@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/cloud/harness-switch.js

@@ -0,0 +1,53 @@
+/**
+ * Write the harness switch back to the platform.
+ *
+ * The panel does not keep this state — it emits an intent and this puts it where the dashboard can
+ * see it, so the two surfaces cannot disagree. Only the switch is sent: somebody who chose a
+ * provider in the console must not have it reset by a panel that never rendered one. The platform's
+ * PUT is what guarantees that, not the verb -- it merges the fields it is given and leaves the rest,
+ * which its own spec pins ("leaves the fields it was not sent alone").
+ *
+ * It says PUT because that is what the platform registers. It said PATCH for one release, against a
+ * route that has only ever served GET and PUT, so every write 404'd. Nothing reported it: the call
+ * is fire-and-forget and failure here is deliberately silent, so the switch simply sprang back on
+ * the next snapshot and looked like a UI that would not stick.
+ *
+ * Failure is SILENT by design, and that deserves saying plainly rather than being discovered. A
+ * dev-only overlay that threw a dialog because a settings write timed out would be worse than one
+ * that quietly did not save; the next snapshot re-reads the platform, so a lost write shows up as
+ * the switch springing back, which is a truthful thing for it to do.
+ */
+import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+const CONFIG_PATH = '/v1/model/config';
+/** Same budget as the read beside it: a settings write must never hold anything up. */
+const TIMEOUT_MS = 2_000;
+/** `true` when the platform accepted it. Callers use this for logging, never to block a person. */
+export async function writeHarnessSwitch(env, enabled, doFetch = (url, init) => fetch(url, init), timeoutMs = TIMEOUT_MS) {
+    const key = apiKeyFrom(env);
+    const host = env[ReticleEnv.CLOUD_URL];
+    if (key === undefined || 0 === key.length)
+        return false;
+    if (host === undefined || 0 === host.length)
+        return false;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        // No projectId in the body: the key IS project-scoped, and the platform refuses to let a key
+        // name somebody else's project. Sending one would be asking for a privilege we do not have.
+        const res = await doFetch(`${host.replace(/\/+$/, '')}${CONFIG_PATH}`, {
+            method: 'PUT',
+            headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ harnessEnabled: enabled }),
+            signal: controller.signal,
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

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

@@ -0,0 +1,121 @@
+/**
+ * The derived records that ride along with runs, and the file each one lives in.
+ *
+ * A list rather than three hand-written blocks so adding a fourth is one line and cannot be
+ * half-done — the bundle, the hashing and the reporting all walk this.
+ */
+declare const DERIVED_RECORDS: readonly [{
+    readonly kind: "impact";
+    readonly file: "impact.json";
+}, {
+    readonly kind: "flake";
+    readonly file: "flake.json";
+}, {
+    readonly kind: "intent";
+    readonly file: "intent.json";
+}];
+type DerivedKind = (typeof DERIVED_RECORDS)[number]['kind'];
+/** What the machine reads from disk. Injected so a cycle is testable with no filesystem at all. */
+export interface SyncSource {
+    /** Every run artifact currently on disk. */
+    runs: () => ReadonlyArray<{
+        runId: string;
+        payload: unknown;
+    }>;
+    /** Every saved flow. Small, upserted by name, so they ride along whenever anything else does. */
+    flows: () => readonly unknown[];
+    /**
+     * Every bug capsule on disk — the minimal failing flow that reproduces a defect, plus its evidence.
+     *
+     * Rides along with flows, and for the same reason: small, upserted by id, and worth nothing on the
+     * machine that found the bug. A verdict count tells a dashboard THAT something broke; the capsule
+     * is the only artifact that lets somebody else make it break again.
+     */
+    capsules: () => readonly unknown[];
+    /** One derived record, or undefined when the file is absent. */
+    derived: (kind: DerivedKind) => unknown;
+}
+/** What the machine writes back. Separated from reads so a dry run is a source with no sink. */
+export interface SyncSink {
+    /** Persist the triage decisions pulled from the dashboard. */
+    writeIssues: (issues: PulledIssues) => void;
+    /** Persist the cursor and the bookkeeping. */
+    writeState: (state: CloudSyncState) => void;
+}
+/** A decision a human made on the dashboard, as the machine stores it. */
+interface PulledIssue {
+    status: string;
+    flowName: string | null;
+    title: string;
+    at: number;
+}
+export interface PulledIssues {
+    /** Keyed by the server's fingerprint — stable across runs, which is the point of it. */
+    triage: Record<string, PulledIssue>;
+}
+/** `.reticle/cloud-state.json`. This machine's side of the conversation, never git-checked. */
+export interface CloudSyncState {
+    /** Opaque. Handed back to the server verbatim; the machine must never parse or invent one. */
+    cursor?: string;
+    lastPushAt?: number;
+    lastPullAt?: number;
+    /** The last failure, kept so `reticle sync` can say why it is behind instead of just "0 sent". */
+    lastError?: string;
+}
+export interface SyncReport {
+    ok: boolean;
+    /** Runs the server accepted this cycle. */
+    runsSent: number;
+    /** Runs it refused, with the reason, so a bad artifact is visible rather than silently stuck. */
+    runsRejected: Array<{
+        index: number;
+        reason: string;
+    }>;
+    flowsSent: number;
+    /** Capsules the server accepted. Zero when it reported none, which includes not knowing the field. */
+    capsulesSent: number;
+    /** Which derived records had actually moved. Empty on a quiet cycle, which is the normal case. */
+    derivedSent: DerivedKind[];
+    /** Decisions collected from the dashboard. */
+    pulled: number;
+    /** True when the pull page was full — call again now rather than waiting for the next tick. */
+    morePending: boolean;
+    /**
+     * The repo holds NO artifacts at all — no runs, no flows, no derived records.
+     *
+     * Distinct from "everything here is already pushed", which is the healthy steady state and looks
+     * identical from the outside. An empty repo usually means the app announces no projectId, so its
+     * runs are pooling into a different root and this binding will never report anything. Tracked so
+     * the summary can tell a user which of the two they are looking at.
+     */
+    localIsEmpty?: boolean;
+    /** Set when the cycle could not complete. The local record is untouched either way. */
+    error?: string;
+}
+interface SyncDeps {
+    config: {
+        url: string;
+        apiKey: string;
+    };
+    source: SyncSource;
+    sink: SyncSink;
+    state: CloudSyncState;
+    now: () => number;
+    /** Injected so a cycle can be driven against a scripted server with no network. */
+    request: (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }) => Promise<{
+        status: number;
+        text: string;
+    }>;
+}
+/**
+ * Run one cycle. Never throws: the local record is already safe on disk, and a sync that can take
+ * down the thing it is backing up is worse than no sync.
+ */
+export declare function runSyncCycle(deps: SyncDeps): Promise<SyncReport>;
+/** One line a human can read, for the CLI and the daemon log. */
+export declare function describeSync(report: SyncReport): string;
+export {};

package/dist/memory/cloud/sync-cycle.js

@@ -0,0 +1,295 @@
+/**
+ * One full conversation with the dashboard: ask, send the difference, collect what came back.
+ *
+ * ── WHY IT LOOKS LIKE THIS ─────────────────────────────────────────────────────────────────────
+ * `.reticle/` is the source of truth and always will be. Reticle has to work with no account and no
+ * network; a verification that blocks on an HTTP round trip is one somebody switches off. So the
+ * dashboard is a REPLICA, and this is the replication protocol:
+ *
+ *   1. ASK      GET /v1/sync/status  → run ids it already holds, a content hash per derived record
+ *   2. SEND     POST /v1/sync        → only unseen runs, only records whose hash moved
+ *   3. COLLECT  GET /v1/sync/pull    → decisions a human made there, since our cursor
+ *   4. APPLY    write them to .reticle/issues.json so the HUD and the next run can see them
+ *
+ * ASK-THEN-SEND, not send-everything. A three-hour session rewrites impact.json on every tool call;
+ * uploading it each time would re-send the same megabytes dozens of times, and a sync that costs
+ * that much is one people turn off — which is the real failure, because a dashboard nobody syncs to
+ * is a dashboard nobody opens. When nothing has moved, a cycle sends nothing at all, and that is
+ * what makes running it on a timer affordable.
+ *
+ * HASHES, NOT TIMESTAMPS. Two machines comparing their own clocks is a guess: they drift, and a
+ * laptop that was asleep will cheerfully decide it is current. A content hash is an answer.
+ *
+ * BOTH DIRECTIONS, ALWAYS. The pull runs even when there is nothing to push — a quiet machine is
+ * precisely the one whose dashboard somebody has been triaging on, so skipping the pull when the
+ * push is empty would starve the direction that matters most.
+ *
+ * NOTHING IS DELETED LOCALLY ON SUCCESS. A lost response costs one redundant upload rather than a
+ * hole in the record, and the server dedupes by run id anyway.
+ *
+ * Every dependency is injected — the clock, the fetch, the reads and writes — because this is the
+ * one piece of Reticle that talks to a network AND to a disk, and it must be provable without either.
+ */
+import { ReticleDir } from '@reticlehq/core';
+import { hashPayload } from './sync-hash.js';
+/** The server's own doors. Kept beside the code that calls them, like the other cloud paths. */
+const SYNC_PATH = '/v1/sync';
+const SYNC_STATUS_PATH = '/v1/sync/status';
+const SYNC_PULL_PATH = '/v1/sync/pull';
+/**
+ * The derived records that ride along with runs, and the file each one lives in.
+ *
+ * A list rather than three hand-written blocks so adding a fourth is one line and cannot be
+ * half-done — the bundle, the hashing and the reporting all walk this.
+ */
+const DERIVED_RECORDS = [
+    { kind: 'impact', file: ReticleDir.IMPACT_FILE },
+    { kind: 'flake', file: ReticleDir.FLAKE_FILE },
+    { kind: 'intent', file: ReticleDir.INTENT_FILE },
+];
+const asJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const isRecord = (v) => 'object' === typeof v && null !== v;
+/**
+ * Run one cycle. Never throws: the local record is already safe on disk, and a sync that can take
+ * down the thing it is backing up is worse than no sync.
+ */
+export async function runSyncCycle(deps) {
+    const empty = {
+        ok: false,
+        runsSent: 0,
+        runsRejected: [],
+        flowsSent: 0,
+        capsulesSent: 0,
+        derivedSent: [],
+        pulled: 0,
+        morePending: false,
+    };
+    const call = async (path, init) => {
+        const res = await deps.request(`${deps.config.url}${path}`, {
+            method: init?.method ?? 'GET',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${deps.config.apiKey}`,
+            },
+            ...(init?.body === undefined ? {} : { body: init.body }),
+        });
+        return { status: res.status, json: asJson(res.text), text: res.text };
+    };
+    const nextState = { ...deps.state };
+    try {
+        // 1. ASK.
+        const status = await call(SYNC_STATUS_PATH);
+        if (200 !== status.status) {
+            const error = `status ${String(status.status)}: ${status.text.slice(0, 200)}`;
+            deps.sink.writeState({ ...nextState, lastError: error });
+            return { ...empty, error };
+        }
+        const held = isRecord(status.json) ? status.json : {};
+        /*
+         * Validated, not trusted. `new Set(someString)` builds a set of CHARACTERS, so a `knownRunIds`
+         * that arrived as a string made `known.has('a')` true and silently skipped any run whose id was
+         * one of those letters — the client deciding, on the server's malformed word, not to upload
+         * something the server does not have. Silent data loss is the one failure this protocol must
+         * not have, and an unreadable answer has to mean "it knows nothing", never "it knows this".
+         */
+        const known = new Set(Array.isArray(held.knownRunIds)
+            ? held.knownRunIds.filter((id) => 'string' === typeof id)
+            : []);
+        // Same rule for the hashes: only a string can equal a hash we computed, so anything else reads
+        // as "unknown" and the record is sent once. Re-sending costs a request; skipping costs the data.
+        const hashes = isRecord(held.stateHashes) ? held.stateHashes : {};
+        // 2. SEND — only what the server does not already have.
+        const allRuns = deps.source.runs();
+        const unsent = allRuns.filter((r) => !known.has(r.runId));
+        const derivedSent = [];
+        const bundle = {};
+        if (unsent.length > 0)
+            bundle['runs'] = unsent.map((r) => r.payload);
+        for (const { kind } of DERIVED_RECORDS) {
+            const payload = deps.source.derived(kind);
+            if (payload === undefined)
+                continue;
+            // The one comparison the whole protocol rests on. Same hash, do not send it.
+            if (hashPayload(payload) === hashes[kind])
+                continue;
+            bundle[kind] = payload;
+            derivedSent.push(kind);
+        }
+        // Flows are small and upserted by name, so they ride along whenever anything else does rather
+        // than earning a round trip of their own.
+        const ridesAlong = bundle['runs'] !== undefined || derivedSent.length > 0;
+        const flows = ridesAlong ? deps.source.flows() : [];
+        if (flows.length > 0)
+            bundle['flows'] = flows;
+        // Same gate as flows: only when something else is already going. A cycle that sent capsules and
+        // nothing else would wake the server on every tick of an idle machine.
+        const capsules = ridesAlong ? deps.source.capsules() : [];
+        if (capsules.length > 0)
+            bundle['capsules'] = capsules;
+        let runsSent = 0;
+        let flowsSent = 0;
+        let capsulesSent = 0;
+        let runsRejected = [];
+        if (Object.keys(bundle).length > 0) {
+            const pushed = await call(SYNC_PATH, { method: 'POST', body: JSON.stringify(bundle) });
+            if (200 !== pushed.status) {
+                const error = `sync ${String(pushed.status)}: ${pushed.text.slice(0, 200)}`;
+                deps.sink.writeState({ ...nextState, lastError: error });
+                return { ...empty, error };
+            }
+            const body = isRecord(pushed.json) ? pushed.json : {};
+            const runs = isRecord(body['runs']) ? body['runs'] : {};
+            const flowsPart = isRecord(body['flows']) ? body['flows'] : {};
+            // Absent means the server said nothing about capsules — an older one that does not know the
+            // field. Read as zero accepted, never as an error: an added field must not break a sync that
+            // was otherwise fine, and the push's own status code is what reports a real refusal.
+            const capsulesPart = isRecord(body['capsules']) ? body['capsules'] : {};
+            runsSent = 'number' === typeof runs['accepted'] ? runs['accepted'] : 0;
+            flowsSent = 'number' === typeof flowsPart['accepted'] ? flowsPart['accepted'] : 0;
+            capsulesSent = 'number' === typeof capsulesPart['accepted'] ? capsulesPart['accepted'] : 0;
+            runsRejected = Array.isArray(runs['rejected'])
+                ? runs['rejected']
+                : [];
+            nextState.lastPushAt = deps.now();
+        }
+        // 3. COLLECT — always, even when there was nothing to send.
+        const query = nextState.cursor === undefined ? '' : `?since=${encodeURIComponent(nextState.cursor)}`;
+        const pull = await call(`${SYNC_PULL_PATH}${query}`);
+        if (200 !== pull.status) {
+            // The push already landed; report it rather than throwing the whole cycle away.
+            const error = `pull ${String(pull.status)}: ${pull.text.slice(0, 200)}`;
+            deps.sink.writeState({ ...nextState, lastError: error });
+            return {
+                ...empty,
+                ok: false,
+                runsSent,
+                flowsSent,
+                capsulesSent,
+                derivedSent,
+                runsRejected,
+                error,
+            };
+        }
+        const pulled = isRecord(pull.json) ? pull.json : {};
+        const decisions = pulled.triage ?? [];
+        // 4. APPLY.
+        if (decisions.length > 0) {
+            const triage = {};
+            for (const d of decisions) {
+                triage[d.fingerprint] = {
+                    status: d.status,
+                    flowName: d.flowName ?? null,
+                    title: d.title ?? '',
+                    at: d.at,
+                };
+            }
+            deps.sink.writeIssues({ triage });
+        }
+        // The cursor is written even on an empty page: it is the server's, and it never goes backwards.
+        if ('string' === typeof pulled.cursor)
+            nextState.cursor = pulled.cursor;
+        nextState.lastPullAt = deps.now();
+        delete nextState.lastError;
+        deps.sink.writeState(nextState);
+        return {
+            ok: true,
+            runsSent,
+            runsRejected,
+            flowsSent,
+            capsulesSent,
+            derivedSent,
+            pulled: decisions.length,
+            morePending: true === pulled.more,
+            /*
+             * Nothing on disk at all, as opposed to nothing NEW. Computed from what the source offered
+             * before any cursor filtering, because a repo whose runs were all already pushed is healthy
+             * and a repo that has never recorded one is usually misconfigured.
+             */
+            localIsEmpty: 0 === allRuns.length &&
+                0 === deps.source.flows().length &&
+                DERIVED_RECORDS.every(({ kind }) => deps.source.derived(kind) === undefined),
+        };
+    }
+    catch (error) {
+        // A network that is down is not an error condition for a local-first tool; it is Tuesday.
+        const message = describeTransportError(error, deps.config.url);
+        deps.sink.writeState({ ...nextState, lastError: message });
+        return { ...empty, error: message };
+    }
+}
+/**
+ * Say WHICH host failed and WHY.
+ *
+ * Node's fetch rejects with the bare string "fetch failed" and hides the real reason — a refused
+ * connection, a bad hostname, an expired certificate — one level down in `cause`. A machine that
+ * has quietly stopped syncing shows that string in `reticle whoami`, and on its own it is
+ * indistinguishable from every other network problem, so the person reading it learns nothing and
+ * checks nothing. Naming the origin and the underlying code turns it into one thing to look at.
+ */
+function describeTransportError(error, url) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause;
+    if (!(cause instanceof Error))
+        return `${error.message} (${url})`;
+    const code = cause.code;
+    // The code and the message are each sometimes empty — an aggregate DNS failure carries a code and
+    // no text, a TLS failure the reverse. Joined only when both are there, so the line never trails
+    // off into a dangling separator.
+    const parts = ['string' === typeof code && code.length > 0 ? code : '', cause.message].filter((part) => part.length > 0);
+    const detail = parts.join(': ');
+    return 0 === detail.length
+        ? `${error.message} (${url})`
+        : `${error.message} — ${detail} (${url})`;
+}
+/** One line a human can read, for the CLI and the daemon log. */
+export function describeSync(report) {
+    if (report.error !== undefined)
+        return `sync failed — ${report.error}`;
+    const sent = [];
+    if (report.runsSent > 0)
+        sent.push(`${String(report.runsSent)} run(s)`);
+    if (report.flowsSent > 0)
+        sent.push(`${String(report.flowsSent)} flow(s)`);
+    if (report.capsulesSent > 0)
+        sent.push(`${String(report.capsulesSent)} capsule(s)`);
+    if (report.derivedSent.length > 0)
+        sent.push(report.derivedSent.join(', '));
+    /*
+     * "Nothing to send" is a statement about the QUEUE, and it is false the moment the queue was full
+     * and the server threw it away. Built from what was accepted, the sentence used to read "nothing
+     * to send, 3 rejected" — something was very much sent, and the reader is told both that it was
+     * not and nothing about why.
+     */
+    const push = sent.length > 0
+        ? `sent ${sent.join(' + ')}`
+        : report.runsRejected.length > 0
+            ? 'nothing accepted'
+            : true === report.localIsEmpty
+                ? // Not the same statement as "nothing to send", which describes a repo that is simply up
+                    // to date. This one has never recorded anything, which for a LINKED repo usually means
+                    // the app announces no projectId and its runs are landing under a different root.
+                    'nothing recorded here yet — if this app has been driven, it is reporting somewhere else'
+                : 'nothing to send';
+    const pull = 0 === report.pulled
+        ? ''
+        : `, pulled ${String(report.pulled)} decision(s)${report.morePending ? ' (more waiting)' : ''}`;
+    /*
+     * One reason, not a count. A rejection count tells somebody they have a problem and nothing about
+     * which problem — and these arrive from a BACKGROUND daemon, so the summary line is often the only
+     * place anybody ever sees it. Rejections in one cycle almost always share a cause (a version skew
+     * refuses every payload the same way), so the first reason plus the count is the whole story
+     * without printing a line per run; `reticle sync` still lists them all.
+     */
+    const bad = 0 === report.runsRejected.length
+        ? ''
+        : `, ${String(report.runsRejected.length)} rejected — ${report.runsRejected[0]?.reason ?? 'no reason given'}`;
+    return `${push}${pull}${bad}`;
+}

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

@@ -0,0 +1,73 @@
+import { type SyncReport } from './sync-cycle.js';
+import { type ProjectCloud } from './cloud-config.js';
+import type { FileSystemPort } from '../project/fs/fs-port.js';
+interface SyncDaemonDeps {
+    reticleRoot: string;
+    /** Resolved per tick, not once: a repo linked while the daemon is alive starts syncing itself. */
+    cloud: () => Promise<ProjectCloud>;
+    /**
+     * Every OTHER `.reticle` root on this machine that might be linked.
+     *
+     * One daemon serves many projects — that is what `artifactRootFor` exists for — and this loop
+     * pushed exactly one of them: whichever directory the daemon happened to be started in. Every
+     * other linked repo went silent, and silent is indistinguishable from "nobody verified anything",
+     * which is the worst possible failure for a dashboard somebody is deciding budget on.
+     *
+     * Optional: a caller that does not supply it gets exactly the old single-root behaviour.
+     */
+    otherRoots?: () => Promise<readonly string[]>;
+    /** Resolve the link for a root that is not this daemon's own. Required to use `otherRoots`. */
+    cloudFor?: (root: string) => Promise<ProjectCloud>;
+    now?: () => number;
+    intervalMs?: number;
+    /** Injected for the test; the real one is `fetch`. */
+    request?: (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }) => Promise<{
+        status: number;
+        text: string;
+    }>;
+}
+export interface SyncDaemon {
+    /** Run one cycle now, whatever the timer is doing. Returns undefined when not linked. */
+    syncNow: () => Promise<SyncReport | undefined>;
+    /**
+     * Something worth shipping just landed — cycle soon rather than at the next tick.
+     *
+     * A verification RUN is the artifact people wait on, and making them wait up to a full interval
+     * for it is the difference between a dashboard that reflects the work and one that lags it. The
+     * counters keep the timer: they are a rolling aggregate, and a write per tool call to move a
+     * number nobody is watching that second is exactly the cost the interval exists to avoid.
+     *
+     * Coalescing, never additive: many nudges in a burst collapse into one cycle.
+     */
+    nudge: () => void;
+    stop: () => void;
+}
+/**
+ * Start the loop. Safe to call for an UNLINKED project: it resolves the link on every tick and does
+ * nothing until one appears, which is what lets `reticle link` take effect without a restart.
+ */
+export declare function startSyncDaemon(deps: SyncDaemonDeps): SyncDaemon;
+/**
+ * Start cloud sync for a daemon and hand back the two hooks the daemon wires to it.
+ *
+ * The wiring lived in `index.ts`, which sits exactly on the thousand-line cap — so the next thing
+ * anyone needed there could not be added without a split, and this is the block that most obviously
+ * did not belong in a bootstrap file. Four calls that are all one concern: what to sync, where else
+ * to look, how a landed run wakes it, and what the panel's button does.
+ *
+ * Returns the daemon itself: the caller still owns when to nudge, when to sync now, and when to
+ * stop. Only the CONSTRUCTION moved, which is the part that was four interdependent arguments about
+ * resolving a credential — and the part a bootstrap file has no business spelling out.
+ */
+export declare function attachCloudSync(deps: {
+    fs: FileSystemPort;
+    reticleRoot: string;
+    homeDir: string;
+    env: NodeJS.ProcessEnv;
+    otherRoots: () => readonly string[];
+}): SyncDaemon;
+export {};