@reticlehq/server 3.5.0 → 3.7.0

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

@@ -0,0 +1,120 @@
+/**
+ * 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';
+import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+import { callingClientDirectory } from '../../hooks/client-directory.js';
+/** 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.'),
+};
+/**
+ * Wire the calling project when another project's tab is the one currently connected.
+ *
+ * The list handler only used to reach {@link emptySessionList} when the daemon's whole list was
+ * empty. A live tab in project A then answered project B's first call with A's sessions, and B
+ * was never wired.
+ */
+export async function wireCallerBesideLiveSessions(deps, sessions) {
+    const dir = callingClientDirectory();
+    if (dir === undefined)
+        return undefined;
+    const projectId = readProjectId(dir);
+    if (projectId !== undefined && sessions.some((session) => session.projectId === projectId)) {
+        return undefined;
+    }
+    const next = deps.sessions.noSessionNextAction();
+    const target = next !== undefined && FIRST_RUN_ACTIONS.has(next.action)
+        ? deps.firstRun?.projectDirectory(dir)
+        : undefined;
+    if (target === undefined || deps.firstRun === undefined)
+        return undefined;
+    return deps.firstRun.wire(target);
+}
+/** The departed tab for this call: the caller's own project when it named one, else the daemon's newest. */
+function departedForCaller(deps) {
+    const dir = callingClientDirectory();
+    if (dir === undefined)
+        return deps.sessions.lastKnown?.();
+    const projectId = readProjectId(dir);
+    if (projectId === undefined)
+        return undefined;
+    return deps.sessions.lastKnownFor?.(projectId);
+}
+export async function emptySessionList(deps, sessions) {
+    // The lead and its next action: the full differential (~3 KB of ranked causes) read as
+    // speculation on the call an agent makes first. Optional-call: test stubs predate the lead.
+    const why = deps.sessions.noSessionLead?.() ?? 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 the client is in, not the directory the daemon was started in.
+    // One daemon serves every project; the proxy names its cwd on the call. With no caller (an
+    // embed, a test) it is still the daemon's own project. A daemon outside any project asks instead.
+    // ponytail: cwd, not an MCP roots/list round trip. A proxy started outside the project still
+    // answers run_init; roots are the upgrade when a client launches there but names the project.
+    // 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(callingClientDirectory() ?? 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 = departedForCaller(deps);
+    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

@@ -18,6 +18,7 @@ export declare const RECOVERY: {
     readonly MISSING_BASELINE: string;
     readonly MISSING_RECORDING: string;
     readonly STALE_REF: string;
+    readonly UNISSUED_REF: string;
     readonly STALE_REF_AFTER_EDIT: string;
     readonly INVALID_NAME: string;
     /**
@@ -66,12 +67,25 @@ 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
      * who deliberately switched the harness off gets a bug report filed about their own decision.
      */
     readonly HARNESS_OFF: string;
+    /**
+     * 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.
+     */
+    readonly HARNESS_LOCKED: string;
+    readonly HARNESS_NOT_LINKED: string;
 };
 /**
  * The actionable next move for a known error message, or undefined when none is recognized.

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

@@ -8,9 +8,11 @@
  * 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, UNISSUED_REF_REFUSAL } 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 { 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. */
 const ELISION = '… [elided] …';
 /**
@@ -33,11 +35,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,7 +59,22 @@ 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 },
 ];
+/**
+ * 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))
@@ -80,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 ' +
@@ -199,15 +235,38 @@ 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
      * 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`.
@@ -227,11 +286,14 @@ 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,
     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
@@ -247,11 +309,23 @@ 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
+    // 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 },
@@ -260,14 +334,31 @@ 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).
     {
-        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 },
@@ -364,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) {
@@ -382,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))
@@ -505,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,5 +10,35 @@
  * 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 { 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.
+ *
+ * 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, planId?: string, 
+/** The person who started it acknowledged the saved flows' destructive steps. */
+confirmDangerous?: boolean): Promise<RemoteDriveOutcome>;