@reticlehq/server 3.9.0 → 3.10.1

package/dist/command/cli/cli-usage.js

@@ -43,17 +43,53 @@ the first flow. It never drives: the Harness is opt-in and runs at any instrumen
 const VERIFY_DETAIL = `Drives the URL and verifies the saved flows. Exit 0 means every one passed.
 
   --explore [--persona <who>]   no saved flows? let Reticle drive the app and record them
+  --against <reference-url>     compare the URL with a reference build: drive both with the same
+                                actions, and report each difference in what users see (exit 1)
   --select <label>              repeatable: verify only flows carrying these labels
   --results-json <file>         also write one verdict per journey as JSON, for CI
   --confirm-dangerous           this run may press what the replay guard holds as destructive
+  --require-start-control       fail a flow whose first control is not on its freshly loaded start page
+  --sweep                       judge every step, also after one fails (the results score counts them all)
   --storage-state <file>        start signed in
-  --session-id <id>, --timeout N, --headed, --port N
+  --session-id <id>, --timeout <ms>, --headed, --port N
   --expect '<json predicate>' | --expect-file <path>
                                 one verdict, no saved flows needed. Asks a running daemon,
                                 never starts one, and waits up to --timeout ms (default 4000)
                                 for it to come true. Exit 0 only on verified:"yes". For an
                                 action --expect cannot do, use the HTTP MCP transport:
                                 https://docs.reticle.sh/http-transport.md`;
+const GRADE_DETAIL = `Grades a finished run of an app from snapshots of its stored data. It needs no
+daemon and no browser.
+
+  grade snapshot --state <file> --out <file> [--url <url>]
+      read the declared state sources (and the page the run ended on) into a snapshot
+  grade judge --reference <file> --again <file> --candidate <file>
+              [--expect <file>] [--answer <text>] [--json]
+      compare the candidate snapshot with two snapshots of the correct run. A line that
+      differs between the two correct runs is ignored. --expect declares a source whose
+      rows are the correct answer, read now. Exit 0 = pass, 1 = fail, 2 = unverified
+  grade tables --list <command> --rows <template> [--container <name>] [--skip <prefix,...>]
+               --out <file>
+      write a declaration with one source for each table; {table} in the template is
+      the table name; --skip leaves out the tables whose name starts with a prefix
+  grade suggest --state <file> --reference <file> --again <file> --out <file>
+      keep only the sources that read the same on two correct runs`;
+const COMPARE_DETAIL = `Drives two running builds of one app the same way, for example main and a pull request
+preview, and reports each difference in what a person sees and in the requests and console
+errors the app made. Install nothing in the app.
+
+It plans every action on every control of the reference, drives the plan on the reference two
+times and on the candidate one time, and ignores what changes between the two reference runs.
+Point it at builds whose data you can change: it presses every button it finds.
+
+  --base <url>     the build before the change: tag each difference as a regression, a missed
+                   target or a change, and print a score
+  --state <file>   a JSON file { "sources": [...] } that declares how to read the app's stored
+                   data (kind command, http or file). Compare reads it after each sequence on
+                   every build, so a change to a record that no page shows is a difference.
+                   Start each row with the record id, so a changed row names its record
+  --json           print one JSON object
+Exit 0 = same, 1 = different, 2 = the run proves nothing (a lost browser session, or an error).`;
 const BROWSER_NOTE = `The browser Reticle opens for your agent is shown so you can watch the run. --headless hides
 it; CI, RETICLE_HEADLESS=1, or a Linux machine with no display hides it too.`;
 /** What `--http` starts. MCP is already on the bridge port; this flag is the verify endpoint. */
@@ -96,16 +132,32 @@ const COMMANDS = [
         group: HelpGroup.CHECK,
         detail: VERIFY_DETAIL,
     },
+    {
+        name: 'compare',
+        synopsis: 'compare <reference-url> <candidate-url> [--base <url>] [--state <file>] [--json] [--report <file>]',
+        summary: 'Drive two builds the same way and list what users would see change',
+        group: HelpGroup.CHECK,
+        detail: COMPARE_DETAIL,
+    },
+    {
+        name: 'grade',
+        synopsis: 'grade <snapshot|judge|tables|suggest> [flags]',
+        summary: "Grade a finished run from snapshots of the app's stored data",
+        group: HelpGroup.MORE,
+        detail: GRADE_DETAIL,
+    },
     {
         name: 'gate',
-        synopsis: 'gate [--since <ref>] [--accept-coverage] [--hook] [file...]',
+        synopsis: 'gate [--list] [--since <ref>] [--accept-coverage] [--hook] [file...]',
         summary: 'Fail unless passing checks cover the flows your changes touch',
         group: HelpGroup.CHECK,
+        detail: '--list names the saved flows your changes touch, and checks nothing.',
     },
     {
         name: 'status',
         synopsis: 'status [--json] [--port N]',
         summary: 'Is Reticle running, is your app connected, are you signed in',
+        detail: 'Shows the enterprise license when a key is set. --json always carries it.',
         group: HelpGroup.MACHINE,
     },
     {
@@ -132,17 +184,12 @@ const COMMANDS = [
             "With --force, frees the port by the Reticle daemon LISTENING on it, never the agent's MCP\n" +
             'proxy, and refuses a listener that is not Reticle.',
     },
-    {
-        name: 'restart',
-        synopsis: 'restart [--force] [--port N]',
-        summary: 'Stop Reticle, then start it and wait until it is listening',
-        group: HelpGroup.MACHINE,
-    },
     {
         name: 'update',
-        synopsis: 'update',
+        synopsis: 'update [--rollback]',
         summary: 'Install the latest version and restart',
         group: HelpGroup.MACHINE,
+        detail: '--rollback restores the previous version and restarts.',
     },
     {
         name: 'logout',
@@ -170,7 +217,7 @@ const COMMANDS = [
         synopsis: 'sync [--watch] [--move-history]',
         summary: 'Send local runs to the dashboard and collect decisions',
         group: HelpGroup.MORE,
-        detail: '`reticle push` is the same command.\n\n  --watch          keep sending as runs are written\n' +
+        detail: '  --watch          keep sending as runs are written\n' +
             '  --move-history   also send runs, flows and records made under the previous link',
     },
     {
@@ -191,12 +238,6 @@ const COMMANDS = [
         summary: 'What this project sends to the dashboard',
         group: HelpGroup.MORE,
     },
-    {
-        name: 'affected',
-        synopsis: 'affected [--since <ref>] [file...]',
-        summary: 'Which saved flows must re-verify for the changed files',
-        group: HelpGroup.MORE,
-    },
     {
         name: 'report',
         synopsis: 'report [--session <id>] [--hook]',
@@ -236,7 +277,7 @@ const COMMANDS = [
         synopsis: 'serve [--port N] [--drive <url>] [--headless] [--headed] [--http] [--http-port N] [--http-token T]',
         summary: 'Start the daemon in the background; returns once it answers',
         group: HelpGroup.MORE,
-        detail: DAEMON_DETAIL,
+        detail: `--restart [--force] stops Reticle, then starts it and waits until it listens.\n\n${DAEMON_DETAIL}`,
     },
     {
         name: 'drive',
@@ -250,18 +291,6 @@ const COMMANDS = [
         summary: 'Register the MCP server with the coding agents on this machine',
         group: HelpGroup.MORE,
     },
-    {
-        name: 'license',
-        synopsis: 'license',
-        summary: 'Show the enterprise license status',
-        group: HelpGroup.MORE,
-    },
-    {
-        name: 'rollback',
-        synopsis: 'rollback',
-        summary: 'Restore the previous version and restart',
-        group: HelpGroup.MORE,
-    },
     {
         name: 'version',
         synopsis: 'version',

package/dist/command/cli/cli-verify.d.ts

@@ -39,6 +39,11 @@ export interface VerifyConnection {
      * only the connection can read one.
      */
     listFlows(select?: readonly string[]): Promise<string[]>;
+    /**
+     * Each named flow's saved step count, for the results score: without it a replay that stopped at
+     * step 2 of 10 reads as a 2-step journey. Optional; a name it cannot read is left out.
+     */
+    plannedSteps?(names: readonly string[]): Promise<ReadonlyMap<string, number>>;
     /**
      * Drive the app with a model and save what it drove. Present only when a model is configured.
      *
@@ -190,8 +195,8 @@ export declare function routeVerify(args: {
     hasPredicate: boolean;
     /**
      * True when the caller asked for something only a browser of OUR OWN can do: `--headed` or
-     * `--storage-state`. The running daemon's tab can honour neither, so replaying there would
-     * silently ignore the request.
+     * `--storage-state`, or a rule its replay tool does not take (`--require-start-control`). The
+     * running daemon's tab can honour none of them, so replaying there would silently ignore the request.
      */
     wantsOwnBrowser?: boolean;
     /**
@@ -230,6 +235,10 @@ export declare function handleVerify(parsed: {
     resultsJson?: string;
     /** Acknowledge the replay guard's destructive steps ("Place order") for this run only. */
     confirmDangerous?: boolean;
+    /** Fail a flow whose step 1 control is missing on its freshly loaded start page. */
+    requireStartControl?: boolean;
+    /** Judge every step, also after one fails. */
+    sweep?: boolean;
 }, 
 /**
  * Called once, after the last verdict line and before the exit. `cli.ts` passes the CI line:

package/dist/command/cli/cli-verify.js

@@ -12,6 +12,7 @@
 import { cliRunAuthor } from '../../judgement/runs/verification-sync.js';
 import { join, basename } from 'node:path';
 import { readFileSync } from 'node:fs';
+import { noSessionMessage } from './verify-no-session.js';
 import { runAdhocVerdict } from './adhoc-verdict.js';
 import { callerArtifactRoot } from '../../memory/project/link-directory.js';
 import { verifyResults } from './verify-results.js';
@@ -59,9 +60,6 @@ const DEFAULT_PROJECT_NAME = 'app';
 export function verifyProjectName(linked, configured, folder) {
     return linked ?? configured ?? (folder || DEFAULT_PROJECT_NAME);
 }
-const MSG_NO_SESSION = 'No app connected: Reticle drove the URL but no @reticlehq/browser session dialed back.\n' +
-    '  Make sure the SDK is in the build and reticle.connect() runs on the preview page' +
-    ' (for a non-localhost preview: allowNonLocalhost + a pairing token).';
 const MSG_NO_FLOWS = 'No saved flows to verify (.reticle/flows is empty), so refusing to report a pass for verifying nothing.\n' +
     '  Flows are recorded interactively by an agent (reticle_record{action:"start"} → act → reticle_flow_save via the\n' +
     '  MCP tools), then committed to .reticle/flows/. In CI, check those files in and re-run `reticle verify`.\n' +
@@ -104,7 +102,7 @@ export async function runVerify(args, outer) {
     try {
         const ready = await conn.sessionReady(args.timeoutMs);
         if (!ready) {
-            ports.fail(MSG_NO_SESSION);
+            ports.fail(noSessionMessage(args.timeoutMs));
             ports.exit(EXIT_FAIL);
             return;
         }
@@ -182,7 +180,7 @@ export async function runVerify(args, outer) {
         // The run's OWN injected timestamp — no wall clock is read in this path (rule 7).
         [{ phase: VerifyPhase.PUSHED, at: run.createdAt }], cloud, cloudFetch).catch(() => undefined);
         if (args.resultsJson !== undefined && ports.writeResults !== undefined) {
-            await ports.writeResults(args.resultsJson, `${JSON.stringify(verifyResults(run, pushed), null, 2)}\n`);
+            await ports.writeResults(args.resultsJson, `${JSON.stringify(verifyResults(run, pushed, (await conn.plannedSteps?.(run.flows.map((f) => f.name))) ?? new Map()), null, 2)}\n`);
         }
         ports.out(renderRunReport(run));
         ports.exit(run.verdict.status === VerdictStatus.PASS ? EXIT_PASS : EXIT_FAIL);
@@ -352,9 +350,24 @@ async function openLiveConnection(opts) {
     });
     const deps = buildVerifyDeps(running, opts.reticleRoot, opts.now);
     const harnessEnv = await withLinkedCredential(deps, process.env);
-    const runner = new ReticleRunner(createRunnerPort(deps, opts.sessionId, { confirmDangerous: true === opts.confirmDangerous }));
+    const runner = new ReticleRunner(createRunnerPort(deps, opts.sessionId, {
+        confirmDangerous: true === opts.confirmDangerous,
+        requireStartControl: true === opts.requireStartControl,
+        sweep: true === opts.sweep,
+    }));
     return {
         sessionReady: (timeoutMs) => waitForSession(deps.sessions, timeoutMs, opts.now),
+        plannedSteps: async (names) => {
+            const planned = new Map();
+            for (const name of names) {
+                const loaded = await deps.flows.load(name).catch(() => undefined);
+                if (true === loaded?.ok) {
+                    // A sequence counts its sub-steps, as the score does.
+                    planned.set(name, loaded.value.steps.reduce((n, step) => n + (step.steps?.length ?? 1), 0));
+                }
+            }
+            return planned;
+        },
         listFlows: async (select) => select === undefined || 0 === select.length
             ? deps.flows.list()
             : (await resolveSuiteSelection(deps, projectOnly(undefined), { labels: [...select] })).run,
@@ -476,7 +489,7 @@ export function expectNeedsDaemonMessage(port, presence) {
 export function daemonLacksKeyMessage(port) {
     return (`${ReticleEnv.API_KEY} is set in this shell, but the daemon on port ${String(port)} was ` +
         'started without it, and the daemon is what asks the platform to drive. Restart it from this ' +
-        `shell so it inherits the key: npx @reticlehq/server restart --port ${String(port)}`);
+        `shell so it inherits the key: npx @reticlehq/server serve --restart --port ${String(port)}`);
 }
 /** What `verify` does next, once the options and the state of the port are both known. */
 export const VerifyRoute = {
@@ -567,6 +580,8 @@ beforeExit = () => undefined) {
             ...(parsed.storageState !== undefined ? { storageState: parsed.storageState } : {}),
             ...(parsed.sessionId !== undefined ? { sessionId: parsed.sessionId } : {}),
             ...(true === parsed.confirmDangerous ? { confirmDangerous: true } : {}),
+            ...(true === parsed.requireStartControl ? { requireStartControl: true } : {}),
+            ...(true === parsed.sweep ? { sweep: true } : {}),
         }),
         out: (line) => process.stdout.write(`${line}\n`),
         fail: (line) => process.stderr.write(`${line}\n`),
@@ -593,7 +608,11 @@ beforeExit = () => undefined) {
         const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
         const plan = routeVerify({
             hasPredicate: expectation !== undefined,
-            wantsOwnBrowser: !parsed.headless || parsed.storageState !== undefined,
+            // `--require-start-control` too: the daemon's replay tool does not take that rule.
+            wantsOwnBrowser: !parsed.headless ||
+                parsed.storageState !== undefined ||
+                true === parsed.requireStartControl ||
+                true === parsed.sweep,
             explore: true === parsed.explore || parsed.persona !== undefined,
             hasSavedFlows: 0 <
                 (await new FlowStore(createNodeFileSystem(), reticleRoot, { now: Date.now }).list()).length,

package/dist/command/cli/cloud-cli.js

@@ -5,7 +5,6 @@
  * `credentials.json` (per-project api keys from `reticle link`). The non-secret repo binding + sync policy
  * is `<repo>/.reticle/cloud.json`. Auth for a command = `RETICLE_API_KEY` env (agent) OR the login token.
  */
-import { CreatedProjectSchema } from './project-name.js';
 import { keyRefusalAtLastSync } from '../../memory/project/sync-status.js';
 import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
 import { writeHarnessSwitch } from '../../memory/cloud/harness-switch.js';
@@ -24,11 +23,10 @@ import { RETICLE_CONFIG_BASENAME } from './ports/resolve/cli-port.js';
 import { cmdLink, validateKey } from './cloud-link.js';
 // `link` moved to its own module; the CLI entry still imports it from here.
 export { cmdLink } from './cloud-link.js';
-import { normalizeUrl } from './auth/cloud-session.js';
 import { chooseWorkspace, cmdLogin, cmdLogout } from './cloud-login.js';
 import { cmdTry } from './try-command.js';
 import { CLOUD_COMMANDS } from './cli-parse-grammar.js';
-import { api, baseUrl, bearer, emit, err, flags, hint, readJson, readSession, readSessionFor, RETICLE_DIR, } from './cloud-kit.js';
+import { api, baseUrl, emit, err, flags, hint, readJson, readSession, readSessionFor, RETICLE_DIR, } from './cloud-kit.js';
 import { syncRequest } from '../../memory/cloud/cloud-sync.js';
 import { GateExit, gateExitWith } from './answers/gate-exit.js';
 import { brokenOf } from './known-regression.js';
@@ -36,7 +34,7 @@ import { describeUnsyncedBriefly } from '../../memory/cloud/unsynced-roots.js';
 import { machineUnsyncedRoots } from '../../memory/project/sync-status.js';
 import { runSyncCycle } from '../../memory/cloud/sync-cycle.js';
 import { describeSync } from '../../memory/cloud/sync-describe.js';
-import { diskSink, diskSource, policyScreenshots, readCloudIssues, readCloudState, } from '../../memory/cloud/sync-disk.js';
+import { diskSink, diskSource, policyScreenshots, readCloudState, } from '../../memory/cloud/sync-disk.js';
 import { fetchPlatformRun } from '../../features/harness/platform/platform-drives.js';
 import { SERVER_VERSION } from '../version/identity/server-version.js';
 /**
@@ -82,48 +80,6 @@ const linkedRoot = () => {
     const onlyHere = !existsSync(join(project, CLOUD_LINK_FILE)) && existsSync(join(here, CLOUD_LINK_FILE));
     return onlyHere ? here : project;
 };
-/**
- * `reticle whoami` — the one call an agent (or a confused human) makes to know its state: who am I logged
- * in as, and is THIS repo attached to a cloud project (and with what sync policy / verify mode)?
- */
-const cmdWhoami = async () => {
-    const session = await readSession();
-    const fs = createNodeFileSystem();
-    const cloud = await resolveProjectCloud(fs, linkedRoot(), homedir(), process.env);
-    /*
-     * The sync half of "what is my state". Without it the honest answer to "why does the dashboard
-     * look old?" was to go and read a JSON file — and the two failure modes a person actually hits
-     * (nothing has synced yet, and the last attempt errored) looked identical from out here.
-     */
-    const reticleRoot = linkedRoot();
-    const state = readCloudState(reticleRoot);
-    const decisions = Object.keys(readCloudIssues(reticleRoot).triage).length;
-    emit({
-        loggedInAs: session?.orgName ?? null,
-        sync: {
-            lastPushAt: state.lastPushAt ?? null,
-            lastPullAt: state.lastPullAt ?? null,
-            /** Present only when the machine is behind BECAUSE something failed, which is the useful case. */
-            ...(state.lastError === undefined ? {} : { lastError: state.lastError }),
-            /** Decisions collected from the dashboard and readable locally. */
-            decisionsHeld: decisions,
-            neverSynced: state.lastPullAt === undefined,
-        },
-        repo: {
-            attached: cloud.config !== null,
-            projectId: cloud.projectId,
-            url: cloud.config?.url ?? null,
-            sync: cloud.policy,
-            verify: cloud.verify,
-        },
-    });
-    // Signed out, `link` refuses with "run reticle login first"; `connect` does both in one go.
-    if (null === cloud.config)
-        hint(null === session
-            ? 'this repo is not attached — run `reticle connect` (signs in and links in one step)'
-            : 'this repo is not attached — run `reticle connect`');
-    return 0;
-};
 /**
  * Who is signed in and which project this repo is linked to, for `reticle status`. Local files
  * only: status must answer with no network.
@@ -146,58 +102,6 @@ export const accountStatusFields = async () => {
         ...(refused === undefined ? {} : { keyRefused: refused }),
     };
 };
-/** `reticle project ls` / `reticle project create <name>` — key- or session-authed. */
-const cmdProject = async (argv) => {
-    const active = await readSession();
-    const url = baseUrl(active);
-    const session = await readSessionFor(url);
-    const token = bearer(session);
-    if (null === token) {
-        // Name BOTH hosts when there is a session for a different one. "Run reticle login" on its own is
-        // baffling to somebody who just did — the useful fact is that they logged in somewhere else.
-        err(null !== active && normalizeUrl(active.url) !== url
-            ? `signed in to ${normalizeUrl(active.url)}, but this command targets ${url} — run \`reticle connect --url ${url}\`, or set RETICLE_API_KEY`
-            : `not signed in to ${url} — run \`reticle connect --url ${url}\`, or set RETICLE_API_KEY`);
-        return 2;
-    }
-    const sub = argv[0];
-    if ('ls' === sub) {
-        emit(await api('GET', `${url}/v1/projects`, token));
-        return 0;
-    }
-    if ('create' === sub) {
-        const name = argv.slice(1).join(' ').trim();
-        if (0 === name.length) {
-            err('usage: reticle project create <name>');
-            return 2;
-        }
-        const created = CreatedProjectSchema.parse(await api('POST', `${url}/v1/projects`, token, { name }));
-        emit(created);
-        hint(`next: \`reticle connect --project ${created.projectId}\` to bind this repo`);
-        return 0;
-    }
-    if ('rename' === sub) {
-        const id = argv[1];
-        const name = argv.slice(2).join(' ').trim();
-        if (id === undefined || 0 === name.length) {
-            err('usage: reticle project rename <projectId> <new name>');
-            return 2;
-        }
-        emit(await api('PATCH', `${url}/v1/projects/${encodeURIComponent(id)}`, token, { name }));
-        return 0;
-    }
-    if ('rm' === sub || 'delete' === sub) {
-        const id = argv[1];
-        if (id === undefined) {
-            err('usage: reticle project rm <projectId>');
-            return 2;
-        }
-        emit(await api('DELETE', `${url}/v1/projects/${encodeURIComponent(id)}`, token));
-        return 0;
-    }
-    err('usage: reticle project <ls|create <name>|rename <id> <name>|rm <id>>');
-    return 2;
-};
 const NO_INSTALL = '--no-install';
 /** Whether `reticle connect`'s init half installs the packages: not under `--no-install`. */
 export const connectInstalls = (argv) => !argv.includes(NO_INSTALL);
@@ -577,10 +481,6 @@ export const runCloudCommand = async (argv) => {
     const [cmd, ...rest] = argv;
     try {
         switch (cmd) {
-            case 'login':
-                // The linker is passed in rather than imported by cloud-login: login ends by linking and
-                // link needs a session, so the cycle is broken at this one call site.
-                return await cmdLogin(rest, cmdLink);
             case 'connect':
                 return await cmdConnect(rest);
             case 'try':
@@ -590,29 +490,12 @@ export const runCloudCommand = async (argv) => {
                 });
             case 'logout':
                 return await cmdLogout(rest);
-            case 'whoami':
-                return await cmdWhoami();
-            case 'project':
-                return await cmdProject(rest);
-            case 'link':
-                return await cmdLink(rest);
             case 'config':
                 return await cmdConfig(rest);
-            // `push` is the name people type, so it takes `--watch` too: the help and the README say so.
-            case 'push':
-                return await cmdSync(rest);
             case 'sync':
                 return await cmdSync(rest);
             case 'runs':
                 return await cmdRunsFamily(rest);
-            case 'issues':
-                return await cmdIssues(rest);
-            case 'memory':
-                return await cmdMemory(rest);
-            case 'regression':
-                return await cmdRegression();
-            case 'share':
-                return await cmdShare(rest);
             default:
                 err(`unknown cloud command '${cmd ?? ''}'`);
                 return 2;

package/dist/command/cli/daemon-link/daemon-client.d.ts

@@ -0,0 +1,45 @@
+export declare const leaseFailedLine: (url: string) => string;
+/**
+ * Open `url` in a Reticle-leased browser unconditionally: `{ leased }` names the lease, which the
+ * caller hands to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print.
+ * `init`'s connect proof on a machine with no system browser takes this path directly.
+ */
+export declare function acquireLease(caller: ToolCaller, url: string, 
+/** Open it in a window somebody can watch, whatever the daemon was started as. */
+headed?: boolean, 
+/** The `.reticle` the lease's runs belong in: the caller's project, not wherever the page resolves. */
+root?: string): Promise<{
+    leased: string;
+    zeroInstall: boolean;
+} | {
+    failed: string[];
+}>;
+/** Hand back a lease `leaseIfNoTab` opened. Best-effort: an expired lease is already gone. */
+export declare function releaseLease(caller: ToolCaller, sessionId: string): Promise<void>;
+/** The narrow slice of an MCP client this needs — one call, then close. */
+export interface ToolCaller {
+    call(name: string, args: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare function endpointFor(port: number, token: string | undefined): URL;
+export declare function connectOverSse(endpoint: URL): Promise<ToolCaller>;
+/**
+ * The report object an MCP tool result carries, or undefined when the shape is not one.
+ *
+ * `field` is the key that makes a payload the report this caller wants: `verified` for a one-shot
+ * verdict, `status` for a suite. It is a parameter rather than a fixed name because the suite path
+ * reproduced this function's own incident the moment it reused it — the headline printed
+ * `unverifiable` while the JSON under it said `"status":"fail"` with 74 failing flows, because a
+ * suite report has no `verified` key and the text reader would only accept one that did.
+ */
+export declare function verdictOf(result: unknown, field?: string): Record<string, unknown> | undefined;
+/**
+ * The tool's own words when it refused, rather than the envelope carrying them.
+ *
+ * A refusal from these tools is the most useful text they produce — it names the cause and the next
+ * action — and printing the MCP result object around it buries that in JSON escaping. The reader is
+ * at a terminal; give them the sentence.
+ */
+export declare function refusalText(result: unknown): string | undefined;
+/** The payload of a tool result: its structured content, or the JSON object in its text. */
+export declare function payloadOf(result: unknown): Record<string, unknown>;