@reticlehq/server 2.14.0 → 3.2.0

package/dist/setup/run-setup.js

@@ -1,294 +0,0 @@
-/**
- * The half of setup that happens after the files are written.
- *
- * `init` wires a project; this gets the app running with the SDK inside it, proves a session
- * connected, and drives one flow to a verdict. Measured against an agent doing the same steps by
- * hand from SKILL.md across five real applications: 176 model turns, $9.92, forty minutes, and a
- * verdict in two runs out of five — three ended by asking a human to restart their client, having
- * shown them nothing.
- *
- * Every effect is injected. That is not ceremony: the sequence has five phases, each with its own
- * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
- * and a real browser to find out what happens when neither works.
- */
-import { judgeWait, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict } from './dev-server-wait.js';
-import { waitProgressLine } from './wait-progress.js';
-/**
- * Windows gets longer to say something before silence counts as a wedge.
- *
- * A first `npm run dev` on a cold Windows runner optimises dependencies before the bundler prints a
- * line, and 45s of quiet is inside that window. Measured on the install gate: the Vue scaffold was
- * declared hung, `init` exited 1, and the gate then started the very same app and connected to it
- * on the next line. Nothing was wrong with the app; the wait was too impatient for the platform.
- *
- * Only the QUIET budget moves. The ceiling is unchanged, and a launcher that exits is still dead
- * immediately, so this buys patience for a starting server and never for a broken one.
- */
-const WINDOWS_QUIET_MEANS_HUNG_MS = 3 * 60_000;
-const WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES = 'win32' === process.platform;
-import { pickSession } from './session-pick.js';
-import { readPage, describePage, PageFinding } from './page-probe.js';
-import { remainingSteps } from './remaining-steps.js';
-import { AppShape, isDesktop, policyFor } from './desktop-shape.js';
-/** Where a run got to, and why it stopped if it did. */
-/**
- * How long to keep asking whether the SDK has reached the page before giving up on opening a window.
- * Bounded by the connect budget, so a short budget is never overrun by the readiness check.
- */
-const SDK_READY_WINDOW_MS = 15_000;
-/** The wait left when no browser was opened: only a tab that is ALREADY loaded can still appear. */
-const NO_BROWSER_GRACE_MS = 3_000;
-export const SetupPhase = {
-    DEV_SERVER: 'dev-server',
-    CONNECT: 'connect',
-    DRIVE: 'drive',
-    DONE: 'done',
-};
-const asProgress = (input, o) => ({
-    initDone: true,
-    devServerUp: undefined !== o.url,
-    sessionConnected: undefined !== o.sessionId,
-    flowSaved: true === o.flowSaved,
-    urlSuppliedByCaller: undefined !== input.suppliedUrl,
-    ...(undefined === o.url ? {} : { url: o.url }),
-    ...(undefined === input.devCommand ? {} : { devCommand: input.devCommand }),
-});
-const stop = (input, phase, partial, notes) => ({
-    ok: false,
-    reachedPhase: phase,
-    flowSaved: false,
-    ...partial,
-    notes,
-    fallback: remainingSteps(asProgress(input, partial)),
-});
-/**
- * Run the phases. Stops at the first one that cannot continue, and always says what is left.
- *
- * A phase that fails is not an error to throw: the caller is usually an agent, and a thrown
- * exception loses the four things it needs — how far this got, the url, the session, and what to do
- * about it.
- */
-export async function runSetupPhases(input, fx) {
-    const notes = [];
-    const note = (line) => {
-        notes.push(line);
-        fx.note(line);
-    };
-    // ── the app has to be running ────────────────────────────────────────────────────────────────
-    let url = input.suppliedUrl;
-    let attachedToExisting = false;
-    if (undefined === url) {
-        const announced = undefined === fx.existingAppUrl ? undefined : await fx.existingAppUrl();
-        if (undefined !== announced && 0 < announced.length) {
-            // The plugin already announced a live server for THIS project. Starting `dev` beside it is
-            // how Vite binds 5174, a second tab opens, and `reticle_sessions` lists three with no way
-            // to pick. The registry is scoped; an unscoped listen would attach to a sibling app.
-            url = announced;
-            attachedToExisting = true;
-            note(`This project is already running at ${announced} — attaching instead of starting a second server.`);
-        }
-        else if (undefined === input.devCommand) {
-            note(
-            // "stop here rather than invent one" is the SKILL.md rule, and the words are the contract —
-            // inventing a dev command is how a setup script runs the wrong thing and reports success.
-            'No dev command: the project names no dev, start or serve script, and there is no --url. ' +
-                'Stopping here rather than invent one — start the app yourself and pass --url to say ' +
-                'where it is serving, or add a dev/start/serve script to package.json and re-run.');
-            return stop(input, SetupPhase.DEV_SERVER, {}, notes);
-        }
-        else {
-            await fx.startDevServer(input.devCommand, input.appDir);
-            const startedAt = fx.now();
-            // This loop used to poll in complete silence. Reported as thirty minutes of nothing ending in a
-            // SIGKILL — and whatever made that wait long, a user who cannot tell "still starting" from
-            // "wedged" has been given no way to act. See wait-progress.ts.
-            let spokeAtMs;
-            for (;;) {
-                const watching = urlToWatch(fx.devServerOutput(), fx.observedPorts());
-                const waitedMs = fx.now() - startedAt;
-                const progress = waitProgressLine(waitedMs, watching, spokeAtMs);
-                if (progress !== undefined) {
-                    note(progress);
-                    spokeAtMs = waitedMs;
-                }
-                const probe = undefined === watching
-                    ? { served: false, sdkInPage: false }
-                    : await fx.probePage(watching);
-                const serving = probe.served;
-                const verdict = judgeWait({
-                    output: fx.devServerOutput(),
-                    launcherExited: fx.devServerExited(),
-                    serving,
-                    quietForMs: fx.devServerQuietForMs(),
-                    elapsedMs: fx.now() - startedAt,
-                    quietMeansHungMs: WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES
-                        ? WINDOWS_QUIET_MEANS_HUNG_MS
-                        : QUIET_MEANS_HUNG_MS,
-                });
-                if (WaitVerdict.READY === verdict && undefined !== watching) {
-                    // Prefer the URL that answered when the announcement was the wrong family (#884).
-                    url = probe.reachedUrl ?? watching;
-                    break;
-                }
-                // A desktop shell serves its webview from inside the app, so there is no port to answer and
-                // nothing to be READY. Once it has announced a url, or bound one we can see, that is as far
-                // as this phase can get: the session it dials from its own window is the real signal.
-                if (isDesktop(input.shape) && undefined !== watching) {
-                    url = watching;
-                    break;
-                }
-                if (WaitVerdict.DEAD === verdict) {
-                    note('The dev server exited without serving anything.');
-                    return stop(input, SetupPhase.DEV_SERVER, {}, notes);
-                }
-                if (WaitVerdict.HUNG === verdict) {
-                    // Says BOTH were checked. A server that prints nothing but IS listening is the CRA case and
-                    // must not be failed, so a reader has to be able to tell "we looked at the log" from "we
-                    // looked at the log AND the ports".
-                    note('The dev server neither printed a URL nor bound a port, so setup has nothing to open. ' +
-                        'Check its log, or pass --url with the address it serves.');
-                    return stop(input, SetupPhase.DEV_SERVER, {}, notes);
-                }
-                await fx.sleep(input.pollMs);
-            }
-        }
-    }
-    // ── and something has to connect from inside it ──────────────────────────────────────────────
-    const policy = policyFor(input.shape);
-    // Through `note`, not `fx.note`: a caller reading the result should see it too.
-    if (undefined !== policy.note)
-        note(policy.note);
-    const listed = await fx.listSessions();
-    const requiredRuntime = isDesktop(input.shape) ? input.shape : undefined;
-    // A tab already on this URL is the answer. Opening another is how three sessions appear.
-    // `before` is empty so pickSession will take that tab rather than waiting for a new one.
-    const alreadyConnected = attachedToExisting
-        ? pickSession(listed, url, new Set(), requiredRuntime)
-        : null;
-    const before = new Set(listed.map((s) => s.sessionId));
-    // Do not put a window in front of somebody until the page behind it can actually do something.
-    //
-    // The probe that says whether the SDK is even IN the page used to run only in the failure branch
-    // below, AFTER the browser was already open. So a mis-wired app opened a real window onto a page
-    // that was never going to connect, and the person watching it saw a browser appear and then
-    // nothing happen for the whole connect budget — which reads as "Reticle is broken" rather than
-    // "the bundle predates the config edit". One fetch, before the window, turns that into a sentence.
-    //
-    // Only the browser is gated. The wait below still runs: something else may connect (an already
-    // open tab, a desktop window), and the probe is a statement about one fetch of the document, not
-    // proof that nothing can ever dial in.
-    const budgetMs = input.connectBudgetMs ?? Math.max(input.phaseTimeoutMs, policy.connectBudgetMs);
-    let openedBrowser = false;
-    if (null === alreadyConnected && input.openBrowser && policy.openBrowser) {
-        // SERVED is the precondition, not SDK_PRESENT: a url that answers nothing is the only state
-        // where a window is certainly useless. Whether the SDK is in the served HTML is a DIFFERENT
-        // question — Vite injects a marker, while Nuxt, React Router, Astro, SvelteKit and CRA deliver
-        // the connect in the JS BUNDLE, so their HTML never carries it. Gating on presence failed five
-        // of ten scaffolds in the install gate: no window, so no bundle, so no session, so exit 1 on a
-        // correct install. page-probe.ts says it is a diagnostic for a connect that already failed; the
-        // same signal as a precondition deadlocks every case it is wrong about.
-        //
-        // So presence decides only WHEN: open the moment it appears (the fast path for the frameworks
-        // that inline it), otherwise once the short readiness window is out.
-        const readyBy = fx.now() + Math.min(SDK_READY_WINDOW_MS, budgetMs);
-        let finding = readPage(await fx.probePage(url));
-        while (PageFinding.SDK_MISSING === finding && fx.now() < readyBy) {
-            await fx.sleep(input.pollMs);
-            finding = readPage(await fx.probePage(url));
-        }
-        if (PageFinding.NOT_SERVED === finding || PageFinding.TLS_REFUSED === finding) {
-            note(describePage(finding, url));
-            note('Not opening a browser: nothing answered that url, so the window could only show an error ' +
-                'page. Fix the line above and re-run — `init` is idempotent.');
-        }
-        else {
-            // Said BEFORE the window appears, so somebody watching a page that stays inert has already
-            // been told which of the two it is.
-            if (PageFinding.SDK_MISSING === finding)
-                note(describePage(finding, url));
-            await fx.openBrowser(url);
-            openedBrowser = true;
-        }
-    }
-    // Waiting the full budget for a session when nothing was opened to create one is dead time, and
-    // it used to be over two minutes of it: the browser is the session source on web, so declining to
-    // open it and then waiting as if we had is a promise to the reader that cannot be kept. Something
-    // else may still dial in — a tab the user already has open, a desktop window — and the existing
-    // diagnosis says such a session "will appear within a second of the page loading", so a short
-    // grace is the honest wait. A run that DID open a browser keeps the whole budget.
-    const deadline = fx.now() +
-        (openedBrowser || !(input.openBrowser && policy.openBrowser)
-            ? budgetMs
-            : Math.min(NO_BROWSER_GRACE_MS, budgetMs));
-    let session = alreadyConnected;
-    while (null === session) {
-        // On a desktop app, only the desktop window counts. AppShape and the runtime a page reports use
-        // the same three names, so the shape IS the requirement — see session-pick.
-        session = pickSession(await fx.listSessions(), url, before, requiredRuntime);
-        if (null !== session)
-            break;
-        if (deadline <= fx.now())
-            break;
-        await fx.sleep(input.pollMs);
-    }
-    if (null === session) {
-        if (isDesktop(input.shape)) {
-            // Nothing outside the app can fetch its webview, so there is no page to describe. What is
-            // wrong here is desktop-shaped: the preload, the capture helper, or a CSP that blocks the
-            // bridge — all of which `reticle doctor` checks.
-            note('The app never dialled in. For a desktop shell that is usually the preload not being required, ' +
-                'the capture helper not installed, or a CSP that blocks the bridge: run `npx @reticlehq/server doctor`.');
-        }
-        else {
-            // What the page contains is the one thing the daemon cannot know, so it is worth one fetch.
-            note(describePage(readPage(await fx.probePage(url)), url));
-        }
-        return stop(input, SetupPhase.CONNECT, { url }, notes);
-    }
-    // ── and it has to be driven, or nothing has been proved ──────────────────────────────────────
-    if (!input.drive) {
-        return {
-            ok: true,
-            reachedPhase: SetupPhase.CONNECT,
-            url,
-            sessionId: session.sessionId,
-            flowSaved: false,
-            notes,
-            fallback: [],
-        };
-    }
-    // Nothing to drive WITH is not the same as driving and proving nothing, and only the second is a
-    // failure of this command. The app is installed, instrumented, booted and connected; the one step
-    // left needs a tool this machine does not have, so it is reported and handed to the caller.
-    if (!fx.driverAvailable()) {
-        note('Installed and connected, but no agent CLI is on this machine (claude, codex, opencode, ' +
-            'cursor-agent or gemini), so nothing drove the app and no verdict was produced.');
-        return {
-            ok: true,
-            reachedPhase: SetupPhase.CONNECT,
-            url,
-            sessionId: session.sessionId,
-            flowSaved: false,
-            notes,
-            fallback: remainingSteps(asProgress(input, { url, sessionId: session.sessionId, flowSaved: false })),
-        };
-    }
-    const verdict = await fx.drive(url, session);
-    const flowSaved = fx.flowsSaved();
-    if (null === verdict) {
-        note('No agent CLI could drive the app, so nothing was proved.');
-    }
-    if (!flowSaved) {
-        return stop(input, SetupPhase.DRIVE, { url, sessionId: session.sessionId, ...(null === verdict ? {} : { verdict }) }, notes);
-    }
-    return {
-        ok: true,
-        reachedPhase: SetupPhase.DONE,
-        url,
-        sessionId: session.sessionId,
-        ...(null === verdict ? {} : { verdict }),
-        flowSaved: true,
-        notes,
-        fallback: [],
-    };
-}

package/dist/setup/setup-command.d.ts

@@ -1,46 +0,0 @@
-/**
- * The wire: everything init established, plus the world, plus the phases.
- *
- * Kept apart from cli.ts so the assembly is readable in one place and so `handleInit` stays the
- * three lines it was. The only decision here is which effects to hand over; the sequencing lives in
- * run-setup.ts and the pieces it calls.
- */
-import { type SetupInput, type SetupOutcome } from './run-setup.js';
-interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
-    /** Where setup was invoked, which is not the app directory in a monorepo. */
-    readonly invokedAt: string;
-    readonly bridgePort: number;
-    readonly env: Readonly<Record<string, string>>;
-    readonly flow?: string | undefined;
-    readonly driveBudgetUsd: number;
-    readonly driveModel?: string | undefined;
-    readonly escalateWeakFlow: boolean;
-    /** Register the MCP server with the coding agents init does not itself reach. */
-    readonly registerAgents: boolean;
-}
-/**
- * Register with the agents `init` does not reach, and leave the skill where one loads skills from.
- *
- * init covers eight clients and only where it finds them installed, which leaves VS Code's USER
- * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
- * so a VS Code user has no tools outside the directory they ran init in.
- */
-export declare function registerOtherAgents(print: (line: string) => void): void;
-interface SetupCommandResult extends SetupOutcome {
-    /** Set when a weak flow was re-recorded with the stronger model. */
-    readonly escalated?: {
-        readonly from: string;
-        readonly to: string;
-    } | undefined;
-    readonly driveTurns?: number | undefined;
-    readonly driveCostUsd?: number | undefined;
-}
-/**
- * Run the phases against the real world.
- *
- * The dev server is stopped on every ending except success, where it is handed to the user: an
- * instrumented app they can watch is the deliverable, and killing it would leave them with config
- * files and a dead tab.
- */
-export declare function runSetupCommand(input: SetupCommandInput, print: (line: string) => void): Promise<SetupCommandResult>;
-export {};

package/dist/setup/setup-command.js

@@ -1,207 +0,0 @@
-/**
- * The wire: everything init established, plus the world, plus the phases.
- *
- * Kept apart from cli.ts so the assembly is readable in one place and so `handleInit` stays the
- * three lines it was. The only decision here is which effects to hand over; the sequencing lives in
- * run-setup.ts and the pieces it calls.
- */
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { planAgentConfigs } from './agent-configs.js';
-import { AppShape, readShape } from './desktop-shape.js';
-import { stopOnInterrupt } from './interrupt.js';
-import { applyAgentPlan, applyAgentSkills } from './agent-writer.js';
-import { ApprovalOutcome, grantAutoApproval } from './auto-approve.js';
-import { agentIo } from './agent-io.js';
-import { EnsureDaemon, ensureDaemon, nodeEnsureDaemonDeps } from './ensure-daemon.js';
-import { openInBrowser } from '../cli/cli-launch.js';
-import { readProjectId } from '../cli/cli-port.js';
-import { reticleStateHome } from '../daemon/daemon.js';
-import { readDevServers } from '../daemon/dev-servers.js';
-import { chooseDriver, DRIVERS, shouldEscalate } from './drive-plan.js';
-import { driveWith } from './drive-agent.js';
-import { urlOfExistingApp } from './existing-app.js';
-import { binaryExists, flowsSaved, listSessions, OwnedDevServer, probePage, } from './node-effects.js';
-import { runSetupPhases, } from './run-setup.js';
-/** The capabilities file init scaffolds, in the order a project is likely to have it. */
-const CAPABILITY_FILES = ['reticle-dev.tsx', 'reticle-dev.ts', 'reticle-dev.jsx', 'reticle-dev.js'];
-/** `electron` in either dependency list, read the same way init's desktop doctor reads it. */
-function hasElectronDependency(dir) {
-    try {
-        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-        if ('object' !== typeof pkg || null === pkg)
-            return false;
-        const p = pkg;
-        return undefined !== { ...p.dependencies, ...p.devDependencies }['electron'];
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Register with the agents `init` does not reach, and leave the skill where one loads skills from.
- *
- * init covers eight clients and only where it finds them installed, which leaves VS Code's USER
- * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
- * so a VS Code user has no tools outside the directory they ran init in.
- */
-export function registerOtherAgents(print) {
-    const platform = process.platform;
-    const home = homedir();
-    const results = applyAgentPlan(planAgentConfigs({ home, platform, exists: agentIo.exists, readFile: agentIo.readFile }), agentIo);
-    const wrote = results.filter((r) => 'created' === r.action || 'merged' === r.action);
-    if (0 < wrote.length) {
-        print(`registered the MCP server with ${wrote.length} more agent(s): ${wrote.map((r) => r.name).join(', ')}`);
-    }
-    // A format we will not rewrite is somebody's to edit, so it has to be said rather than skipped.
-    for (const manual of results.filter((r) => 'manual' === r.action)) {
-        print(`${manual.name}: ${manual.why} — add the reticle entry to ${manual.file} by hand.`);
-    }
-    const skills = applyAgentSkills(agentIo, { home, platform });
-    if (0 < skills.length)
-        print(`wrote the /reticle skill for ${skills.length} agent(s)`);
-    // Registration alone still leaves an Accept dialog in front of every call, and a verification run
-    // makes dozens of them: the loop is only autonomous once the tools are pre-approved.
-    const approvals = grantAutoApproval(agentIo, { home, platform });
-    const granted = approvals.filter((a) => ApprovalOutcome.GRANTED === a.outcome);
-    if (0 < granted.length) {
-        print(`pre-approved the reticle tools in ${granted.map((a) => a.name).join(', ')} — no Accept prompt per call`);
-    }
-    for (const noted of approvals.filter((a) => undefined !== a.warn)) {
-        print(`${noted.name}: ${String(noted.warn)}`);
-    }
-}
-/**
- * Run the phases against the real world.
- *
- * The dev server is stopped on every ending except success, where it is handed to the user: an
- * instrumented app they can watch is the deliverable, and killing it would leave them with config
- * files and a dead tab.
- */
-export async function runSetupCommand(input, print) {
-    if (input.registerAgents)
-        registerOtherAgents(print);
-    // Before the app is booted, because the app's whole job from here is to dial this port. Without
-    // it the phases wait out their budget and then report the SDK as the thing that failed.
-    const daemon = await ensureDaemon(input.bridgePort, nodeEnsureDaemonDeps());
-    if (EnsureDaemon.UNAVAILABLE === daemon) {
-        print(`could not start the Reticle daemon on port ${String(input.bridgePort)}, so nothing is listening for the app to connect to. Run \`npx @reticlehq/server serve --port ${String(input.bridgePort)}\` and try again.`);
-    }
-    // Which shell this is decides three things the phases would otherwise get wrong: opening a
-    // browser (harmful for desktop, where the app's own window is the client), waiting for an HTTP
-    // port (a Tauri webview has none), and how long the app gets to appear (a cold `tauri dev` builds
-    // Rust first). The same evidence init's desktop doctor reads.
-    const shape = readShape({
-        hasTauriConf: existsSync(join(input.appDir, 'src-tauri', 'tauri.conf.json')),
-        hasElectronDep: hasElectronDependency(input.appDir),
-    });
-    if (AppShape.WEB !== shape)
-        print(`detected a ${shape} app`);
-    const server = new OwnedDevServer();
-    // Both roots, because in a monorepo `.reticle/` sits at the app root rather than where setup ran.
-    const flowRoots = [input.invokedAt, input.appDir];
-    let lastDrive;
-    let escalated;
-    const effects = {
-        startDevServer: (command, cwd) => {
-            print(`starting: ${command}`);
-            server.start(command, cwd, input.env);
-            return Promise.resolve();
-        },
-        existingAppUrl: () => Promise.resolve(urlOfExistingApp(readDevServers(reticleStateHome()), {
-            projectId: readProjectId(input.appDir),
-            root: input.appDir,
-        })),
-        devServerOutput: () => server.output(),
-        devServerExited: () => server.exited(),
-        devServerQuietForMs: () => server.quietForMs(),
-        observedPorts: () => server.listeningPorts(),
-        probePage,
-        openBrowser: async (url) => {
-            const failure = await openInBrowser(url);
-            if (null !== failure) {
-                print(`could not open a browser (${failure}). On a machine with none — CI, a container, an SSH ` +
-                    'session — take a tab Reticle owns instead: reticle_run({ tool: "reticle_lease", args: ' +
-                    `{ action: "acquire", url: "${url}" } }).`);
-            }
-        },
-        listSessions: () => listSessions(input.bridgePort),
-        // Asked before the drive rather than inferred from its result: "nothing to drive with" and
-        // "drove and proved nothing" are different answers and only the second is a failure.
-        driverAvailable: () => null !==
-            chooseDriver(DRIVERS, (bin) => ({ present: binaryExists(bin), runs: binaryExists(bin) })),
-        drive: (url, session) => {
-            const driver = chooseDriver(DRIVERS, (bin) => ({
-                present: binaryExists(bin),
-                // Present is not enough: a CLI that does not run produces an empty session that looks
-                // exactly like success.
-                runs: binaryExists(bin),
-            }));
-            if (null === driver)
-                return Promise.resolve(null);
-            // Only when the SESSION says they were never finished. init fills this file for a
-            // conventional app — it detects a state library and the testids — so opening it otherwise
-            // spends a turn on work already done, and grants write access nobody needed.
-            const capabilitiesFile = false === session.hasCapabilities
-                ? CAPABILITY_FILES.map((f) => join(input.appDir, 'src', f)).find((p) => existsSync(p))
-                : undefined;
-            print('');
-            print(`  ▸ WATCH ${url} NOW — the HUD is on, and you are about to see Reticle drive your app.`);
-            print('');
-            const request = {
-                url,
-                sessionId: session.sessionId,
-                tabThrottled: false,
-                budgetUsd: input.driveBudgetUsd,
-                ...(undefined === input.flow ? {} : { flow: input.flow }),
-                ...(undefined === input.driveModel ? {} : { model: input.driveModel }),
-                ...(undefined === capabilitiesFile ? {} : { unfinishedCapabilitiesFile: capabilitiesFile }),
-            };
-            lastDrive = driveWith(driver, request, input.appDir);
-            // A weak flow only ACTS, so it passes when the feature is broken — and setup replays saved
-            // flows, which turns one weak recording into a permanent green. Re-record it rather than
-            // hand the trade to the user.
-            if (shouldEscalate({
-                escalationEnabled: input.escalateWeakFlow,
-                fasterModel: input.driveModel,
-                flowSaved: flowsSaved(flowRoots),
-                ...(undefined === lastDrive.grade ? { grade: undefined } : { grade: lastDrive.grade }),
-            })) {
-                print(`the saved flow graded \`${lastDrive.grade ?? 'unknown'}\` — re-recording with the default model`);
-                const stronger = driveWith(driver, { ...request, model: undefined }, input.appDir);
-                escalated = { from: lastDrive.grade ?? 'unknown', to: stronger.grade ?? 'unknown' };
-                if (undefined !== stronger.grade)
-                    lastDrive = stronger;
-            }
-            if (undefined !== lastDrive.incomplete) {
-                print(`the drive did not finish, and ${lastDrive.incomplete}`);
-            }
-            return Promise.resolve('' === lastDrive.text ? null : lastDrive.text);
-        },
-        flowsSaved: () => flowsSaved(flowRoots),
-        now: () => Date.now(),
-        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-        note: print,
-    };
-    // A `finally` does not run on SIGINT, and this phase owns a detached dev server — see interrupt.ts.
-    const releaseSignals = stopOnInterrupt(() => {
-        server.stop();
-    }, process);
-    try {
-        const outcome = await runSetupPhases({ ...input, shape }, effects);
-        // The app stays up only when there is something worth watching.
-        if (outcome.ok)
-            server.handOver();
-        return {
-            ...outcome,
-            ...(undefined === escalated ? {} : { escalated }),
-            ...(undefined === lastDrive?.turns ? {} : { driveTurns: lastDrive.turns }),
-            ...(undefined === lastDrive?.costUsd ? {} : { driveCostUsd: lastDrive.costUsd }),
-        };
-    }
-    finally {
-        releaseSignals();
-        server.stop();
-    }
-}

package/dist/setup/setup-options.d.ts

@@ -1,76 +0,0 @@
-/**
- * The contract between the agent and the script.
- *
- * Everything setup does is deterministic except for the handful of things that require reading a
- * repository and a human's request and understanding both. Those are exactly what an agent is good
- * at and code is not, so they arrive here as ARGUMENTS rather than as steps somebody walks through:
- * the agent decides, the script executes, and neither does the other's job.
- *
- * What only an agent can know, and therefore what belongs in this type:
- *
- *   --flow      which journey proves the thing the user cares about. Code can enumerate buttons; it
- *               cannot know that checkout matters and the theme toggle does not. Measured, naming
- *               it took one app's drive from a ten-minute timeout to 138 seconds, because the turns
- *               go into FINDING a flow and naming one removes that search.
- *   --app       which app in a monorepo the user meant. init can find the ones that are servable;
- *               only the request says which of them is being worked on.
- *   --env       what the app needs to get past its own front door. A key in .env.example, a mock
- *               backend named in the README, the variable that skips an auth wall: all readable by
- *               an agent, none inferable by a script. Without this a real app sits on a login
- *               screen and there is no flow to drive at all.
- *   --url       the app is already running here, so do not start anything. This is also the answer
- *               when the project's own scripts do not name a dev command: start it yourself and say
- *               where. There is no flag that overrides the dev command; --url replaces the need.
- *
- * Everything else on this type is an operator's dial, not an agent's judgement.
- */
-/** The bridge port. NOT the dev server's, and conflating them is a documented setup failure. */
-export declare const DEFAULT_BRIDGE_PORT = 4400;
-/** Per-phase budget. The drive gets its own, much larger one. */
-export declare const DEFAULT_PHASE_TIMEOUT_MS = 120000;
-/** What the drive may spend before it is stopped. */
-export declare const DEFAULT_DRIVE_BUDGET_USD = 3;
-interface SetupOptions {
-    /** The journey to drive, in the caller's own words. */
-    readonly flow?: string | undefined;
-    /** Which app in a monorepo. */
-    readonly app?: string | undefined;
-    /** Environment the app needs in order to reach a usable state. */
-    readonly env?: Readonly<Record<string, string>> | undefined;
-    /** The dev command, when the project's scripts do not say it plainly. */
-    readonly devCommand?: string | undefined;
-    /** The app is already served here. */
-    readonly url?: string | undefined;
-    readonly bridgePort: number;
-    readonly phaseTimeoutMs: number;
-    readonly driveBudgetUsd: number;
-    readonly driveModel?: string | undefined;
-    /** Register the MCP with the other coding agents on this machine. */
-    readonly registerAgents: boolean;
-    /** Open a browser. False for CI, a headless box, or a tab the user already has. */
-    readonly openBrowser: boolean;
-    /** Drive a flow. False leaves step five to the caller, and is the only honest way to skip it. */
-    readonly drive: boolean;
-    /** Re-record with the stronger model when the saved flow is graded weaker than `asserted`. */
-    readonly escalateWeakFlow: boolean;
-    /** Restart a dev server whose bundle predates the build-config edit. */
-    readonly restartStaleDevServer: boolean;
-    /** Write files and stop, which is what `init` did before it grew the runtime phases. */
-    readonly filesOnly: boolean;
-    /** A license key, written to .env and never echoed. */
-    readonly licenseKey?: string | undefined;
-}
-export declare const DEFAULT_SETUP_OPTIONS: SetupOptions;
-/** One `KEY=VALUE`, as an agent would pass it. Everything after the first `=` is the value. */
-export declare function parseEnvAssignment(pair: string): {
-    key: string;
-    value: string;
-} | null;
-/**
- * Fold repeated `--env KEY=VALUE` into one map, ignoring what cannot be a variable.
- *
- * A malformed pair is dropped rather than guessed at: an agent that meant `--env` and typed
- * something else should see its variable missing, not see setup invent one.
- */
-export declare function collectEnv(pairs: readonly string[]): Record<string, string>;
-export {};