@reticlehq/server 2.14.0 → 3.2.0

package/dist/setup/auto-approve.js

@@ -1,153 +0,0 @@
-/**
- * Removing the Accept button, for the tools Reticle owns and nothing else.
- *
- * A drive that stops on a per-call approval dialog is not automated, and the dialog is per CALL:
- * a single verification run makes dozens, so a human sits there clicking through a loop that was
- * supposed to run without them. Every client below documents a way to pre-approve a named server,
- * and this writes exactly that rule, at install time, in the client's own spelling.
- *
- * Two limits, both deliberate:
- *
- * 1. ONLY `reticle` is allowed. Not `mcp(*)`, not a global auto-run switch. Reticle's tools drive
- *    the user's own dev server on their own machine, which is what makes pre-approving them
- *    defensible; the same edit made globally would hand the same pass to every other MCP server
- *    they ever install, including ones that reach the network. Their approval gate is not ours to
- *    dismantle, only ours to step out of.
- * 2. Nothing is CREATED where the file itself takes over settings we cannot read — Cursor's
- *    permissions.json supersedes its in-app allowlist and pins the run mode to Allowlist, so a user
- *    who ran everything without asking loses that and cannot switch back while the file exists.
- *    Merging into one they already have is fine; making one is not, so that case is DEFERRED with
- *    the in-app step to take instead. Nothing is written at all for an agent that is not installed:
- *    an absent agent has no Accept button to remove.
- *
- * Codex is absent by design: its approval policy is global (`approval_policy`), so there is no
- * reticle-shaped rule to write, and its config is TOML, which this repo never rewrites. Its
- * headless form, `codex exec`, does not prompt at all — which is the form the drive uses.
- */
-import { joinFor } from './agent-configs.js';
-const RETICLE_KEY = 'reticle';
-const INDENT = 2;
-const home = (path) => ({ darwin: path, linux: path, win32: path });
-/** Append to a nested array, without duplicating and without disturbing what is already in it. */
-function addToList(current, outer, key, value) {
-    const scope = null === outer
-        ? current
-        : 'object' === typeof current[outer] && null !== current[outer]
-            ? { ...current[outer] }
-            : {};
-    const list = Array.isArray(scope[key]) ? scope[key] : [];
-    if (list.includes(value))
-        return current;
-    const next = { ...scope, [key]: [...list, value] };
-    return null === outer ? next : { ...current, [outer]: next };
-}
-export const APPROVAL_GRANTS = [
-    {
-        id: 'claude-code',
-        name: 'Claude Code',
-        paths: home('.claude/settings.json'),
-        markers: [home('.claude')],
-        rule: 'permissions.allow += "mcp__reticle"',
-        grant: (c) => addToList(c, 'permissions', 'allow', 'mcp__reticle'),
-    },
-    {
-        id: 'cursor',
-        name: 'Cursor',
-        paths: home('.cursor/permissions.json'),
-        markers: [home('.cursor')],
-        rule: 'mcpAllowlist += "reticle:*"',
-        // Documented: "when a key appears in permissions.json, it fully replaces the in-app allowlist
-        // for that type" — and in practice it costs more than that. A non-empty mcpAllowlist also locks
-        // the run mode to Allowlist, so a user who had Run Everything ("YOLO") on loses it and cannot
-        // turn it back on while the file exists; Cursor has acknowledged that as their bug. Merging into
-        // a file the user already made is safe — they are already in Allowlist mode. Creating one is
-        // not, so we never do: see the DEFERRED branch below.
-        supersedesInApp: true,
-        grant: (c) => addToList(c, null, 'mcpAllowlist', `${RETICLE_KEY}:*`),
-    },
-    {
-        id: 'antigravity',
-        name: 'Antigravity',
-        paths: home('.gemini/antigravity-cli/settings.json'),
-        markers: [
-            {
-                darwin: 'Library/Application Support/Antigravity',
-                linux: '.config/Antigravity',
-                win32: 'AppData/Roaming/Antigravity',
-            },
-            home('.gemini/antigravity-cli'),
-        ],
-        rule: 'permissions.allow += "mcp(reticle/*)"',
-        grant: (c) => addToList(c, 'permissions', 'allow', `mcp(${RETICLE_KEY}/*)`),
-    },
-    {
-        id: 'gemini-cli',
-        name: 'Gemini CLI',
-        paths: home('.gemini/settings.json'),
-        markers: [home('.gemini')],
-        rule: 'mcpServers.reticle.trust = true',
-        // Gemini has no allowlist: trust is a property of the server entry itself, so this reaches into
-        // the entry init already wrote rather than adding a rule beside it.
-        grant: (c) => {
-            const servers = 'object' === typeof c['mcpServers'] && null !== c['mcpServers']
-                ? { ...c['mcpServers'] }
-                : {};
-            const entry = 'object' === typeof servers[RETICLE_KEY] && null !== servers[RETICLE_KEY]
-                ? servers[RETICLE_KEY]
-                : {};
-            return { ...c, mcpServers: { ...servers, [RETICLE_KEY]: { ...entry, trust: true } } };
-        },
-    },
-];
-export const ApprovalOutcome = {
-    GRANTED: 'granted',
-    ALREADY: 'already',
-    ABSENT: 'absent',
-    /** Deliberately left for an explicit run, because doing it unattended costs the user something. */
-    DEFERRED: 'deferred',
-    FAILED: 'failed',
-};
-/**
- * Pre-approve Reticle's tools everywhere the machine has an agent that would otherwise ask.
- *
- * A client that cannot be written is reported, never thrown: one unwritable settings file is not a
- * reason to leave the other three prompting.
- */
-export function grantAutoApproval(io, where, grants = APPROVAL_GRANTS) {
-    const join = joinFor(where.platform);
-    return grants.map((grant) => {
-        const file = join(where.home, grant.paths[where.platform]);
-        const base = { id: grant.id, name: grant.name, file, rule: grant.rule };
-        const installed = grant.markers.some((m) => io.exists(join(where.home, m[where.platform])));
-        if (!installed)
-            return { ...base, outcome: ApprovalOutcome.ABSENT };
-        try {
-            const existed = io.exists(file);
-            if (true === grant.supersedesInApp && !existed) {
-                return {
-                    ...base,
-                    outcome: ApprovalOutcome.DEFERRED,
-                    warn: `left ${grant.name}'s approvals alone — creating ${file} would take over its in-app settings and pin the run mode to Allowlist. If ${grant.name} asks before every reticle tool call, add \`${RETICLE_KEY}:*\` under Settings → Agents → Approvals & Execution (nothing to do if you run everything already).`,
-                };
-            }
-            // A settings file we cannot parse is left exactly as it is. Reformatting somebody's config to
-            // add one line is a worse outcome than one dialog they have to click.
-            const current = existed
-                ? JSON.parse(io.readFile(file))
-                : {};
-            const next = grant.grant(current);
-            if (next === current)
-                return { ...base, outcome: ApprovalOutcome.ALREADY };
-            io.mkdirp(file.slice(0, Math.max(0, file.lastIndexOf('/'))));
-            io.writeFile(file, `${JSON.stringify(next, null, INDENT)}\n`);
-            return { ...base, outcome: ApprovalOutcome.GRANTED };
-        }
-        catch (err) {
-            return {
-                ...base,
-                outcome: ApprovalOutcome.FAILED,
-                warn: String(err?.message ?? err).slice(0, 120),
-            };
-        }
-    });
-}

package/dist/setup/bridge-port.d.ts

@@ -1,15 +0,0 @@
-/**
- * The bridge port, checked before the connect wait.
- *
- * The bridge is the channel between the daemon and the SDK in the page. While something else holds
- * that port no session can ever appear, however correct the instrumentation is — so a run that goes
- * ahead spends its entire connect budget and then reports what looks like a wiring problem, sending
- * the reader to the one place that is fine.
- *
- * `serve` refuses a held port too, in prose written for somebody starting a daemon. This is the same
- * fact told to somebody installing, and it has to say what the bridge IS: that sentence is what
- * makes "no session appeared" mean something.
- */
-import { PortPresence } from '../daemon/port-presence.js';
-/** The refusal to print, or undefined when the port is usable. */
-export declare function bridgeOccupied(presence: PortPresence, port: number): string | undefined;

package/dist/setup/bridge-port.js

@@ -1,24 +0,0 @@
-/**
- * The bridge port, checked before the connect wait.
- *
- * The bridge is the channel between the daemon and the SDK in the page. While something else holds
- * that port no session can ever appear, however correct the instrumentation is — so a run that goes
- * ahead spends its entire connect budget and then reports what looks like a wiring problem, sending
- * the reader to the one place that is fine.
- *
- * `serve` refuses a held port too, in prose written for somebody starting a daemon. This is the same
- * fact told to somebody installing, and it has to say what the bridge IS: that sentence is what
- * makes "no session appeared" mean something.
- */
-import { PortPresence } from '../daemon/port-presence.js';
-/** The refusal to print, or undefined when the port is usable. */
-export function bridgeOccupied(presence, port) {
-    // DAEMON is the ordinary case — that is the daemon init is about to use. FREE is fine too: one
-    // gets started. Only a stranger is fatal.
-    if (PortPresence.FOREIGN !== presence)
-        return undefined;
-    return (`port ${String(port)} is held by something that is not a Reticle daemon. That is the bridge — ` +
-        'the channel between the daemon and the SDK in your page — so no session can ever appear while ' +
-        'it is occupied, however correct the wiring is. Free it, or re-run with --port <n> and set the ' +
-        'same port in .reticle.json.');
-}

package/dist/setup/confirm.js

@@ -1,205 +0,0 @@
-/**
- * The step `init` never took: stay and watch for an app to connect.
- *
- * The install has two halves. Registering the MCP server gives the agent the tools; getting the SDK
- * into a running page gives it something to look at. Almost everyone finishes the first, and nothing
- * joined "init finished" to "an app connected" — so `init` exited 0 having written files, and the
- * person left with a config file and no instrumented page was never told (#269).
- *
- * The capability existed in three places and was used together by none of them: the poll behind
- * `reticle open`, the install gate (which calls this exact check "the only step that proves the
- * install works"), and the event that measures whether it ever happened.
- *
- * WHY NO FLAG, and no dev-server management:
- *
- *  - No flag, because the people this is for are the ones who do not know to ask. `--verify` would
- *    be typed by the users who already run `status` afterwards, which is exactly the cohort that is
- *    not being lost. The gate instead is whether a HUMAN IS AT THE TERMINAL: `init` waits when
- *    stdout is a TTY and skips the wait entirely otherwise, so a scripted or agent-driven `init`
- *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
- *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
- *    also keeps `init`'s documented flag surface where it is.
- *  - The DAEMON never starts anything. A dev server started by a long-lived daemon is invisible to
- *    the person whose machine it runs on and orphans when the daemon exits, so the daemon stays out
- *    of it. Note what that reasoning is actually about: attributability, not abstinence. A
- *    foreground `init` somebody ran satisfies it — the command is in their transcript, and it stops
- *    what it started if setup fails or is interrupted — which is why the runtime phase is allowed
- *    to boot one where the daemon is not. This function keeps its own shape either way: confirm the
- *    app if it connects, otherwise name the ONE command that is outstanding and the one that proves
- *    it worked.
- */
-import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { fetchStatus, summarizeStatus } from '../cli/cli-launch.js';
-import { readDevServers } from '../daemon/dev-servers.js';
-import { devServersForProject } from '@reticlehq/core/artifacts';
-import { readProjectId } from '../cli/cli-port.js';
-import { reticleStateHome } from '../daemon/daemon.js';
-import { reportInitOutcome } from '../telemetry/init-telemetry.js';
-/**
- * How long a human is asked to wait.
- *
- * Long enough for a page that is already loading to finish dialling, short enough that somebody who
- * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
- * have not typed the command that would make it succeed, and the message tells them which one.
- */
-const CONFIRM_WINDOW_MS = 12_000;
-const CONFIRM_POLL_MS = 500;
-/**
- * Poll until an app connects or the window runs out.
- *
- * A session that was ALREADY there when the wait began does not count, and this is the whole reason
- * the check reads ids rather than a count. A daemon is shared across every project on the machine,
- * so "a session exists" is satisfied by another app, by a stray tab, by yesterday's work — and
- * confirming this install on somebody else's session is a false green in the one message a user
- * reads to decide whether they are done. `reticle open` refuses the same way, for the same reason.
- *
- * The conservative direction is deliberate: an app that reconnects under an id it already held is
- * reported as not-yet-connected, and the message it gets sends them to `status`, which shows it. A
- * missed confirmation costs one command; a false one costs the whole point of confirming.
- */
-export async function confirmAppConnected(deps) {
-    const deadline = deps.now() + (deps.windowMs ?? CONFIRM_WINDOW_MS);
-    let before;
-    for (;;) {
-        const ids = await deps.listSessionIds();
-        // A port nobody is listening on cannot receive a session, and no amount of waiting changes that.
-        // One look settles it; polling on would spend the whole window to re-learn the first answer.
-        if (null === ids)
-            return InitConfirmation.NO_DAEMON;
-        const baseline = before;
-        if (baseline === undefined)
-            before = new Set(ids);
-        else if (ids.some((id) => !baseline.has(id)))
-            return InitConfirmation.CONNECTED;
-        if (deadline <= deps.now())
-            return InitConfirmation.NO_SESSION;
-        await deps.sleep(deps.pollMs ?? CONFIRM_POLL_MS);
-    }
-}
-const PROVE_COMMAND = '`npx @reticlehq/server status`';
-/**
- * What the user reads, in the marks the rest of the report already uses: `⚠` means work left to do
- * and nothing else, `ℹ` is worth reading but is not work, `✓` happened.
- *
- * Only NO_SESSION earns a `⚠`, and it earns it honestly: the app is wired and has not connected, so
- * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
- * up when the agent loads the tools — so it is a notice.
- */
-/**
- * Narrow "no app connected" using what the dev servers themselves announced.
- *
- * `confirmAppConnected` can only observe the bridge, so its NO_SESSION covers two situations with
- * OPPOSITE fixes: the dev server is not running Reticle at all, or it is and no page has been
- * opened. An announced entry is proof the plugin is loaded in the process that is actually running
- * — which means the config is right and it has already been restarted.
- *
- * Only the unexplained answer is sharpened. CONNECTED is the finished state and NO_DAEMON is a
- * different fact; neither becomes more true because a dev server is up.
- */
-export function sharpenWithDevServers(confirmation, running) {
-    if (confirmation !== InitConfirmation.NO_SESSION)
-        return confirmation;
-    return 0 === running.length ? InitConfirmation.NO_SESSION : InitConfirmation.NO_PAGE;
-}
-export function confirmationMessage(confirmation, port, running = []) {
-    if (confirmation === InitConfirmation.CONNECTED) {
-        return ('  [✓] an app is connected — that is the install finished, not just written.\n' +
-            '      Ask your agent to drive a flow.');
-    }
-    if (confirmation === InitConfirmation.NO_DAEMON) {
-        return (`  [ℹ] nothing is listening on port ${String(port)} yet, so no app could have connected and ` +
-            'this run did not wait for one.\n' +
-            '      The daemon starts on its own when your agent loads the Reticle tools. After that, ' +
-            `${PROVE_COMMAND} confirms the app.`);
-    }
-    if (confirmation === InitConfirmation.NO_PAGE) {
-        // Deliberately never says "restart". The announcement is proof they already did — telling them
-        // again is how a correct instruction reads as the tool not knowing what is going on.
-        const where = running.map((s) => `        ${s.url}`).join('\n');
-        return ('  [⚠] your dev server has Reticle loaded, and no page has connected yet — so the only step ' +
-            'left is opening the app.\n' +
-            `      Open it in a browser:\n${where}\n` +
-            `      ${PROVE_COMMAND} then confirms it.`);
-    }
-    return ('  [⚠] no app has connected yet — the files are written, the page half of the install is not ' +
-        'done.\n' +
-        '      Restart your dev server and load the app in a browser — or ask your agent to, which it is ' +
-        'now told to do for you, in the background and with the command from your own scripts.\n' +
-        `      ${PROVE_COMMAND} then confirms it, or says exactly why it has not connected.`);
-}
-/**
- * What a non-TTY run says instead of waiting.
- *
- * `init` deliberately does not block when nobody is at the terminal — a 12-second wait in a script
- * is wrong, and an agent driving `init` through a shell is never a TTY. But silence was the wrong
- * other half of that decision: the agent path IS the prescribed path (every skill and every README
- * block tells an agent to run exactly this command), so the one message joining "init finished" to
- * "an app connected" was withheld from most of the people who run it. They were left with files on
- * disk, an exit code of 0, and nothing saying the page half had not happened.
- *
- * It claims nothing it did not check. It did not look for a session, so it does not say whether one
- * exists — a one-shot look would be worse than none, because a daemon is shared across every project
- * on the machine and "a session exists" is satisfied by somebody else's app, which is the false
- * green `confirmAppConnected` refuses by design.
- */
-function unwatchedMessage(port) {
-    return ('  [ℹ] the files are written. An app CONNECTING is what finishes the install, and this run did ' +
-        'not wait to see one.\n' +
-        '      Start the dev server, load the app in a browser, then ' +
-        `${PROVE_COMMAND} — it confirms the app, or says exactly why it has not connected.\n` +
-        `      Bridge port ${String(port)}.`);
-}
-const WATCHING = (windowMs) => `  watching for an app to connect (up to ${String(Math.round(windowMs / 1000))}s) — Ctrl-C is safe, ` +
-    'everything above is already written.';
-/**
- * Finish `init` on evidence rather than on a write.
- *
- * The telemetry report happens HERE rather than inside `runInit`, so the one `init_completed` event
- * carries what was seen. Emitting inside `runInit` and again after the wait would double-count the
- * funnel it exists to measure, and a second event kind for the same command would need joining back
- * to the first before anybody could read either.
- */
-export async function confirmInstall(result, io, deps, report = reportInitOutcome) {
-    const outcome = result.outcome;
-    // No outcome means a dry run or an exit that already reported for itself (no package.json). A
-    // preview is not an install and must not land in the funnel as either a success or a failure.
-    if (outcome === undefined)
-        return;
-    if (!deps.interactive) {
-        // Still no waiting — see unwatchedMessage for why it speaks anyway.
-        io.print('');
-        io.print(unwatchedMessage(deps.port));
-        report(outcome);
-        return;
-    }
-    io.print('');
-    io.print(WATCHING(deps.windowMs ?? CONFIRM_WINDOW_MS));
-    const observed = await confirmAppConnected(deps);
-    const running = deps.listDevServers?.() ?? [];
-    const confirmation = sharpenWithDevServers(observed, running);
-    io.print(confirmationMessage(confirmation, deps.port, running));
-    report({ ...outcome, confirmation });
-}
-/** The real deps: the daemon's own status endpoint, and whether a human is watching. */
-export function nodeConfirmDeps(port = RETICLE_DEFAULT_PORT) {
-    return {
-        // Scoped to the project being set up. The registry is machine-wide, so unscoped it reported a
-        // sibling app's dev server as this one's — see devServersForProject.
-        listDevServers: () => devServersForProject(readDevServers(reticleStateHome()), {
-            projectId: readProjectId(process.cwd()),
-            root: process.cwd(),
-        }),
-        listSessionIds: async () => {
-            const payload = await fetchStatus(port);
-            // `fetchStatus` resolves undefined when nothing answered, which is precisely the "no daemon"
-            // case — a zero-session daemon and an absent one need opposite messages.
-            if (payload === undefined)
-                return null;
-            return summarizeStatus(payload).sessions.map((s) => s.sessionId);
-        },
-        now: () => Date.now(),
-        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-        interactive: true === process.stdout.isTTY,
-        port,
-    };
-}

package/dist/setup/dev-server-wait.d.ts

@@ -1,68 +0,0 @@
-/**
- * Deciding when a dev server we started is up, hung, or gone.
- *
- * Nothing else in the package owns a spawned dev server, so this is the one genuinely new decision
- * setup contributes. All three cases below were failures in the field:
- *
- * - a url in the output is an ANNOUNCEMENT, not readiness. Next prints `- Local: …` before it can
- *   serve, so a tab opened on that line lands on a 404 and the whole connect budget is then spent
- *   blaming the SDK for a server that had not finished starting.
- * - a launcher that EXITS is not necessarily a dead server. `astro dev` forks the real one, prints
- *   the url and returns, which was read as death and failed Astro every time.
- * - a fixed budget is the wrong instrument for "is this hung?". The heaviest real monorepo builds
- *   two shared packages before its app serves and was measured taking twenty minutes, while a
- *   genuinely wedged server writes nothing at all and gets exactly the same budget.
- */
-/** Everything the decision needs, gathered by the caller. */
-export interface WaitFacts {
-    /** The dev server's own output so far. */
-    readonly output: string;
-    /** Whether the process we spawned has exited. */
-    readonly launcherExited: boolean;
-    /** Whether the url we are watching answers. */
-    readonly serving: boolean;
-    /** Milliseconds since the dev server last wrote anything. */
-    readonly quietForMs: number;
-    /** Milliseconds since the wait began. */
-    readonly elapsedMs: number;
-    /**
-     * How long silence may mean "still starting" on THIS machine. Defaults to QUIET_MEANS_HUNG_MS.
-     *
-     * Passed in rather than read from the platform here, so this stays a pure decision and exactly one
-     * caller owns the platform check. 45s is generous on a laptop and tight on a cold Windows runner,
-     * where a first `npm run dev` optimises dependencies before Vite prints a line.
-     */
-    readonly quietMeansHungMs?: number;
-}
-export declare const WaitVerdict: {
-    /** It is up. Carry on. */
-    readonly READY: "ready";
-    /** Still building or still starting; keep waiting. */
-    readonly WAITING: "waiting";
-    /** The launcher exited and nothing it started is answering. */
-    readonly DEAD: "dead";
-    /** It has gone silent without ever serving. */
-    readonly HUNG: "hung";
-};
-export type WaitVerdict = (typeof WaitVerdict)[keyof typeof WaitVerdict];
-/** Silence for this long, with nothing served, means hung rather than busy. */
-export declare const QUIET_MEANS_HUNG_MS = 45000;
-/** Even a talkative dev server has had enough rope by here. */
-export declare const WAIT_CEILING_MS: number;
-/**
- * Whether to keep waiting.
- *
- * `serving` outranks everything: a launcher that exited while the port answers has DAEMONIZED, and
- * that is a live server whatever its parent did.
- */
-export declare function judgeWait(facts: WaitFacts): WaitVerdict;
-export declare function announcedUrl(output: string): string | undefined;
-/**
- * The url to watch: whatever the tool announced, else one composed from a port we OBSERVED our own
- * process group binding.
- *
- * The second is not a guess. `react-scripts` prints no parseable url outside a tty, so a CRA app
- * compiled successfully, served happily, and setup timed out insisting no url appeared — the
- * evidence there is the process we spawned, not a convention.
- */
-export declare function urlToWatch(output: string, observedPorts: readonly number[]): string | undefined;

package/dist/setup/dev-server-wait.js

@@ -1,67 +0,0 @@
-/**
- * Deciding when a dev server we started is up, hung, or gone.
- *
- * Nothing else in the package owns a spawned dev server, so this is the one genuinely new decision
- * setup contributes. All three cases below were failures in the field:
- *
- * - a url in the output is an ANNOUNCEMENT, not readiness. Next prints `- Local: …` before it can
- *   serve, so a tab opened on that line lands on a 404 and the whole connect budget is then spent
- *   blaming the SDK for a server that had not finished starting.
- * - a launcher that EXITS is not necessarily a dead server. `astro dev` forks the real one, prints
- *   the url and returns, which was read as death and failed Astro every time.
- * - a fixed budget is the wrong instrument for "is this hung?". The heaviest real monorepo builds
- *   two shared packages before its app serves and was measured taking twenty minutes, while a
- *   genuinely wedged server writes nothing at all and gets exactly the same budget.
- */
-export const WaitVerdict = {
-    /** It is up. Carry on. */
-    READY: 'ready',
-    /** Still building or still starting; keep waiting. */
-    WAITING: 'waiting',
-    /** The launcher exited and nothing it started is answering. */
-    DEAD: 'dead',
-    /** It has gone silent without ever serving. */
-    HUNG: 'hung',
-};
-/** Silence for this long, with nothing served, means hung rather than busy. */
-export const QUIET_MEANS_HUNG_MS = 45_000;
-/** Even a talkative dev server has had enough rope by here. */
-export const WAIT_CEILING_MS = 25 * 60_000;
-/**
- * Whether to keep waiting.
- *
- * `serving` outranks everything: a launcher that exited while the port answers has DAEMONIZED, and
- * that is a live server whatever its parent did.
- */
-export function judgeWait(facts) {
-    if (facts.serving)
-        return WaitVerdict.READY;
-    if (facts.launcherExited)
-        return WaitVerdict.DEAD;
-    if (facts.elapsedMs >= WAIT_CEILING_MS)
-        return WaitVerdict.HUNG;
-    // Output IS progress. Silence is what distinguishes a build from a wedge.
-    return facts.quietForMs >= (facts.quietMeansHungMs ?? QUIET_MEANS_HUNG_MS)
-        ? WaitVerdict.HUNG
-        : WaitVerdict.WAITING;
-}
-/** A url the dev server announced, if it has announced one. Never composed, only read. */
-const URL_IN_OUTPUT = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+/;
-export function announcedUrl(output) {
-    return URL_IN_OUTPUT.exec(output)?.[0];
-}
-/**
- * The url to watch: whatever the tool announced, else one composed from a port we OBSERVED our own
- * process group binding.
- *
- * The second is not a guess. `react-scripts` prints no parseable url outside a tty, so a CRA app
- * compiled successfully, served happily, and setup timed out insisting no url appeared — the
- * evidence there is the process we spawned, not a convention.
- */
-export function urlToWatch(output, observedPorts) {
-    const announced = announcedUrl(output);
-    if (undefined !== announced)
-        return announced;
-    const port = observedPorts[0];
-    return undefined === port ? undefined : `http://localhost:${port}`;
-}

package/dist/setup/drive-agent.d.ts

@@ -1,70 +0,0 @@
-/**
- * Asking a child agent to drive the app, and reading what it says back.
- *
- * The drive needs a model, and the model does not need to be the caller. A client reads its MCP
- * server list once at startup and cannot reload it, so an agent that has just run `init` does not
- * yet have the reticle_* tools — which is why the hand-driven procedure asks for a restart, and why
- * three runs in five ended there having shown the user nothing. A child process started after init
- * reads the list init just wrote. No restart, no lost context, no waiting on a human.
- *
- * Two details here are not stylistic, and both cost a real run to learn.
- */
-import { type DriverSpec } from './drive-plan.js';
-export interface DriveRequest {
-    readonly url: string;
-    readonly sessionId: string;
-    /** The journey to drive, in the caller's own words. Absent means the child picks one. */
-    readonly flow?: string | undefined;
-    /** The capabilities file, when the session says it was never finished. */
-    readonly unfinishedCapabilitiesFile?: string | undefined;
-    /** The tab is hidden or throttled, so the child should not blame the app for a frozen page. */
-    readonly tabThrottled: boolean;
-    readonly budgetUsd: number;
-    readonly model?: string | undefined;
-}
-interface DriveReport {
-    /** The agent's own account, kept verbatim and never treated as a pass on its own. */
-    readonly text: string;
-    readonly grade?: string | undefined;
-    readonly turns?: number | undefined;
-    readonly costUsd?: number | undefined;
-    /** Set when the run was cut short, naming where it had got to. */
-    readonly incomplete?: string | undefined;
-}
-/**
- * Findings are the point, not the verdict.
- *
- * A green verdict demonstrates the mechanism. What people remember is Reticle telling them
- * something they did not know — measured on a real app, a drive's own assertion passed and Reticle
- * overruled it on a 504 fired inside the action window, which the drive then reported rather than
- * explaining away. That only happens if the drive is asked for it: asked for a verdict alone, it
- * returns a verdict alone, and everything else the page did goes unmentioned.
- */
-/**
- * The task LEADS.
- *
- * Measured: with the situation first and a capabilities dump in the middle, a model answered "I
- * don't see an actual task or request from you yet" and drove nothing — one turn, no verdict, and
- * setup reported success. Context goes after the ask, never before it.
- */
-export declare function buildDrivePrompt(req: DriveRequest): string;
-/**
- * NDJSON, one event per line.
- *
- * `--output-format json` emits nothing until the run completes, so a drive killed at the timeout
- * left no trace of what it had been doing — measured four times on one app, every one reporting
- * "the drive produced no output". Streaming turns that into evidence, because spawnSync hands back
- * the stdout it collected before killing the child.
- */
-export declare function readDriveOutput(out: string): DriveReport;
-/**
- * The prompt goes on STDIN.
- *
- * `--allowedTools` is variadic: with the prompt passed positionally after it, the flag swallowed
- * the prompt as another tool name and the run exited in two seconds having done nothing, with the
- * error on stderr — which the caller was discarding. No flag ordering is safe across four CLIs.
- */
-export declare function driveWith(driver: DriverSpec, req: DriveRequest, cwd: string): DriveReport;
-/** Everything that is not Claude Code reports prose, so the report IS its output. */
-export declare function readPlainOutput(out: string): DriveReport;
-export {};