@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/cloud/account-state.js

@@ -0,0 +1,70 @@
+/**
+ * Is this machine signed in to a Reticle workspace?
+ *
+ * Asked by the HUD, and there are two sources that must not be reimplemented per caller: the session
+ * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_API_KEY` for an agent that
+ * was handed a key instead. Everything that gates on login — the defect sync button, the prompt to sign
+ * in — resolves through here.
+ *
+ * Node-only by design: it reads the filesystem and the environment, so it lives in the server and
+ * only the SHAPE (`AccountState`) is in core, where the contract belongs.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir, apiKeyFrom } from '@reticlehq/core';
+import { CloudEnv } from './cloud-sync.js';
+import { SESSION_FILE } from '../../command/cli/cloud-kit.js';
+/** Signed OUT is the safe answer: it shows the way in, where a wrong "signed in" hides it. */
+const SIGNED_OUT = { signedIn: false };
+/**
+ * The fields we read off the session file, and nothing else.
+ *
+ * Narrowed by hand rather than parsed with the login schema on purpose: this function must be unable
+ * to carry a token even if the file grows one, and the surest way to guarantee that is never to bind
+ * it to a name here.
+ */
+function fromSessionFile(home) {
+    try {
+        const raw = JSON.parse(readFileSync(join(home, ReticleDir.ROOT, SESSION_FILE), 'utf8'));
+        if ('object' !== typeof raw || null === raw)
+            return undefined;
+        const record = raw;
+        // A half-written or hand-edited file must not read as authenticated. `signedIn: true` is the
+        // claim that costs something when wrong, because it hides the way in.
+        if ('string' !== typeof record['token'] || 0 === record['token'].length)
+            return undefined;
+        const org = record['orgName'];
+        const email = record['email'];
+        const host = record['url'];
+        return {
+            signedIn: true,
+            ...('string' === typeof org && org.length > 0 ? { org } : {}),
+            // No cloud writes this yet, so the absent branch is the live one. Read rather than derived, so
+            // a cloud that starts returning it needs no client release.
+            ...('string' === typeof email && email.length > 0 ? { email } : {}),
+            ...('string' === typeof host && host.length > 0 ? { host } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the account state for this machine.
+ *
+ * The env key WINS over the session file: an agent handed a key is authenticating as that key,
+ * whatever a human left on disk, and reporting the human's org there would be a lie about who is
+ * acting.
+ */
+export function readAccountState(home, env) {
+    // Through the resolver, so a machine still exporting the key's previous name is still signed in.
+    const key = apiKeyFrom(env);
+    const url = env[CloudEnv.URL];
+    if (key !== undefined) {
+        return {
+            signedIn: true,
+            ...('string' === typeof url && url.length > 0 ? { host: url.replace(/\/+$/, '') } : {}),
+        };
+    }
+    return fromSessionFile(home) ?? SIGNED_OUT;
+}

package/dist/memory/cloud/cloud-config.d.ts

@@ -0,0 +1,79 @@
+import type { FileSystemPort } from '../project/fs/fs-port.js';
+import { type CloudConfig } from './cloud-sync.js';
+/** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
+/** Re-exported so the existing importers keep working; the string itself lives in core. */
+export declare const CLOUD_LINK_FILE: "cloud.json";
+/** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
+export declare const CREDENTIALS_FILE = "credentials.json";
+/** What the daemon mirrors to the cloud for a project. Each surface is independently toggleable. */
+interface SyncPolicy {
+    /** Push verification-run artifacts to the dashboard Runs tab. */
+    runs: boolean;
+    /** Push per-flow project-memory outcomes (the regression history). */
+    memory: boolean;
+    /** Sync saved flow files (the shared regression suite). */
+    flows: boolean;
+    /**
+     * Push bug capsules — the minimal failing flow for a defect, plus its evidence.
+     *
+     * Its OWN toggle rather than riding on `flows`, because it carries more than a flow does: a
+     * capsule's blast radius names the requests and store keys an action touched WITHOUT declaring
+     * them, which is app data and the reason the artifact is worth anything. Somebody who chose to
+     * share a regression suite has not thereby chosen to share that, and this interface already
+     * promises each surface is independently toggleable.
+     *
+     * Defaults ON, like the other three: the capsule is the only artifact that lets a teammate make
+     * the bug happen again, and a defect nobody else can reproduce is a defect nobody else can fix.
+     */
+    capsules: boolean;
+}
+/** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
+export declare const VerifyMode: {
+    readonly LOCAL: "local";
+    readonly SERVER: "server";
+};
+export type VerifyMode = (typeof VerifyMode)[keyof typeof VerifyMode];
+/** The resolved cloud picture for one project. `config === null` ⇒ cloud NOT attached (stay 100% local). */
+export interface ProjectCloud {
+    config: CloudConfig | null;
+    policy: SyncPolicy;
+    verify: VerifyMode;
+    /** The cloud project id this project is linked to (for display/logging); null when env-fallback. */
+    projectId: string | null;
+}
+/** Look up the API key for a cloud project id in the user credentials map. */
+/**
+ * The API key this machine holds for one project ON ONE CLOUD.
+ *
+ * The store used to be keyed by cloud project id ALONE, which collides in the case that is not rare
+ * at all — it is the default. `reticle link` names every project "default", so a repo linked to a
+ * self-hosted install and a repo linked to the hosted service both claim the slot `default`, and
+ * whichever was linked last wins. Measured: two repos on one machine, and the production key was
+ * being sent to a localhost server, which answered 401.
+ *
+ * That is the same class of defect as sending a session token to a host that did not issue it, and
+ * it deserves the same answer: a credential is scoped to the cloud that minted it, and no credential
+ * at all is better than one belonging to somewhere else.
+ *
+ * Two shapes are accepted. `{ key, url }` is what is written now and is checked against the URL
+ * being dialled. A bare string is the legacy shape, has no URL to check, and is still honoured —
+ * refusing it would silently unlink every repo that predates this change, which is a worse outage
+ * than the collision. Re-linking upgrades a repo to the safe shape.
+ */
+export declare const credentialSlot: (url: string, projectId: string, orgId?: string) => string;
+/**
+ * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
+ * user credential store; if the project isn't linked (no cloud.json), falls back to the global env creds
+ * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
+ */
+export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv): Promise<ProjectCloud>;
+/**
+ * The linked credential, as a port the tool surface can be handed.
+ *
+ * Lives here, beside the resolver it wraps, rather than in the daemon bootstrap: `index.ts` sits
+ * exactly on the thousand-line cap, so a caller that needs this in three lines has to put those
+ * three lines somewhere they belong. The harness reads it so a machine that has run `reticle link`
+ * needs no exported key — see `withLinkedCredential`.
+ */
+export declare const linkedCloudPort: (fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv) => () => Promise<CloudConfig | null>;
+export {};

package/dist/memory/cloud/cloud-config.js

@@ -0,0 +1,156 @@
+/**
+ * Per-project cloud resolution for a SHARED daemon. One reticle MCP/daemon serves many projects; each
+ * project declares its own cloud binding + sync policy in `<root>/.reticle/cloud.json`, and the SECRET
+ * (the API key) lives once per user in `~/.reticle/credentials.json` (keyed by cloud project id) — never
+ * in the repo. The daemon resolves "is cloud attached for THIS project, and what should I push where?"
+ * from those two files, falling back to the global `RETICLE_CLOUD_*` env vars for the single-project /
+ * CI case (backward compatible).
+ *
+ * Vercel-style split: `.reticle/cloud.json` is the safe-to-commit-but-gitignored binding, the key is a
+ * user-level credential. "Cloud attached" = a valid link file AND a key for its project id (or env creds).
+ */
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { resolveCloudConfig } from './cloud-sync.js';
+/** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
+/** Re-exported so the existing importers keep working; the string itself lives in core. */
+export const CLOUD_LINK_FILE = ReticleDir.CLOUD_LINK_FILE;
+/** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
+export const CREDENTIALS_FILE = 'credentials.json';
+const DEFAULT_SYNC_POLICY = { runs: true, memory: true, flows: true, capsules: true };
+/** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
+export const VerifyMode = { LOCAL: 'local', SERVER: 'server' };
+const asBool = (v, fallback) => ('boolean' === typeof v ? v : fallback);
+/** Read + JSON-parse a file, or null on any problem (missing/malformed) — never throws. */
+async function readJson(fs, path) {
+    try {
+        if (!(await fs.exists(path)))
+            return null;
+        return JSON.parse(await fs.readFile(path));
+    }
+    catch {
+        return null;
+    }
+}
+/** Validate the shape of `.reticle/cloud.json`. Requires projectId + url; policy/verify default in. */
+function parseLink(raw) {
+    if (typeof raw !== 'object' || null === raw)
+        return null;
+    const o = raw;
+    if (typeof o.projectId !== 'string' || 0 === o.projectId.length)
+        return null;
+    if (typeof o.url !== 'string' || 0 === o.url.length)
+        return null;
+    const sync = 'object' === typeof o.sync && o.sync !== null ? o.sync : {};
+    return {
+        projectId: o.projectId,
+        orgId: 'string' === typeof o.orgId && o.orgId.length > 0 ? o.orgId : undefined,
+        url: o.url,
+        sync: {
+            runs: asBool(sync.runs, DEFAULT_SYNC_POLICY.runs),
+            memory: asBool(sync.memory, DEFAULT_SYNC_POLICY.memory),
+            flows: asBool(sync.flows, DEFAULT_SYNC_POLICY.flows),
+            capsules: asBool(sync.capsules, DEFAULT_SYNC_POLICY.capsules),
+        },
+        verify: o.verify === VerifyMode.SERVER ? VerifyMode.SERVER : VerifyMode.LOCAL,
+    };
+}
+/** Look up the API key for a cloud project id in the user credentials map. */
+/**
+ * The API key this machine holds for one project ON ONE CLOUD.
+ *
+ * The store used to be keyed by cloud project id ALONE, which collides in the case that is not rare
+ * at all — it is the default. `reticle link` names every project "default", so a repo linked to a
+ * self-hosted install and a repo linked to the hosted service both claim the slot `default`, and
+ * whichever was linked last wins. Measured: two repos on one machine, and the production key was
+ * being sent to a localhost server, which answered 401.
+ *
+ * That is the same class of defect as sending a session token to a host that did not issue it, and
+ * it deserves the same answer: a credential is scoped to the cloud that minted it, and no credential
+ * at all is better than one belonging to somewhere else.
+ *
+ * Two shapes are accepted. `{ key, url }` is what is written now and is checked against the URL
+ * being dialled. A bare string is the legacy shape, has no URL to check, and is still honoured —
+ * refusing it would silently unlink every repo that predates this change, which is a worse outage
+ * than the collision. Re-linking upgrades a repo to the safe shape.
+ */
+export const credentialSlot = (url, projectId, orgId) => orgId === undefined || 0 === orgId.length
+    ? `${normalizeCloudUrl(url)}::${projectId}`
+    : `${normalizeCloudUrl(url)}::org::${orgId}::${projectId}`;
+function credentialFor(raw, projectId, url, orgId) {
+    if (typeof raw !== 'object' || null === raw)
+        return null;
+    const store = raw;
+    /*
+     * The ORG slot first, because cloud + project is still not an identity.
+     *
+     * `link` names every project "default", so two ACCOUNTS on one cloud both claimed the slot
+     * `<url>::default` and the last link won: a new workspace could be handed a stored key belonging
+     * to another organisation — valid, so every validation passed, and every run it pushed would land
+     * in a stranger's dashboard. Keying by cloud fixed two clouds colliding; only keying by ORG fixes
+     * two tenants colliding.
+     */
+    const orgScoped = orgId === undefined ? undefined : store[credentialSlot(url, projectId, orgId)];
+    if ('string' === typeof orgScoped && orgScoped.length > 0)
+        return orgScoped;
+    /*
+     * Then the cloud+project slot, which is what every repo linked before this change still holds. It
+     * is ambiguous between tenants by construction, which is why it is consulted second and why the
+     * writer above stopped producing it as the only entry.
+     */
+    const composite = store[credentialSlot(url, projectId)];
+    if ('string' === typeof composite && composite.length > 0)
+        return composite;
+    const entry = store[projectId];
+    if ('string' === typeof entry)
+        return entry.length > 0 ? entry : null;
+    if (typeof entry !== 'object' || null === entry)
+        return null;
+    const record = entry;
+    const key = record['key'];
+    const forUrl = record['url'];
+    if ('string' !== typeof key || 0 === key.length)
+        return null;
+    // A credential stamped with a DIFFERENT cloud is not this project's credential, however much the
+    // project ids match. Refuse rather than dial somewhere with somebody else's key.
+    if ('string' === typeof forUrl && normalizeCloudUrl(forUrl) !== normalizeCloudUrl(url))
+        return null;
+    return key;
+}
+/** Trailing slashes are not identity: `https://x/` and `https://x` are one cloud. */
+const normalizeCloudUrl = (url) => url.replace(/\/+$/, '');
+/**
+ * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
+ * user credential store; if the project isn't linked (no cloud.json), falls back to the global env creds
+ * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
+ */
+export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
+    const link = parseLink(await readJson(fs, join(reticleRoot, CLOUD_LINK_FILE)));
+    if (null === link) {
+        // No per-project link → the env vars are the whole story (legacy single-project / CI behaviour).
+        return {
+            config: resolveCloudConfig(env),
+            policy: DEFAULT_SYNC_POLICY,
+            verify: VerifyMode.LOCAL,
+            projectId: null,
+        };
+    }
+    const policy = {
+        runs: link.sync.runs ?? DEFAULT_SYNC_POLICY.runs,
+        memory: link.sync.memory ?? DEFAULT_SYNC_POLICY.memory,
+        flows: link.sync.flows ?? DEFAULT_SYNC_POLICY.flows,
+        capsules: link.sync.capsules ?? DEFAULT_SYNC_POLICY.capsules,
+    };
+    const key = credentialFor(await readJson(fs, join(homeDir, ReticleDir.ROOT, CREDENTIALS_FILE)), link.projectId, link.url, link.orgId);
+    const config = key !== null ? { url: link.url.replace(/\/+$/, ''), apiKey: key } : null;
+    return { config, policy, verify: link.verify, projectId: link.projectId };
+}
+/**
+ * The linked credential, as a port the tool surface can be handed.
+ *
+ * Lives here, beside the resolver it wraps, rather than in the daemon bootstrap: `index.ts` sits
+ * exactly on the thousand-line cap, so a caller that needs this in three lines has to put those
+ * three lines somewhere they belong. The harness reads it so a machine that has run `reticle link`
+ * needs no exported key — see `withLinkedCredential`.
+ */
+export const linkedCloudPort = (fs, reticleRoot, homeDir, env) => async () => (await resolveProjectCloud(fs, reticleRoot, homeDir, env)).config;

package/dist/memory/cloud/cloud-sync.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Optional cloud sync for saved flows. "Logged in" here means the two cloud env vars are set (written by
+ * `reticle login` later; settable by hand today): the hosted URL and an API key from the Reticle
+ * dashboard. When present, a freshly-saved flow is pushed to `POST /v1/flows` so the team's regression
+ * suite lives in the cloud — surviving refactors and runnable in CI. When absent, sync is a no-op and
+ * everything stays 100% local (the "no phone-home" default: nothing leaves the machine unless you opt in).
+ *
+ * Sync is best-effort: a network failure NEVER fails the local save. The flow is already on disk; the
+ * cloud copy is an enhancement, so a push error is logged and swallowed.
+ */
+import { z } from 'zod';
+import { type FlowFile, type ReticleVerificationRun, type RunRecord, type VerifyProgressEvent } from '@reticlehq/core';
+/**
+ * Env var names — the presence of BOTH is what "logged in" means for cloud sync.
+ *
+ * `KEY` names the CURRENT spelling only. The previous one is still honoured, through `apiKeyFrom`
+ * below, which is the one place that knows there are two.
+ */
+export declare const CloudEnv: {
+    readonly URL: "RETICLE_CLOUD_URL";
+    readonly KEY: "RETICLE_API_KEY";
+};
+export interface CloudConfig {
+    url: string;
+    apiKey: string;
+}
+/** Resolve cloud credentials from the environment, or null when not logged in (sync disabled). */
+export declare function resolveCloudConfig(env: NodeJS.ProcessEnv): CloudConfig | null;
+export declare const CLOUD_VERIFY_TIMEOUT_MS = 120000;
+/**
+ * The fetch every cloud call goes through. Adds the abort signal, and turns the abort into a message
+ * that says what happened and what to do — a bare `AbortError` reaching a user or an agent is a riddle,
+ * and the agent-facing half of this product is judged on whether its errors are actionable.
+ */
+export declare function cloudFetch(url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}, timeoutMs?: number): Promise<Response>;
+export declare const SyncOutcome: {
+    readonly SYNCED: "synced";
+    readonly SKIPPED: "skipped";
+    readonly FAILED: "failed";
+};
+export type SyncOutcome = (typeof SyncOutcome)[keyof typeof SyncOutcome];
+interface SyncResult {
+    outcome: SyncOutcome;
+    status?: number;
+    error?: string;
+}
+/** A fetch-shaped function, injected so the sync is testable without a real network. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+/** GET-shaped fetch (no body, reads back JSON), injected so the read is testable without a network. */
+export type FetchGetLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+/**
+ * Push one flow to the cloud. `projectId` scopes it to this app. Returns a structured outcome; never
+ * throws — a failure is reported, not propagated, so the local save is authoritative.
+ */
+export declare function syncFlowToCloud(flow: FlowFile, config: CloudConfig | null, projectId: string | undefined, fetchImpl: FetchLike): Promise<SyncResult>;
+/**
+ * Push one verification-run artifact to the cloud. This is what makes "runs recorded on the dashboard"
+ * real once a user shifts to the server: after `reticle verify` produces a run, it lands in the team's
+ * hosted history with its verdict. Same opt-in creds as flow sync — absent → no-op (stays local). The
+ * cloud's `POST /v1/runs` ingests the RAW artifact (validated by the same `@reticlehq/core` schema that
+ * built it), so the body is the run itself, not a wrapper. Best-effort: never throws, never blocks exit.
+ */
+export declare function syncRunToCloud(run: ReticleVerificationRun, config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
+/**
+ * Push one project-memory RunRecord (a flow replay/verify outcome) to the cloud so the team's server-side
+ * regression history stays current: "did this development break a previously-passing flow?" is answered
+ * from these. Same opt-in creds as the others — absent → no-op (project.json stays the local source of
+ * truth). `projectId` scopes an org's multiple suites. Best-effort: never throws, never blocks the tool.
+ */
+export declare function syncRunRecordToCloud(record: RunRecord, projectId: string | undefined, config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
+/**
+ * Read the team's server-side regression report back down to the agent. This is the half that makes the
+ * system "agent-friendly across context loss": a fresh agent (new session, CI box, teammate's machine)
+ * whose local .reticle/project.json is empty can still ask the ONE tool it knows — reticle_project — and
+ * get the durable cloud memory of what's broken vs before. Returns the raw report (shape owned by the
+ * cloud), or null when not logged in / unreachable — so the caller degrades to local-only, never fails.
+ */
+export declare function fetchProjectRegressionFromCloud(config: CloudConfig | null, projectId: string | undefined, fetchImpl: FetchGetLike): Promise<unknown>;
+/** POST-that-reads-JSON fetch shape (injected so the server-verify submit is testable without a network). */
+export type FetchPostJsonLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+/** The hosted runner's report, validated at the boundary (the full shape is owned by the cloud app). */
+declare const ServerVerificationSchema: z.ZodObject<{
+    verificationId: z.ZodString;
+    verdict: z.ZodNullable<z.ZodString>;
+    flows: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        status: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        status: string;
+        name: string;
+    }, {
+        status: string;
+        name: string;
+    }>, "many">;
+    summary: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    verificationId: string;
+    verdict: string | null;
+    flows: {
+        status: string;
+        name: string;
+    }[];
+    summary: string;
+}, {
+    verificationId: string;
+    verdict: string | null;
+    flows: {
+        status: string;
+        name: string;
+    }[];
+    summary: string;
+}>;
+export type ServerVerification = z.infer<typeof ServerVerificationSchema>;
+/**
+ * Delegate a verification to the hosted runner: submit the preview URL + flow names to `POST
+ * /v1/verifications` and read back the report. This is the `verify: 'server'` half of the per-project
+ * config — the WORK runs on the server (real browser pool, later), not the local machine. The server
+ * records the verification itself, so there is no separate run-push. Returns null when not attached or the
+ * submit fails, so the caller falls back to a local replay. Never throws.
+ */
+export declare function submitServerVerification(body: {
+    previewUrl: string;
+    flows: string[];
+    source: string;
+}, config: CloudConfig | null, fetchImpl: FetchPostJsonLike): Promise<ServerVerification | null>;
+/**
+ * Narrate a run in flight to the dashboard.
+ *
+ * ## Why this exists
+ *
+ * Everything else here syncs a FINISHED artifact. That is the right shape for evidence and the wrong
+ * shape for the minutes a verification is actually running: a browser launches, flows replay one at
+ * a time, and until the run ends the dashboard has nothing to show but a spinner. A run that is
+ * working and a run that has died are indistinguishable for the whole of its duration, and somebody
+ * watching sat on exactly that ambiguity for fifteen minutes.
+ *
+ * ## Why it is batched
+ *
+ * One request per flow is one request per flow. A fifty-flow suite would open a hundred connections
+ * to say things that are only interesting in aggregate, so events accumulate and go out on a timer.
+ * Two seconds is well under the time a person waits before deciding a page is broken, and well over
+ * the time a fast flow takes — so a burst of quick replays becomes one request, not twenty.
+ *
+ * ## Why it can never matter
+ *
+ * Opt-in like every other cloud call (no credentials → no-op, nothing leaves the machine), and
+ * best-effort at every layer: a failed flush is dropped, never retried and never surfaced. This is
+ * narration. The run artifact is the record, it syncs separately, and nothing here is graded or
+ * allowed to influence a verdict or an exit code.
+ */
+export declare function syncProgressToCloud(runId: string, events: readonly VerifyProgressEvent[], config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
+/** How long events accumulate before a flush. See the batching note above. */
+export declare const PROGRESS_FLUSH_MS = 2000;
+/**
+ * A listener that buffers progress and ships it on a timer.
+ *
+ * Returned with its own `flush` and `stop` so the caller can push the last events out when the run
+ * ends — otherwise the most interesting event of all, the one saying it finished, waits for a timer
+ * that is about to be cleared.
+ *
+ * The timer is `unref`'d where the runtime supports it: a narration timer must never be the reason a
+ * CLI process stays alive after its work is done.
+ */
+export declare function createProgressReporter(runId: string, config: CloudConfig | null, fetchImpl: FetchLike, flushMs?: number): {
+    onProgress: (event: VerifyProgressEvent) => void;
+    flush: () => Promise<void>;
+    stop: () => void;
+};
+export {};