@reticlehq/server 3.5.0 → 3.7.0

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

@@ -9,22 +9,32 @@
  * so the decision logic — including the two honesty guards (no session, no flows ⇒ never a green pass)
  * — is unit-tested without launching a real browser.
  */
+import { CLI_CLIENT_NAME } from '../../judgement/runs/verification-sync.js';
 import { join, basename } from 'node:path';
 import { readFileSync } from 'node:fs';
 import { runAdhocVerdict } from './adhoc-verdict.js';
+import { callerArtifactRoot } from '../../memory/project/link-directory.js';
+import { verifyResults } from './verify-results.js';
+import { writeFile } from 'node:fs/promises';
 import { runAdhocExplore, runAdhocSuite } from './adhoc-suite.js';
-import { exploreApp, harnessAvailable, MSG_NO_HARNESS_KEY, } from '../../surface/tools/harness-explore.js';
+import { cutOffReason, exploreApp, harnessAvailable, MSG_NO_HARNESS_KEY, withLinkedCredential, } from '../../surface/tools/harness-explore.js';
+import { linkedCloudPort } from '../../memory/cloud/cloud-config.js';
+import { CONNECT } from '../../surface/tools/platform-moment.js';
 import { resolveSuiteSelection } from '../../language/flows/suite-selection.js';
-import { readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../portal/bridge/pairing-token.js';
+import { projectOnly } from '../../memory/project/session-root.js';
+import { configuredPairingToken, nodePairingTokenDeps, readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../portal/bridge/pairing-token.js';
 import { randomUUID } from 'node:crypto';
-import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, VerifyPhase, } from '@reticlehq/core';
+import { MCP_SSE_PATH, MCP_MESSAGE_PATH, RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, VerifyPhase, } from '@reticlehq/core';
 import { start } from '../../index.js';
 import { probePresence, describePresence, PortPresence, } from '../daemon/binding/port-presence.js';
 import { EXPECT_FLAG } from './cli-parse-grammar.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { fetchStatus, summarizeStatus } from '../daemon/binding/daemon-status-probe.js';
 import { cloudFetch, createProgressReporter, syncProgressToCloud, syncRunToCloud, SyncOutcome, } from '../../memory/cloud/cloud-sync.js';
-import { linkedCloudPort } from '../../memory/cloud/cloud-config.js';
+import { readProjectId } from './ports/resolve/cli-port.js';
+import { linkedRunsCloudPort, resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
+import { readDashboardUrl } from '../../memory/project/sync-status.js';
+import { seeRunLine } from '../../memory/project/sync-status.js';
 import { homedir } from 'node:os';
 import { ReticleRunner } from '../../judgement/runs/reticle-runner.js';
 import { createRunnerPort } from '../../judgement/runs/runner-port.js';
@@ -41,7 +51,15 @@ const EXIT_FAIL = 1;
 const DEFAULT_SESSION_TIMEOUT_MS = 15_000;
 const SESSION_POLL_MS = 250;
 const DEFAULT_PROJECT_NAME = 'app';
-const VERIFY_AGENT_ID = 'reticle-cli';
+/**
+ * The project a verify run is named for: the dashboard project this checkout is linked to, else the
+ * id its `.reticle.json` carries, else the folder. A CI run read "ci-repo" on a dashboard whose
+ * project, and the repo's own committed config, said `web-ci`.
+ */
+export function verifyProjectName(linked, configured, folder) {
+    return linked ?? configured ?? (folder || DEFAULT_PROJECT_NAME);
+}
+const VERIFY_AGENT_ID = CLI_CLIENT_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).';
@@ -150,6 +168,9 @@ export async function runVerify(args, ports) {
         await syncProgressToCloud(streamId, 
         // 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), null, 2)}\n`);
+        }
         ports.out(renderRunReport(run));
         ports.exit(run.verdict.status === VerdictStatus.PASS ? EXIT_PASS : EXIT_FAIL);
     }
@@ -176,6 +197,12 @@ async function explore(conn, args, ports) {
     }
     ports.out('No saved flows yet — driving the app to record some.');
     const drive = await conn.explore(args.persona);
+    const cut = cutOffReason(drive);
+    if (cut !== undefined) {
+        ports.fail(cut);
+        ports.exit(EXIT_FAIL);
+        return false;
+    }
     if (0 === drive.savedFlows.length) {
         ports.fail(MSG_EXPLORED_NOTHING);
         ports.exit(EXIT_FAIL);
@@ -192,15 +219,35 @@ async function explore(conn, args, ports) {
  * already reported locally; the cloud copy is an enhancement.
  */
 async function pushRunToCloud(run, config, ports) {
-    if (null === config)
+    if (null === config) {
+        ports.out(`run ${run.runId} was kept on this computer: this repo is not linked, so nothing was sent ` +
+            `to the dashboard. To save runs for your team: ${CONNECT}`);
         return;
+    }
     const result = await syncRunToCloud(run, config, cloudFetch);
     if (result.outcome === SyncOutcome.SYNCED) {
-        ports.out(`↑ run ${run.runId} recorded on the Reticle dashboard`);
+        const dashboard = ports.dashboardUrl?.();
+        ports.out(dashboard === undefined
+            ? `↑ run ${run.runId} recorded on the Reticle dashboard`
+            : seeRunLine(dashboard, run.runId));
     }
     else {
-        ports.fail(`cloud run sync failed (${result.status ?? result.error ?? 'error'}); run kept locally`);
+        ports.fail(runSyncFailure(result.status, result.error));
+    }
+}
+/** The platform answered: the credential was not accepted. */
+const REFUSED_STATUSES = new Set([401, 403]);
+/**
+ * Why the run did not reach the dashboard. A revoked key left CI green with "cloud run sync failed
+ * (401)" in the log as the only trace; a refused key is said as one, loudly.
+ */
+export function runSyncFailure(status, error) {
+    if (status !== undefined && REFUSED_STATUSES.has(status)) {
+        return (`⚠ The platform refused this project's API key (${String(status)}): this run did NOT reach ` +
+            'the dashboard, and nothing pushed with this key will. The key was revoked, or its owner no ' +
+            'longer has access to the workspace — mint a new one in Settings → API keys. Run kept locally.');
     }
+    return `cloud run sync failed (${String(status ?? error ?? 'error')}); run kept locally`;
 }
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -233,6 +280,9 @@ export function buildVerifyDeps(running, reticleRoot, now) {
         fs,
         reticleRoot,
         now,
+        // The key `reticle connect` filed. Without it a connected machine that never exported
+        // RETICLE_API_KEY was told to run `reticle connect` when asking the Harness to drive.
+        linkedCloud: linkedCloudPort(fs, reticleRoot, homedir(), process.env),
     };
     if (running.realInput !== undefined)
         deps.realInput = running.realInput;
@@ -259,17 +309,18 @@ async function openLiveConnection(opts) {
     const envPort = Number(process.env[ReticleEnv.PORT]);
     const port = Number.isFinite(envPort) && envPort > 0 ? envPort : opts.port;
     const { origin, loopback } = urlParts(opts.url);
-    const pairing = loopback
+    // The configured token when there is one: an app in a container presents the one in the shared
+    // token directory, and a fresh one-shot token refused it (#1251).
+    const token = loopback
+        ? undefined
+        : ((await configuredPairingToken(process.env, nodePairingTokenDeps())) ?? randomUUID());
+    const pairing = token === undefined
         ? {}
-        : (() => {
-            const token = randomUUID();
-            const bridgeUrl = bridgeWsUrl(port);
-            return {
-                token,
-                injectConnect: { token, url: bridgeUrl },
-                ...(origin !== undefined ? { allowedOrigins: [origin] } : {}),
-            };
-        })();
+        : {
+            token,
+            injectConnect: { token, url: bridgeWsUrl(port) },
+            ...(origin !== undefined ? { allowedOrigins: [origin] } : {}),
+        };
     const running = await start({
         port,
         driveUrl: opts.url,
@@ -281,22 +332,28 @@ async function openLiveConnection(opts) {
         ...(opts.storageState !== undefined ? { storageState: opts.storageState } : {}),
     });
     const deps = buildVerifyDeps(running, opts.reticleRoot, opts.now);
-    const runner = new ReticleRunner(createRunnerPort(deps, opts.sessionId));
+    const harnessEnv = await withLinkedCredential(deps, process.env);
+    const runner = new ReticleRunner(createRunnerPort(deps, opts.sessionId, { confirmDangerous: true === opts.confirmDangerous }));
     return {
         sessionReady: (timeoutMs) => waitForSession(deps.sessions, timeoutMs, opts.now),
         listFlows: async (select) => select === undefined || 0 === select.length
             ? deps.flows.list()
-            : (await resolveSuiteSelection(deps, undefined, { labels: [...select] })).run,
+            : (await resolveSuiteSelection(deps, projectOnly(undefined), { labels: [...select] })).run,
         // Absent, not throwing, when no model is configured: the CLI reads its absence as "unavailable"
         // and prints the one sentence that makes it available.
-        ...(harnessAvailable(process.env)
+        ...(harnessAvailable(harnessEnv)
             ? {
                 explore: async (focus) => {
-                    const result = await exploreApp(deps, process.env, {
+                    const result = await exploreApp(deps, harnessEnv, {
                         ...(focus === undefined ? {} : { focus }),
                         ...(opts.sessionId === undefined ? {} : { sessionId: opts.sessionId }),
                     });
-                    return { savedFlows: result.savedFlows, steps: result.drive.steps };
+                    return {
+                        savedFlows: result.savedFlows,
+                        steps: result.drive.steps,
+                        stopReason: result.drive.stopReason,
+                        ...(result.drive.error === undefined ? {} : { error: result.drive.error }),
+                    };
                 },
             }
             : {}),
@@ -389,16 +446,19 @@ export function expectNeedsDaemonMessage(port, presence) {
         '  • Start a daemon on that port, pointed at the app, then re-run this command: ' +
         `npx @reticlehq/server serve --port ${String(port)} --drive <url>\n` +
         `  • Or drop ${EXPECT_FLAG}, and verify drives the url itself and replays your saved flows — ` +
-        'a different question, and it proves nothing about your predicate.');
+        'a different question, and it proves nothing about your predicate.\n\n' +
+        `  • Once that daemon is running, you can also drive its HTTP MCP transport for anything ` +
+        `${EXPECT_FLAG} cannot do — click, fill, press (${MCP_SSE_PATH}, then ${MCP_MESSAGE_PATH}). ` +
+        'See https://docs.reticle.sh/http-transport.md.');
 }
 /**
- * The model key is set here but not in the daemon, which is where the drive runs. The daemon is
+ * The platform key is set here but not in the daemon, which is what asks the platform. The daemon is
  * usually the one `init` or the agent's MCP client started, from an environment without the key.
  */
 export function daemonLacksKeyMessage(port) {
-    return (`${ReticleEnv.HARNESS_KEY} is set in this shell, but the daemon on port ${String(port)} was ` +
-        'started without it, and the drive runs inside the daemon. Restart it from this shell so it ' +
-        `inherits the key: npx @reticlehq/server restart --port ${String(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)}`);
 }
 /** What `verify` does next, once the options and the state of the port are both known. */
 export const VerifyRoute = {
@@ -430,7 +490,7 @@ export function routeVerify(args) {
     }
     if (args.presence !== PortPresence.DAEMON)
         return { route: VerifyRoute.FLOWS };
-    if (true === args.explore && true !== args.wantsOwnBrowser) {
+    if (true === args.explore && true !== args.wantsOwnBrowser && true !== args.hasSavedFlows) {
         return { route: VerifyRoute.ADHOC_EXPLORE };
     }
     // No predicate, but there may be SAVED FLOWS, and a daemon already owns the port: replay them
@@ -470,33 +530,45 @@ export function handleVerify(parsed) {
         }
     }
     const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
-    const projectName = basename(process.cwd()) || DEFAULT_PROJECT_NAME;
+    const linkedName = async () => verifyProjectName((await resolveProjectCloud(createNodeFileSystem(), reticleRoot, homedir(), process.env))
+        .projectId, readProjectId(process.cwd()), basename(process.cwd()));
     const ports = {
-        connect: () => openLiveConnection({
+        connect: async () => openLiveConnection({
             url: parsed.url,
             headless: parsed.headless,
             reticleRoot,
-            projectName,
+            projectName: await linkedName(),
             now,
             port: parsed.port ?? RETICLE_DEFAULT_PORT,
             ...(parsed.storageState !== undefined ? { storageState: parsed.storageState } : {}),
             ...(parsed.sessionId !== undefined ? { sessionId: parsed.sessionId } : {}),
+            ...(true === parsed.confirmDangerous ? { confirmDangerous: true } : {}),
         }),
         out: (line) => process.stdout.write(`${line}\n`),
         fail: (line) => process.stderr.write(`${line}\n`),
         exit: (code) => process.exit(code),
-        cloud: linkedCloudPort(createNodeFileSystem(), reticleRoot, homedir(), process.env),
+        cloud: linkedRunsCloudPort(createNodeFileSystem(), reticleRoot, homedir(), process.env),
+        dashboardUrl: () => readDashboardUrl(reticleRoot),
+        writeResults: (path, text) => writeFile(path, text, 'utf8'),
     };
     // Asked BEFORE anything binds. The listen failure arrives asynchronously on the server object,
     // long after `start` has resolved, so no `.catch` on that promise can ever see it — which is why
     // this used to reach the user as a raw node stack rather than as an answer.
     void (async () => {
+        const keyNote = (await resolveProjectCloud(createNodeFileSystem(), reticleRoot, homedir(), process.env)).note;
+        if (keyNote !== undefined)
+            process.stderr.write(`${keyNote}\n`);
         const port = parsed.port ?? RETICLE_DEFAULT_PORT;
+        // A lease opened for this verdict writes its runs into this folder's project, not `unmatched/`.
+        const root = callerArtifactRoot(process.cwd());
+        const callerRoot = root === undefined ? {} : { root };
         const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
         const plan = routeVerify({
             hasPredicate: expectation !== undefined,
             wantsOwnBrowser: !parsed.headless || parsed.storageState !== undefined,
             explore: true === parsed.explore || parsed.persona !== undefined,
+            hasSavedFlows: 0 <
+                (await new FlowStore(createNodeFileSystem(), reticleRoot, { now: Date.now }).list()).length,
             presence,
             port,
         });
@@ -522,6 +594,7 @@ export function handleVerify(parsed) {
                     // Read fresh, not from `presence`: that probe asks whether a daemon is on the port, and
                     // this asks whether a TAB is — the difference between asserting and opening the url first.
                     sessions: async () => summarizeStatus(await fetchStatus(port)).sessions,
+                    ...callerRoot,
                     ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
                     ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
                 });
@@ -535,6 +608,10 @@ export function handleVerify(parsed) {
             case VerifyRoute.ADHOC_SUITE: {
                 const suite = await runAdhocSuite({
                     port,
+                    ...(parsed.url !== undefined && '' !== parsed.url ? { url: parsed.url } : {}),
+                    sessions: async () => summarizeStatus(await fetchStatus(port)).sessions,
+                    ...callerRoot,
+                    ...(true === parsed.confirmDangerous ? { confirmDangerous: true } : {}),
                     ...(parsed.select === undefined ? {} : { select: parsed.select }),
                     ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
                     ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
@@ -552,13 +629,14 @@ export function handleVerify(parsed) {
                     url: parsed.url,
                     ...(parsed.persona === undefined ? {} : { persona: parsed.persona }),
                     sessions: async () => summarizeStatus(await fetchStatus(port)).sessions,
+                    ...callerRoot,
                     ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
                 });
                 for (const line of explored.lines)
                     ports.out(line);
                 // The drive runs INSIDE the daemon, so the key has to be in ITS environment. A reader who
-                // exported it in this shell and got "set ANTHROPIC_API_KEY" back has been told to do the
-                // thing they just did; say where the key is actually missing.
+                // exported it in this shell and was told to link has been told to do the thing they just
+                // did; say where the key is actually missing.
                 if (0 !== explored.code && harnessAvailable(process.env)) {
                     const refusedForKey = explored.lines.some((line) => line.includes(MSG_NO_HARNESS_KEY));
                     if (refusedForKey)
@@ -574,6 +652,7 @@ export function handleVerify(parsed) {
                     ...(true === parsed.explore ? { explore: true } : {}),
                     ...(parsed.persona === undefined ? {} : { persona: parsed.persona }),
                     ...(parsed.select === undefined ? {} : { select: parsed.select }),
+                    ...(parsed.resultsJson === undefined ? {} : { resultsJson: parsed.resultsJson }),
                 }, ports);
                 return;
         }

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

@@ -1,3 +1,16 @@
+export { cmdLink } from './cloud-link.js';
 export declare const isCloudCommand: (cmd: string | undefined) => boolean;
+/**
+ * Who is signed in and which project this repo is linked to, for `reticle status`. Local files
+ * only: status must answer with no network.
+ */
+export declare const accountStatusFields: () => Promise<{
+    signedInAs: string | null;
+    linkedProject: string | null;
+    linkedWorkspace?: string;
+    keyRefused?: string;
+}>;
+/** Whether `reticle connect`'s init half installs the packages: not under `--no-install`. */
+export declare const connectInstalls: (argv: readonly string[]) => boolean;
 /** Dispatch a cloud subcommand. Returns the process exit code. */
 export declare const runCloudCommand: (argv: readonly string[]) => Promise<number>;