@reticlehq/server 3.6.0 → 3.7.0

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

@@ -1,26 +1,22 @@
-/**
- * The harness switch, cached for a HUD that reads it inline.
- *
- * `fetchPlatformConfig` already asks the platform and parses the answer; this adds the one thing the
- * impact snapshot needs and the drive path does not — a SYNCHRONOUS read. The snapshot is rebuilt
- * dozens of times a session, the answer changes about as often as somebody opens a settings page,
- * and a panel that awaited the network on every repaint would be a panel that stutters.
- *
- * Deliberately the same shape as `harnessOfferSource` next door rather than a shared abstraction:
- * two callers with the same caching problem is not yet a pattern, and the day one of them needs a
- * different staleness rule the shared version becomes the awkward one.
- *
- * Every failure answers `undefined`, which the HUD must read as "we have not heard" and render as NO
- * control — never as "off". Showing a switch that cannot be honoured is worse than showing none.
- *
- * The loader arrives as a PORT rather than an import. Reading the platform lives in
- * `features/harness`, and a cloud-memory file reaching into a feature is the reach the directory
- * guard refuses — correctly, and for the same reason it refused the tool surface reaching the other
- * way. Whoever wires the daemon owns both sides and can hand one to the other.
- */
 import { writeHarnessSwitch } from './harness-switch.js';
 /** How long a cached answer is trusted. A person who just changed it expects the panel to notice. */
 const FRESH_MS = 30 * 1_000;
+const DAY_MS = 24 * 60 * 60 * 1_000;
+/**
+ * The answer as the HUD is pushed it: the grant's end date becomes whole days left, counted on the
+ * daemon's clock (the HUD has none worth trusting for this). No end date, no days. Pure.
+ */
+export function configForHud(config, now) {
+    if (config.credits === undefined)
+        return config;
+    const { endsAt, ...credits } = config.credits;
+    return {
+        ...config,
+        credits: endsAt === undefined
+            ? credits
+            : { ...credits, daysLeft: Math.max(0, Math.ceil((endsAt - now) / DAY_MS)) },
+    };
+}
 export function harnessConfigSource(load, now = () => Date.now()) {
     let cached;
     // `undefined` rather than 0: "never asked" is a different state from "asked at the epoch", and

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

@@ -61,6 +61,23 @@ export interface MemoryReadScope {
     projectId: string | null | undefined;
     subject?: string | undefined;
 }
+/**
+ * Who a memory read is for. An agent's read names the agent and the platform counts it as a
+ * consultation; the daemon's sync names its purpose and is never counted as one.
+ */
+export declare const MemoryReadHeader: {
+    readonly AGENT: "x-reticle-agent";
+    readonly PURPOSE: "x-reticle-read-purpose";
+};
+export declare const MemoryReadPurpose: {
+    readonly SYNC: "sync";
+};
+/**
+ * The headers of an agent's memory read: the key, and the agent whose call made the read. A replay's
+ * read went without the agent, and the platform credited it to "an agent that did not name itself".
+ * No agent is named when no single agent made the call: a guess would credit the wrong one.
+ */
+export declare function memoryReadHeaders(apiKey: string): Record<string, string>;
 /**
  * The URL for one memory read.
  *

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

@@ -37,6 +37,7 @@
  * constants live, and because both readers already reach this directory: a home under `recall/` would
  * make `flows` reach a directory it never needed.
  */
+import { callingClientName } from '../../hooks/coding-agents.js';
 /**
  * The path this module builds, spelled once, for the same reason as the names below.
  *
@@ -71,6 +72,27 @@ export const MemoryScopeField = {
  * a cast dressed up as a conversion.
  */
 const projectToName = (projectId) => 'string' === typeof projectId && projectId.length > 0 ? projectId : undefined;
+/**
+ * Who a memory read is for. An agent's read names the agent and the platform counts it as a
+ * consultation; the daemon's sync names its purpose and is never counted as one.
+ */
+export const MemoryReadHeader = {
+    AGENT: 'x-reticle-agent',
+    PURPOSE: 'x-reticle-read-purpose',
+};
+export const MemoryReadPurpose = { SYNC: 'sync' };
+/**
+ * The headers of an agent's memory read: the key, and the agent whose call made the read. A replay's
+ * read went without the agent, and the platform credited it to "an agent that did not name itself".
+ * No agent is named when no single agent made the call: a guess would credit the wrong one.
+ */
+export function memoryReadHeaders(apiKey) {
+    const agent = callingClientName();
+    return {
+        authorization: `Bearer ${apiKey}`,
+        ...(agent === undefined ? {} : { [MemoryReadHeader.AGENT]: agent }),
+    };
+}
 /**
  * The URL for one memory read.
  *

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

@@ -1,3 +1,4 @@
+import { type ScreenshotSyncState } from './sync-screenshots.js';
 /**
  * The derived records that ride along with runs, and the file each one lives in.
  *
@@ -34,18 +35,20 @@ export interface SyncSource {
         runId: string;
         payload: unknown;
     }>;
-    /** Every saved flow. Small, upserted by name, so they ride along whenever anything else does. */
+    /** Every saved flow. Upserted by name, so the set is sent only when it changed. */
     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
+     * Sent like flows, only when the set changed: 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;
+    /** One step screenshot of a run. Absent when this project keeps its screenshots local. */
+    screenshot?: (runId: string, file: string) => Uint8Array | undefined;
 }
 /** What the machine writes back. Separated from reads so a dry run is a source with no sink. */
 export interface SyncSink {
@@ -66,7 +69,7 @@ export interface PulledIssues {
     triage: Record<string, PulledIssue>;
 }
 /** `.reticle/cloud-state.json`. This machine's side of the conversation, never git-checked. */
-export interface CloudSyncState {
+export interface CloudSyncState extends ScreenshotSyncState {
     /** Opaque. Handed back to the server verbatim; the machine must never parse or invent one. */
     cursor?: string;
     lastPushAt?: number;
@@ -104,6 +107,21 @@ export interface CloudSyncState {
      */
     sentFlowsHash?: string;
     sentCapsulesHash?: string;
+    /**
+     * The hash of each derived record the platform last ACCEPTED from here. A platform that reports
+     * a hash of its own form of a record never matches ours, so the same record went every cycle.
+     */
+    sentDerivedHashes?: Record<string, string>;
+    /** The names of the flows the platform last took from here: one gone from disk is deleted there. */
+    sentFlowNames?: string[];
+    /**
+     * The link everything above was kept for: cloud, workspace and project (`credentialSlot`). A
+     * folder re-linked elsewhere starts a fresh record, so the new link gets the flows the old one
+     * already had, and none of the old link's runs.
+     */
+    link?: string;
+    /** When this folder was re-linked: runs made before it stay here unless the person moves them. */
+    linkedAt?: number;
     /**
      * A flow or capsule set the platform refused, kept so the refusal stays visible on the cycles that
      * do not resend it, and so the set is offered again once it changes or the platform reads more.
@@ -131,6 +149,8 @@ export interface SyncReport {
     ok: boolean;
     /** Runs the server accepted this cycle. */
     runsSent: number;
+    /** Step screenshots the server took this cycle, for runs it holds. */
+    screenshotsSent?: number;
     /** Runs it refused, with the reason, so a bad artifact is visible rather than silently stuck. */
     runsRejected: Array<{
         index: number;
@@ -189,6 +209,12 @@ interface SyncDeps {
         url: string;
         apiKey: string;
     };
+    /** The link this cycle sends for (`credentialSlot`); absent for an env-only key (CI). */
+    link?: string;
+    /** Send runs made under a previous link too: only ever because the person asked. */
+    moveHistory?: boolean;
+    /** The project flows are synced for. Absent when this cycle does not send flows: none is deleted. */
+    projectId?: string;
     source: SyncSource;
     sink: SyncSink;
     state: CloudSyncState;
@@ -210,7 +236,9 @@ export declare const MSG_RUNS_UNCONFIRMED = "sync 200 without a runs result: the
  * 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>;
+/** The command that moves a folder's earlier runs to the link it has now. */
+export declare const MOVE_HISTORY_COMMAND = "reticle sync --move-history";
+export declare function runSyncCycle(given: 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

@@ -30,12 +30,14 @@
  * 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 { FlowErrorCode, ReticleDir, SYNC_BATCH_LIMITS } from '@reticlehq/core';
+import { FlowErrorCode, ReticleDir, SYNC_BATCH_LIMITS, flowJsonReplacer } from '@reticlehq/core';
 import { hashPayload } from './sync-hash.js';
+import { syncScreenshots } from './sync-screenshots.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';
+const FLOWS_PATH = '/v1/flows';
 /**
  * The derived records that ride along with runs, and the file each one lives in.
  *
@@ -131,7 +133,29 @@ function batchRuns(runs) {
  * 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) {
+/** The command that moves a folder's earlier runs to the link it has now. */
+export const MOVE_HISTORY_COMMAND = 'reticle sync --move-history';
+/**
+ * The record this cycle keeps, for this link. Re-linked to another cloud, workspace or project, it
+ * starts afresh from now: what the old link was sent says nothing about the new one, and the runs
+ * made under the old link are that workspace's (a person's email can be in their steps), so they go
+ * only when the person moves them. A first link, or a record from before links were kept, is
+ * adopted as it is.
+ */
+function stateForLink(deps) {
+    const { state, link } = deps;
+    if (link === undefined)
+        return state;
+    if (state.link === undefined || state.link === link) {
+        const { linkedAt, ...rest } = state;
+        return true === deps.moveHistory || linkedAt === undefined
+            ? { ...rest, link }
+            : { ...rest, link, linkedAt };
+    }
+    return { link, ...(true === deps.moveHistory ? {} : { linkedAt: deps.now() }) };
+}
+export async function runSyncCycle(given) {
+    const deps = { ...given, state: stateForLink(given) };
     const empty = {
         ok: false,
         runsSent: 0,
@@ -237,7 +261,14 @@ export async function runSyncCycle(deps) {
             notRetried.push({ runId: run.runId, reason: prior.reason });
             return false;
         });
+        // Made before this folder was linked here: the previous link's, kept until the person moves it.
+        const linkedAt = deps.state.linkedAt;
+        const earlier = unsent.filter((run) => linkedAt !== undefined && !((numberAt(run.payload, 'createdAt') ?? 0) >= linkedAt));
+        if (0 < earlier.length)
+            heldBack.push(`${String(earlier.length)} run${1 === earlier.length ? '' : 's'} made before this folder was linked to this workspace stay${1 === earlier.length ? 's' : ''} on this machine (recorded under its previous link): run \`${MOVE_HISTORY_COMMAND}\` to send ${1 === earlier.length ? 'it' : 'them'} here`);
         const sendable = unsent.filter((run) => {
+            if (earlier.includes(run))
+                return false;
             const version = numberAt(run.payload, 'schemaVersion');
             if (runVersions === undefined || version === undefined || runVersions.includes(version))
                 return true;
@@ -248,25 +279,51 @@ export async function runSyncCycle(deps) {
         const derivedOffered = [];
         const unsupported = [];
         const bundle = {};
+        // A folder re-linked elsewhere keeps what it derived under the old link (its counts, defects,
+        // notes) here with the runs: those records add up the whole history and cannot be split by time.
+        // ponytail: held until `--move-history`; a per-link reset of the counters would let new ones go.
+        const derivedHeld = [];
         for (const { kind } of DERIVED_RECORDS) {
             const payload = deps.source.derived(kind);
             if (payload === undefined)
                 continue;
+            if (linkedAt !== undefined) {
+                derivedHeld.push(kind);
+                continue;
+            }
             if (!acceptedKinds.has(kind)) {
                 unsupported.push(kind);
                 continue;
             }
-            // The one comparison the whole protocol rests on. Same hash, do not send it.
-            if (hashPayload(payload) === hashes[kind])
+            // The one comparison the whole protocol rests on. Same hash, do not send it: the platform's,
+            // or the one it accepted from here while it still holds the record (a null means it does not).
+            const hash = hashPayload(payload);
+            if (hash === hashes[kind])
+                continue;
+            if ('string' === typeof hashes[kind] && hash === deps.state.sentDerivedHashes?.[kind])
                 continue;
             bundle[kind] = payload;
             derivedOffered.push(kind);
         }
         if (unsupported.length > 0)
             heldBack.push(`this platform does not accept ${unsupported.join(', ')} yet`);
+        if (0 < derivedHeld.length)
+            heldBack.push(`the ${derivedHeld.join(', ')} record${1 === derivedHeld.length ? '' : 's'} made under this folder's previous link stay${1 === derivedHeld.length ? 's' : ''} on this machine: run \`${MOVE_HISTORY_COMMAND}\` to send ${1 === derivedHeld.length ? 'it' : 'them'} here`);
         // Flows and capsules are upserted by name/id, so the whole set goes whenever it differs from the
-        // set the platform last answered for, and rides along with anything else being sent.
-        const flows = deps.source.flows().filter((flow, index) => {
+        // set the platform last answered for — and only then. Riding along with every run push re-sent
+        // ~1.3 MB per push on a real repo, and a POST that size timed out and failed the run with it.
+        // Made before this folder was linked here, like the runs: the previous link's, kept until moved.
+        // A flow carries the steps of whoever drove it, so it is that workspace's as much as a run is.
+        // One read for both halves: the disk source rebuilds every flow per read, so a second read's
+        // objects are never `includes` of the first's, and every held-back flow went out anyway.
+        const flowsAll = deps.source.flows();
+        const madeBefore = (flow) => linkedAt !== undefined && !((numberAt(flow, 'createdAt') ?? 0) >= linkedAt);
+        const flowsBefore = flowsAll.filter(madeBefore);
+        if (0 < flowsBefore.length)
+            heldBack.push(`${String(flowsBefore.length)} flow${1 === flowsBefore.length ? '' : 's'} made before this folder was linked to this workspace stay${1 === flowsBefore.length ? 's' : ''} on this machine: run \`${MOVE_HISTORY_COMMAND}\` to send ${1 === flowsBefore.length ? 'it' : 'them'} here`);
+        const flows = flowsAll.filter((flow, index) => {
+            if (madeBefore(flow))
+                return false;
             const version = numberAt(flow, 'version');
             if (flowVersions === undefined || version === undefined || flowVersions.includes(version))
                 return true;
@@ -296,10 +353,9 @@ export async function runSyncCycle(deps) {
         };
         const flowsChanged = due('flow', flowsHash, flows.length, deps.state.sentFlowsHash);
         const capsulesChanged = due('capsule', capsulesHash, capsulesAll.length, deps.state.sentCapsulesHash);
-        const ridesAlong = sendable.length > 0 || derivedOffered.length > 0 || flowsChanged || capsulesChanged;
-        if (ridesAlong && flows.length > 0)
+        if (flowsChanged)
             bundle['flows'] = flows;
-        const capsules = ridesAlong ? capsulesAll : [];
+        const capsules = capsulesChanged ? capsulesAll : [];
         if (capsules.length > 0)
             bundle['capsules'] = capsules;
         let runsSent = 0;
@@ -321,7 +377,11 @@ export async function runSyncCycle(deps) {
             const body = 0 === i ? { ...bundle } : {};
             if (batch.length > 0)
                 body['runs'] = batch.map((r) => r.payload);
-            const pushed = await call(SYNC_PATH, { method: 'POST', body: JSON.stringify(body) });
+            // The flows ride here too: a default flag stays out of them, as on disk.
+            const pushed = await call(SYNC_PATH, {
+                method: 'POST',
+                body: JSON.stringify(body, flowJsonReplacer),
+            });
             if (200 !== pushed.status) {
                 pushError = `sync ${String(pushed.status)}: ${pushed.text.slice(0, 200)}`;
                 break;
@@ -388,18 +448,40 @@ export async function runSyncCycle(deps) {
             const state = isRecord(answer['state']) ? answer['state'] : {};
             for (const kind of derivedOffered) {
                 const verdict = state[kind];
-                if ('accepted' === verdict)
+                if ('accepted' === verdict) {
                     derivedSent.push(kind);
+                    nextState.sentDerivedHashes = {
+                        ...nextState.sentDerivedHashes,
+                        [kind]: hashPayload(bundle[kind]),
+                    };
+                }
                 else if ('string' === typeof verdict)
                     refused.push({ part: kind, reason: `${kind}: ${verdict}` });
             }
         }
+        // A flow the platform took from here and that is gone from disk is deleted there by name: it
+        // does not infer a deletion from a missing name, since another clone may still hold the flow.
+        const onDisk = new Set(deps.source.flows().map(flowName));
+        const kept = [];
+        for (const name of deps.projectId === undefined ? [] : (deps.state.sentFlowNames ?? [])) {
+            if (onDisk.has(name)) {
+                kept.push(name);
+                continue;
+            }
+            const gone = await call(`${FLOWS_PATH}/${encodeURIComponent(name)}?projectId=${encodeURIComponent(deps.projectId ?? '')}`, { method: 'DELETE' });
+            if (2 !== Math.floor(gone.status / 100) && 404 !== gone.status)
+                kept.push(name);
+        }
+        if (deps.projectId !== undefined)
+            nextState.sentFlowNames = kept;
         if (requests > 0 && pushError === undefined) {
             nextState.lastPushAt = deps.now();
             // The platform answered for these sets, refusals included (reported above, and not re-offered
             // until the set changes — the same rule as a refused run).
-            if (ridesAlong && flows.length > 0)
+            if (flowsChanged)
                 nextState.sentFlowsHash = flowsHash;
+            if (flowsChanged && deps.projectId !== undefined)
+                nextState.sentFlowNames = [...new Set([...kept, ...flows.map(flowName)])];
             if (capsules.length > 0)
                 nextState.sentCapsulesHash = capsulesHash;
         }
@@ -429,6 +511,22 @@ export async function runSyncCycle(deps) {
          */
         nextState.sentRunIds = allRuns.map((r) => r.runId).filter((id) => known.has(id));
         nextState.sentRunHashes = heldHashes(allRuns, recorded);
+        // 2b. The step screenshots of every run the platform now holds, once each.
+        let screenshotsSent = 0;
+        const readImage = deps.source.screenshot;
+        if (readImage !== undefined) {
+            const shots = await syncScreenshots({
+                runs: allRuns,
+                accepted: (runId) => known.has(runId),
+                readImage,
+                state: deps.state,
+                post: (path, body) => call(path, { method: 'POST', body }),
+            });
+            screenshotsSent = shots.sent;
+            Object.assign(nextState, shots.state);
+            if (shots.error !== undefined)
+                heldBack.push(shots.error);
+        }
         // 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}`);
@@ -477,6 +575,7 @@ export async function runSyncCycle(deps) {
                 0 === setsNotRetried.length &&
                 !heldArtifacts,
             runsSent,
+            ...(0 === screenshotsSent ? {} : { screenshotsSent }),
             runsRejected,
             flowsSent,
             capsulesSent,
@@ -550,6 +649,8 @@ export function describeSync(report) {
         sent.push(`${String(report.flowsSent)} flow(s)`);
     if (report.capsulesSent > 0)
         sent.push(`${String(report.capsulesSent)} capsule(s)`);
+    if ((report.screenshotsSent ?? 0) > 0)
+        sent.push(`${String(report.screenshotsSent)} screenshot(s)`);
     if (report.derivedSent.length > 0)
         sent.push(report.derivedSent.join(', '));
     /*

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

@@ -1,5 +1,6 @@
 import { type SyncReport } from './sync-cycle.js';
 import { type ProjectCloud } from './cloud-config.js';
+import { type UnsyncedRoot } from './unsynced-roots.js';
 import type { FileSystemPort } from '../project/fs/fs-port.js';
 interface SyncDaemonDeps {
     reticleRoot: string;
@@ -20,6 +21,11 @@ interface SyncDaemonDeps {
     cloudFor?: (root: string) => Promise<ProjectCloud>;
     now?: () => number;
     intervalMs?: number;
+    /**
+     * Call `onChange` when this root's link file changes; returns how to stop. A re-link was read only
+     * on the next idle tick, so a daemon kept syncing to the old link for up to a minute.
+     */
+    watchLink?: (onChange: () => void) => () => void;
     /** Injected for the test; the real one is `fetch`. */
     request?: (url: string, init: {
         method: string;
@@ -58,6 +64,11 @@ export interface SyncDaemon {
      * time — the artifact is still on disk and the next daemon for this project sends it.
      */
     flush: () => Promise<void>;
+    /**
+     * Every root this daemon knows with runs the platform does not have, as of the last cycle — linked
+     * or not. An unlinked one is the case nothing will ever send, and it used to be skipped silently.
+     */
+    unsyncedRoots: () => readonly UnsyncedRoot[];
 }
 /**
  * Start the loop. Safe to call for an UNLINKED project: it resolves the link on every tick and does