@reticlehq/server 3.4.0 → 3.6.0

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

@@ -29,6 +29,17 @@ function unknownParamsError(toolName, unknown) {
 const TOOLS_LIST_ACTION = 'list';
 /** What to write instead — the one parameter reticle_tools declares, and the no-argument form. */
 const TOOLS_ARG_HINT = 'name the tools you want in `names`: reticle_tools { names: ["reticle_act_and_wait"] } — or call it with no arguments for the full catalog';
+/**
+ * The refusal for arguments of the wrong type, naming each offending key and what it declared.
+ * `path` is joined for a nested value (`intents.0.id`); a missing required key reads as the key.
+ */
+function invalidParamsError(toolName, issues) {
+    const named = issues.map((issue) => {
+        const where = 0 === issue.path.length ? '(arguments)' : issue.path.join('.');
+        return `${where} (${issue.message})`;
+    });
+    return `invalid ${1 === named.length ? 'parameter' : 'parameters'} for ${toolName}: ${named.join('; ')} — NOT applied, so any result would be an answer to a different question`;
+}
 /** The keys not declared by `shape`, in call order. */
 function unknownKeys(args, shape) {
     const declared = new Set(Object.keys(shape));
@@ -263,8 +274,24 @@ callable) {
                     hint: 'fix the arguments and call reticle_run again',
                 };
             }
+            // Keys are not enough: the TYPES are the other half of what a direct call's SDK validation
+            // refuses. Unchecked here, `reticle_viewport { width: "1440" }` from a client that stringifies
+            // numbers reached the handler, which read a non-number as missing and set the page to 64x64,
+            // and `reticle_intent { action: "declare", intents: "[...]" }` stored nothing and answered
+            // `{ intents: [] }` (#1118). The parsed value goes on, as it does on the direct path, so a
+            // schema's defaults and transforms apply the same way through either door.
+            const typed = z.object(target.inputSchema).safeParse(callArgs);
+            if (!typed.success) {
+                return {
+                    error: invalidParamsError(name, typed.error.issues),
+                    tool: name,
+                    params: paramInfo(target.inputSchema),
+                    ...(target.example === undefined ? {} : { example: target.example }),
+                    hint: 'fix the arguments and call reticle_run again',
+                };
+            }
             try {
-                return await runTool(target, deps, callArgs);
+                return await runTool(target, deps, typed.data);
             }
             catch (error) {
                 // The SAME payload the direct tool path builds — recovery included. Answering every failure
@@ -272,7 +299,7 @@ callable) {
                 // is reached through here: a stale ref, a paused session, a missing pairing token all came
                 // back as the agent's arguments being wrong, which is advice that spends the retry.
                 const message = error instanceof Error ? error.message : String(error);
-                return { ...takeVersionSkewOnto(buildErrorPayload(message)), tool: name };
+                return { ...takeVersionSkewOnto(buildErrorPayload(message), deps.peerSkew), tool: name };
             }
         },
     };

package/dist/surface/tools/empty-session-list.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { ToolDeps } from './tool-kit.js';
+/** The fields only an empty list carries, declared so a schema-aware client does not strip them. */
+export declare const EMPTY_SESSION_LIST_OUTPUT: {
+    why: z.ZodOptional<z.ZodString>;
+    next_action: z.ZodOptional<z.ZodObject<{
+        action: z.ZodNativeEnum<{
+            readonly START_DEV_SERVER: "start_dev_server";
+            readonly RUN_INIT: "run_init";
+            readonly OPEN_APP: "open_app";
+            readonly REOPEN_APP: "reopen_app";
+            readonly DAEMON_SPLIT: "daemon_split";
+        }>;
+        command: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        action: "start_dev_server" | "run_init" | "open_app" | "reopen_app" | "daemon_split";
+        reason: string;
+        port?: number | undefined;
+        command?: string | undefined;
+    }, {
+        action: "start_dev_server" | "run_init" | "open_app" | "reopen_app" | "daemon_split";
+        reason: string;
+        port?: number | undefined;
+        command?: string | undefined;
+    }>>;
+    talk_to_us: z.ZodOptional<z.ZodString>;
+    wired: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    lastKnown: z.ZodOptional<z.ZodObject<{
+        sessionId: z.ZodString;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        url: string;
+    }, {
+        sessionId: string;
+        url: string;
+    }>>;
+};
+export declare function emptySessionList(deps: ToolDeps, sessions: unknown[]): Promise<Record<string, unknown>>;

package/dist/surface/tools/empty-session-list.js

@@ -0,0 +1,80 @@
+/**
+ * What `reticle_session { action: "list" }` answers when nothing is connected.
+ *
+ * An empty list is the most common thing that tool returns, and on its own it is a dead end: the
+ * agent asked the one question it knows to ask and got no next step. So it carries why nothing is
+ * connected, the executable next action, the last tab that was here, and, on a project that has
+ * never connected, the first-run wiring itself (see first-run-wiring.ts).
+ */
+import { dirname } from 'node:path';
+import { z } from 'zod';
+import { DiscoveryInvite, NoSessionAction } from '@reticlehq/core';
+/** The answers that mean "this app is not set up yet", which a first run can settle by wiring it. */
+const FIRST_RUN_ACTIONS = new Set([
+    NoSessionAction.RUN_INIT,
+    NoSessionAction.START_DEV_SERVER,
+    NoSessionAction.OPEN_APP,
+]);
+/** The fields only an empty list carries, declared so a schema-aware client does not strip them. */
+export const EMPTY_SESSION_LIST_OUTPUT = {
+    why: z
+        .string()
+        .optional()
+        .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
+    next_action: z
+        .object({
+        action: z.nativeEnum(NoSessionAction),
+        command: z.string().optional(),
+        port: z.number().optional(),
+        reason: z.string(),
+    })
+        .optional()
+        .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
+    talk_to_us: z
+        .string()
+        .optional()
+        .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
+    wired: z
+        .record(z.unknown())
+        .optional()
+        .describe('Files the first run changed (`steps`); tell the user.'),
+    lastKnown: z
+        .object({
+        sessionId: z.string(),
+        url: z.string(),
+    })
+        .optional()
+        .describe('Present ONLY when `sessions` is empty AND a tab was connected to this daemon earlier: the last sessionId and URL that tab was on when it disappeared. A route that 500s tears the page down and the SDK never reconnects — this is the last thing we knew, not a route-500 verdict. An empty list with no lastKnown is a tab that never arrived.'),
+};
+export async function emptySessionList(deps, sessions) {
+    const why = deps.sessions.noSessionHint();
+    // The executable half. `why` is for the human reading the transcript; this is the one the
+    // agent acts on, so it never has to parse a paragraph to find a command inside it.
+    const next = deps.sessions.noSessionNextAction();
+    // The first run wires the app, not the installation: the daemon runs init itself, once,
+    // in its own project, and says what it changed. A daemon outside any project asks instead.
+    // Not only on `run_init`: an unwired app whose dev server is not running yet answers
+    // `start_dev_server`, which is the commonest first run of all, and init starts that server itself.
+    // `projectDirectory` refuses a project that is already wired, so a wired app is never re-run.
+    const dir = next !== undefined && FIRST_RUN_ACTIONS.has(next.action)
+        ? deps.firstRun?.projectDirectory(dirname(deps.reticleRoot))
+        : undefined;
+    if (dir !== undefined && deps.firstRun !== undefined) {
+        const wired = await deps.firstRun.wire(dir);
+        const connected = deps.sessions.list();
+        if (wired.ok && 0 < connected.length)
+            return { sessions: connected, wired };
+        return { sessions, wired, ...(why === undefined ? {} : { why }) };
+    }
+    // The last tab, when one was here. Optional-call: test stubs of SessionManager predate it.
+    const known = deps.sessions.lastKnown?.();
+    const lastKnown = undefined === known ? undefined : { sessionId: known.id, url: known.url };
+    return {
+        sessions,
+        ...(why === undefined ? {} : { why }),
+        ...(next === undefined ? {} : { next_action: next }),
+        ...(undefined === lastKnown ? {} : { lastKnown }),
+        // Setup that never connects is where most people give up; it is the talk worth having.
+        talk_to_us: DiscoveryInvite.AGENT,
+    };
+}

package/dist/surface/tools/error-recovery.d.ts

@@ -66,6 +66,12 @@ export declare const RECOVERY: {
     readonly COMMAND_TIMEOUT: string;
     readonly FLOW_STEP_MISSING: string;
     readonly NO_POOL: string;
+    /**
+     * RETICLE_CHROMIUM_PATH names a browser the daemon cannot launch. The call was fine and so is the
+     * Playwright install, so neither a retry nor the install command can help: only the daemon's own
+     * environment can, and a running daemon keeps the values it started with.
+     */
+    readonly CHROMIUM_PATH: string;
     /**
      * The two ways a platform answer can refuse a drive. Neither is a fault, and both were telling the
      * agent that a perfectly understood refusal might be a defect in Reticle — which is how a person

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

@@ -8,9 +8,10 @@
  * 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, TRANSPORT_LIMITS } from '@reticlehq/core';
+import { RefusalReason, ReticleEnv, TRANSPORT_LIMITS } from '@reticlehq/core';
 import { SELF_RECOVERING_MARKER } from '../../portal/session/no-session-diagnosis.js';
-import { chromiumInstallCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.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. */
 const ELISION = '… [elided] …';
 /**
@@ -33,11 +34,21 @@ function capMessage(message) {
     const keep = Math.floor((max - ELISION.length) / 2);
     return `${message.slice(0, keep)}${ELISION}${message.slice(message.length - keep)}`;
 }
+/**
+ * A fixed phrase as a pattern for the table below, which matches on phrasing.
+ *
+ * The phrase comes from the module that throws it rather than being retyped here, and a constant is
+ * still text: escaped so a future reword containing `(` or `?` cannot turn into a pattern that means
+ * something else — or fails to compile at import time, taking the whole surface with it.
+ */
+function literally(phrase) {
+    return new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i');
+}
 /**
  * Messages that already spell out the exact retry, so any hint we add can only argue with them.
  *
  * The no-session diagnosis is one (it inspected the machine and named the cause). The native-input
- * refusal is the other: it names the tool, the argument and the follow-up call to make instead — and
+ * refusal is another: it names the tool, the argument and the follow-up call to make instead — and
  * it was still collecting the defect ask, inviting a bug report about a refusal that had just told
  * the agent precisely what to do.
  */
@@ -47,6 +58,11 @@ const SELF_RECOVERING = [
     // the current ids" to a message that just named them contradicts the shorter path it offers, and
     // a contradicted instruction is how one agent came to retry a dead id twelve times.
     { match: /Connected right now:/i, reason: RefusalReason.NO_SESSION },
+    // The body-clause pre-flight: nothing ran, no action was spent, and the message names the setting
+    // to switch on — or says the page's SDK predates it, which is a limit and not a defect either. It
+    // was collecting the defect ask on top of its own remedy, so the envelope contradicted itself and
+    // asked for a bug report about somebody's connect() options.
+    { match: literally(BODY_CLAUSE_REFUSAL_OPENING), reason: RefusalReason.UNSUPPORTED },
 ];
 /** A message that already carries its own concrete next action, so nothing should be appended. */
 function isSelfRecovering(message) {
@@ -199,6 +215,17 @@ export const RECOVERY = {
         chromiumInstallCommand(bundledPlaywrightVersion()) +
         '` if that is what is missing. Meanwhile drive ' +
         'a tab the human already has open — reticle_sessions lists them.',
+    /**
+     * RETICLE_CHROMIUM_PATH names a browser the daemon cannot launch. The call was fine and so is the
+     * Playwright install, so neither a retry nor the install command can help: only the daemon's own
+     * environment can, and a running daemon keeps the values it started with.
+     */
+    CHROMIUM_PATH: `Reticle cannot launch the browser ${ReticleEnv.CHROMIUM_PATH} names (the message above says ` +
+        'what is wrong with the path). The call itself was fine, so retrying it will not help, and ' +
+        'neither will installing Chromium. Ask the human to fix that path, or unset it to use ' +
+        "Playwright's own Chromium, in the environment the daemon starts from, then run " +
+        '`npx @reticlehq/server restart`. Meanwhile drive a tab the human already has open, which ' +
+        'reticle_sessions lists. This is configuration, not a Reticle defect: there is nothing to report.',
     /**
      * The two ways a platform answer can refuse a drive. Neither is a fault, and both were telling the
      * agent that a perfectly understood refusal might be a defect in Reticle — which is how a person
@@ -227,6 +254,7 @@ const REASON_OF = {
     THROTTLED: RefusalReason.NOT_READY,
     COMMAND_TIMEOUT: RefusalReason.NOT_READY,
     NO_POOL: RefusalReason.NOT_READY,
+    CHROMIUM_PATH: RefusalReason.NOT_READY,
     TOKEN_REQUIRED: RefusalReason.NOT_READY,
     MISSING_BASELINE: RefusalReason.NO_MATCH,
     MISSING_RECORDING: RefusalReason.NO_MATCH,
@@ -252,6 +280,11 @@ const REASON_OF = {
 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 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
+    // its call failed the schema. Not anchored, so a launch error that wraps it is still caught. The
+    // prefix has no regex metacharacters, so it is used as is.
+    { match: new RegExp(CHROMIUM_PATH_REFUSAL_PREFIX), hint: RECOVERY.CHROMIUM_PATH },
     { match: /no browser session connected/i, hint: RECOVERY.NO_SESSION },
     { match: /multiple sessions connected/i, hint: RECOVERY.MULTIPLE_SESSIONS },
     { match: /no connected session with id/i, hint: RECOVERY.UNKNOWN_SESSION },
@@ -267,7 +300,7 @@ const RULES = [
     // 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).
     {
-        match: /scope mismatch|session\(s\) ARE connected under a different project/i,
+        match: /scope mismatch|session\(s\) ARE connected (?:under a different project|with no projectId)/i,
         hint: RECOVERY.SCOPE_MISMATCH,
     },
     { match: /^session disconnected$|session .* never connected/i, hint: RECOVERY.SESSION_GONE },
@@ -293,8 +326,7 @@ const RULES = [
     { match: /contenteditable/i, hint: RECOVERY.UNSUPPORTED_SURFACE },
     { match: /cannot hover without a real pointer/i, hint: RECOVERY.HOVER_NEEDS_POINTER },
     { match: /cannot \w+ a (disabled|readonly) </i, hint: RECOVERY.NOT_EDITABLE },
-    // Three spellings ship — "action", "native action", "WebMCP tool" — and the rule matched one, so
-    // two thirds of the same deliberate refusal still read as a possible defect.
+    // Both "action" and "native action" refusals need the same confirmation guidance.
     {
         match: /potentially destructive (?:\w+ )*(?:action|tool) blocked/i,
         hint: RECOVERY.CONFIRM_DANGEROUS,

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

@@ -10,5 +10,14 @@
  * 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 } from './tool-kit.js';
+import type { ToolDef, ToolDeps } from './tool-kit.js';
+import { type RemoteDriveOutcome } from '../../features/harness/platform/remote-drive.js';
 export declare const EXPLORE_TOOLS: ToolDef[];
+/**
+ * A drive the platform's chat asked for, run as the very tool an agent would call.
+ *
+ * Through `runTool`, not a second path to `exploreApp`: a dispatch that skips it is a drive nobody
+ * 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>;

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

@@ -11,28 +11,28 @@
  * them deterministically with no model in the loop at all.
  */
 import { z } from 'zod';
+import { unprovedGoals } from '../../features/harness/goals.js';
 import { ReticleTool, asRecord } from '@reticlehq/core';
 import { stepCountSchema } from './args/numeric-bounds.js';
+import { runTool } from './invoke-tool.js';
+import { driveVerdict } from '../../features/harness/platform/remote-drive.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 { EXPLORE_NEEDS } from '../../features/harness/drivers.js';
+import { checkTally, 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.',
+        description: 'Drive the app yourself? Do not — call this instead. The Reticle Harness drives it through this same tool surface (it decides on the Reticle platform, this daemon executes each step), 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 Harness credits. ' +
+            EXPLORE_NEEDS,
         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.'),
+                .describe('The journey in plain words; any "quoted text" must be on the page when it ends (checked).'),
             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.'),
+                .describe('Ceiling on model turns; the drive is graded however it ends.'),
             sessionId: z
                 .string()
                 .optional()
@@ -47,6 +47,21 @@ export const EXPLORE_TOOLS = [
             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()),
+            /** Saved flows with no step that asserts anything: their replay verifies nothing. */
+            unverifiedFlows: z.array(z.string()),
+            /** Whether the drive ran at least one check. A drive that did not proved nothing. */
+            proved: z.boolean(),
+            /**
+             * Whether every journey reached its goal, as the platform judged when the drive finished.
+             * Absent when no journey's goal was judged. Checks that held are not the goal reached.
+             */
+            goalMet: z.boolean().optional(),
+            /** How the drive's checks came out, one per control and claim at its worst. */
+            checks: z.object({ held: z.number(), failed: z.number(), undecided: z.number() }),
+            /** The runs this drive syncs as (`harness-<uuid>`): what the platform links its check to. */
+            runIds: z.array(z.string()).optional(),
+            /** One verdict per requested goal, checked by the harness itself. Only `yes` is proved. */
+            goals: z.array(z.object({ text: z.string(), verified: 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
@@ -81,12 +96,10 @@ export const EXPLORE_TOOLS = [
             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, {
+            const { drive, savedFlows, rewroteFlows, unverifiedFlows, driverName, plan, goals, planLines, runIds, } = 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,
@@ -94,11 +107,19 @@ export const EXPLORE_TOOLS = [
                 steps: drive.steps,
                 savedFlows: [...savedFlows],
                 rewroteFlows: [...rewroteFlows],
+                unverifiedFlows: [...unverifiedFlows],
+                proved: drive.proved,
+                checks: checkTally(drive.toolCalls),
+                ...(drive.goalMet === undefined ? {} : { goalMet: drive.goalMet }),
+                ...(runIds === undefined ? {} : { runIds: [...runIds] }),
+                goals: [...goals],
                 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]),
+                    ...(planLines ?? []),
+                    describeDrive(drive.toolCalls, [...savedFlows, ...rewroteFlows], unverifiedFlows),
+                    ...[unprovedGoals(goals)].filter((line) => line !== undefined),
                     ...(0 === drive.summary.length ? [] : [`The driver's own account: ${drive.summary}`]),
                 ].join('\n'),
                 ...(drive.error === undefined ? {} : { error: drive.error }),
@@ -159,4 +180,52 @@ const NOTHING_RECORDED = {
     [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.',
+    [StopReason.STOPPED]: 'Autonomous driving was switched off before the drive saved anything. Nothing is proved; switch it back on to drive again.',
 };
+/**
+ * A drive the platform's chat asked for, run as the very tool an agent would call.
+ *
+ * Through `runTool`, not a second path to `exploreApp`: a dispatch that skips it is a drive nobody
+ * 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 async function driveForChat(deps, goal, sessionId) {
+    const explore = EXPLORE_TOOLS.find((tool) => ReticleTool.VERIFY_EXPLORE === tool.name);
+    if (explore === undefined)
+        throw new Error('this build has no Harness drive');
+    const out = asRecord(await runTool(explore, deps, {
+        persona: goal,
+        ...(sessionId === undefined ? {} : { sessionId }),
+    }));
+    const summary = 'string' === typeof out['summary'] ? out['summary'] : '';
+    const error = 'string' === typeof out['error'] ? out['error'] : undefined;
+    const note = 'string' === typeof out['note'] ? out['note'] : undefined;
+    const goals = Array.isArray(out['goals'])
+        ? out['goals'].flatMap((g) => {
+            const verified = asRecord(g)['verified'];
+            return 'string' === typeof verified ? [{ verified }] : [];
+        })
+        : [];
+    const goalMet = out['goalMet'];
+    const tally = asRecord(out['checks']);
+    const count = (key) => ('number' === typeof tally[key] ? tally[key] : 0);
+    const checks = { held: count('held'), failed: count('failed'), undecided: count('undecided') };
+    const runIds = Array.isArray(out['runIds'])
+        ? out['runIds'].filter((id) => 'string' === typeof id)
+        : [];
+    return {
+        // Only a drive that ran a check and did not break counts as one that proved anything.
+        ok: true === out['proved'] && error === undefined,
+        ...(0 === runIds.length ? {} : { runIds }),
+        verdict: driveVerdict({
+            proved: true === out['proved'],
+            checks,
+            goals,
+            ...(error === undefined ? {} : { error }),
+            ...('boolean' === typeof goalMet ? { goalMet } : {}),
+        }),
+        summary: [summary, note, error === undefined ? undefined : `Error: ${error}`]
+            .filter((line) => line !== undefined && 0 < line.length)
+            .join('\n'),
+    };
+}

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

@@ -17,6 +17,17 @@ import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { submitFeedback, feedbackDisabled } from '../../telemetry/feedback.js';
 import { getTelemetry } from '../../telemetry/telemetry.js';
+import { dirname } from 'node:path';
+import { sessionRoot } from '../../memory/project/session-root.js';
+/** The project folder this call's session belongs to, when one can be told. */
+function projectDir(deps, sessionId) {
+    try {
+        return { cwd: dirname(sessionRoot(deps, sessionId)) };
+    }
+    catch {
+        return {};
+    }
+}
 /** One optional string arg, present only when the agent actually supplied it. */
 function optionalText(args, key) {
     const value = asString(args[key]);
@@ -175,6 +186,9 @@ export const FEEDBACK_TOOLS = [
                 ...optionalRating(args),
             }, {
                 session: sessionFacts(deps, asString(args['sessionId'])),
+                // A report that cannot be sent is written into the project being verified, never into
+                // whatever folder the daemon happened to start in.
+                ...projectDir(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,