@reticlehq/server 3.7.0 → 3.8.1

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

@@ -10,7 +10,8 @@
  * 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 { DEFAULT_PLATFORM_URL, ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { DEFAULT_PLATFORM_URL, ReticleDir, ReticleEnv, mainCheckoutTwin } from '@reticlehq/core';
+import { readTextOrUndefined } from '../project/fs/fs-port.js';
 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. */
@@ -23,6 +24,7 @@ const DEFAULT_SYNC_POLICY = {
     flows: true,
     capsules: true,
     screenshots: true,
+    video: true,
 };
 /** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
 export const VerifyMode = { LOCAL: 'local', SERVER: 'server' };
@@ -30,8 +32,9 @@ 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)))
+        if (!(await fs.exists(path))) {
             return null;
+        }
         return JSON.parse(await fs.readFile(path));
     }
     catch {
@@ -40,13 +43,16 @@ async function readJson(fs, path) {
 }
 /** Validate the shape of `.reticle/cloud.json`. Requires projectId + url; policy/verify default in. */
 function parseLink(raw) {
-    if (typeof raw !== 'object' || null === raw)
+    if (typeof raw !== 'object' || null === raw) {
         return null;
+    }
     const o = raw;
-    if (typeof o.projectId !== 'string' || 0 === o.projectId.length)
+    if (typeof o.projectId !== 'string' || 0 === o.projectId.length) {
         return null;
-    if (typeof o.url !== 'string' || 0 === o.url.length)
+    }
+    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,
@@ -58,6 +64,8 @@ function parseLink(raw) {
             flows: asBool(sync.flows, DEFAULT_SYNC_POLICY.flows),
             capsules: asBool(sync.capsules, DEFAULT_SYNC_POLICY.capsules),
             screenshots: asBool(sync.screenshots, asBool(sync.runs, DEFAULT_SYNC_POLICY.screenshots)),
+            video: asBool(sync.video, asBool(sync.screenshots, asBool(sync.runs, DEFAULT_SYNC_POLICY.video))),
+            ...(true === sync.episodes ? { episodes: true } : {}),
         },
         verify: o.verify === VerifyMode.SERVER ? VerifyMode.SERVER : VerifyMode.LOCAL,
     };
@@ -85,8 +93,9 @@ export const credentialSlot = (url, projectId, orgId) => orgId === undefined ||
     ? `${normalizeCloudUrl(url)}::${projectId}`
     : `${normalizeCloudUrl(url)}::org::${orgId}::${projectId}`;
 function credentialFor(raw, projectId, url, orgId) {
-    if (typeof raw !== 'object' || null === raw)
+    if (typeof raw !== 'object' || null === raw) {
         return null;
+    }
     const store = raw;
     /*
      * The ORG slot first, because cloud + project is still not an identity.
@@ -98,41 +107,56 @@ function credentialFor(raw, projectId, url, orgId) {
      * two tenants colliding.
      */
     const orgScoped = orgId === undefined ? undefined : store[credentialSlot(url, projectId, orgId)];
-    if ('string' === typeof orgScoped && orgScoped.length > 0)
+    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)
+    if ('string' === typeof composite && composite.length > 0) {
         return composite;
+    }
     const entry = store[projectId];
-    if ('string' === typeof entry)
+    if ('string' === typeof entry) {
         return entry.length > 0 ? entry : null;
-    if (typeof entry !== 'object' || null === entry)
+    }
+    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)
+    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))
+    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(/\/+$/, '');
+/**
+ * A linked worktree's link, read from its main checkout. `.reticle/` is often git-ignored, so a new
+ * worktree has no `cloud.json`, and `reticle connect` once in the main checkout must cover it.
+ */
+async function linkOfMainCheckout(fs, reticleRoot) {
+    const twin = mainCheckoutTwin(reticleRoot, readTextOrUndefined);
+    return twin === undefined ? null : parseLink(await readJson(fs, join(twin, CLOUD_LINK_FILE)));
+}
 /**
  * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
  * user credential store, else the env key; if the project isn't linked (no cloud.json), the env creds
  * are the whole story (the single-project / CI flow). `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)));
+    const link = parseLink(await readJson(fs, join(reticleRoot, CLOUD_LINK_FILE))) ??
+        (await linkOfMainCheckout(fs, reticleRoot));
     if (null === link) {
         // No per-project link → the env vars are the whole story (legacy single-project / CI behaviour).
         const config = resolveCloudConfig(env);
@@ -152,6 +176,8 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
         flows: link.sync.flows ?? DEFAULT_SYNC_POLICY.flows,
         capsules: link.sync.capsules ?? DEFAULT_SYNC_POLICY.capsules,
         screenshots: link.sync.screenshots ?? DEFAULT_SYNC_POLICY.screenshots,
+        video: link.sync.video ?? DEFAULT_SYNC_POLICY.video,
+        ...(true === link.sync.episodes ? { episodes: true } : {}),
     };
     const stored = credentialFor(await readJson(fs, join(homeDir, ReticleDir.ROOT, CREDENTIALS_FILE)), link.projectId, link.url, link.orgId);
     /*

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

@@ -42,6 +42,7 @@ export declare function syncRequest(url: string, init: {
 }, timeoutMs?: number): Promise<{
     status: number;
     text: string;
+    etag?: string;
 }>;
 export declare const SyncOutcome: {
     readonly SYNCED: "synced";
@@ -117,31 +118,9 @@ declare const ServerVerificationSchema: z.ZodObject<{
     flows: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         status: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        status: string;
-        name: string;
-    }, {
-        status: string;
-        name: string;
-    }>, "many">;
+    }, z.core.$strip>>;
     summary: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    flows: {
-        status: string;
-        name: string;
-    }[];
-    verificationId: string;
-    verdict: string | null;
-    summary: string;
-}, {
-    flows: {
-        status: string;
-        name: string;
-    }[];
-    verificationId: string;
-    verdict: string | null;
-    summary: string;
-}>;
+}, z.core.$strip>;
 export type ServerVerification = z.infer<typeof ServerVerificationSchema>;
 /**
  * Delegate a verification to the hosted runner: submit the preview URL + flow names to `POST

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

@@ -105,7 +105,9 @@ export async function cloudFetch(url, init, timeoutMs = CLOUD_FETCH_TIMEOUT_MS)
  */
 export async function syncRequest(url, init, timeoutMs = CLOUD_FETCH_TIMEOUT_MS) {
     const res = await cloudFetch(url, init, timeoutMs);
-    return { status: res.status, text: await res.text() };
+    // The tag a conditional read names next time (the idle memory poll); absent when none was sent.
+    const etag = res.headers.get('etag');
+    return { status: res.status, text: await res.text(), ...(null === etag ? {} : { etag }) };
 }
 export const SyncOutcome = {
     SYNCED: 'synced',
@@ -153,7 +155,8 @@ export async function syncRunToCloud(run, config, fetchImpl) {
                 'content-type': 'application/json',
                 authorization: `Bearer ${config.apiKey}`,
             },
-            // The prompt context leaves the machine only when the project opted in.
+            // The prompt context leaves with the run when it was captured shared: on by default for a
+            // linked project, off with `"shareRequests": false`.
             body: JSON.stringify(shareableRun(run)),
         });
         return res.ok

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

@@ -32,13 +32,6 @@ export interface HarnessConfigView {
         kind?: CreditKind | undefined;
         endsAt?: number;
     };
-    /** The platform's coverage gate, when it sent one: the HUD prefers it to the local score. */
-    gate?: {
-        unlocked: boolean;
-        percent?: number;
-        reason?: string;
-        prompt?: string;
-    };
     plan?: {
         kind: CreditKind;
         daysLeft?: number;

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

@@ -48,7 +48,12 @@
 export declare const MemoryScopeField: {
     readonly PROJECT_ID: "projectId";
     readonly SUBJECT: "subject";
+    readonly LIMIT: "limit";
+    readonly CURSOR: "cursor";
+    readonly NEXT_CURSOR: "nextCursor";
 };
+/** One page of a memory read: the platform's own maximum. */
+export declare const MEMORY_PAGE_LIMIT = 100;
 /**
  * What a read is asked about: the linked project, and optionally one subject within it.
  *
@@ -60,6 +65,10 @@ export interface MemoryReadScope {
     /** The cloud project the link file names. Absent, `null` and empty all mean "no project to name". */
     projectId: string | null | undefined;
     subject?: string | undefined;
+    /** One page's size; absent asks for everything, which a server that does not page also answers. */
+    limit?: number | undefined;
+    /** The `nextCursor` of the page before this one. */
+    cursor?: string | undefined;
 }
 /**
  * Who a memory read is for. An agent's read names the agent and the platform counts it as a
@@ -159,3 +168,13 @@ export declare function scopedMemoryEntries(body: unknown, projectId: string | n
  * The caller therefore checks for `undefined` and refuses out loud, instead of asking twice.
  */
 export declare function scopeMemoryResponse(body: unknown, projectId: string | null | undefined): unknown;
+/**
+ * Every page of a memory read, as one envelope: the first page's, with every page's entries.
+ *
+ * The platform pages `GET /v1/memory` when asked, so every reader asks a page at a time and follows
+ * `nextCursor`; a server that does not page answers once with everything and no cursor. A page whose
+ * envelope is not this project's is handed back as it arrived, so the reader's scope check refuses
+ * the whole read rather than mixing it in. `fetchBody` answers `undefined` for a failed request, and
+ * so does this.
+ */
+export declare function readMemoryPages(baseUrl: string, scope: Omit<MemoryReadScope, 'limit' | 'cursor'>, fetchBody: (url: string) => Promise<unknown>): Promise<unknown>;

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

@@ -57,7 +57,14 @@ const CLOUD_MEMORY_PATH = '/v1/memory';
 export const MemoryScopeField = {
     PROJECT_ID: 'projectId',
     SUBJECT: 'subject',
+    LIMIT: 'limit',
+    CURSOR: 'cursor',
+    NEXT_CURSOR: 'nextCursor',
 };
+/** One page of a memory read: the platform's own maximum. */
+export const MEMORY_PAGE_LIMIT = 100;
+/** ponytail: 100 pages = 10,000 entries per read; a project past that needs a subject-scoped read. */
+const MAX_MEMORY_PAGES = 100;
 /**
  * The project id to name, or `undefined` when there is none.
  *
@@ -109,6 +116,11 @@ export function memoryReadUrl(baseUrl, scope) {
     if (projectId !== undefined) {
         parts.push(`${MemoryScopeField.PROJECT_ID}=${encodeURIComponent(projectId)}`);
     }
+    if (scope.limit !== undefined)
+        parts.push(`${MemoryScopeField.LIMIT}=${String(scope.limit)}`);
+    if (scope.cursor !== undefined) {
+        parts.push(`${MemoryScopeField.CURSOR}=${encodeURIComponent(scope.cursor)}`);
+    }
     const url = `${baseUrl}${CLOUD_MEMORY_PATH}`;
     return 0 === parts.length ? url : `${url}?${parts.join('&')}`;
 }
@@ -225,3 +237,39 @@ export function scopeMemoryResponse(body, projectId) {
         return body;
     return { ...envelope, entries: keepOwnProject(entries, projectId) };
 }
+/**
+ * Every page of a memory read, as one envelope: the first page's, with every page's entries.
+ *
+ * The platform pages `GET /v1/memory` when asked, so every reader asks a page at a time and follows
+ * `nextCursor`; a server that does not page answers once with everything and no cursor. A page whose
+ * envelope is not this project's is handed back as it arrived, so the reader's scope check refuses
+ * the whole read rather than mixing it in. `fetchBody` answers `undefined` for a failed request, and
+ * so does this.
+ */
+export async function readMemoryPages(baseUrl, scope, fetchBody) {
+    let first;
+    const entries = [];
+    let cursor;
+    let more = false;
+    for (let page = 0; page < MAX_MEMORY_PAGES; page += 1) {
+        const body = await fetchBody(memoryReadUrl(baseUrl, { ...scope, limit: MEMORY_PAGE_LIMIT, cursor }));
+        if (null === body || 'object' !== typeof body)
+            return body;
+        if (!isReadableMemoryScope(scopeOfMemoryResponse(body, scope.projectId)))
+            return body;
+        const envelope = body;
+        first ??= envelope;
+        const pageEntries = envelope['entries'];
+        if (!Array.isArray(pageEntries))
+            return 0 === page ? body : { ...first, entries };
+        entries.push(...pageEntries);
+        const next = envelope[MemoryScopeField.NEXT_CURSOR];
+        more = 'string' === typeof next && 0 < next.length;
+        if (!more)
+            break;
+        cursor = next;
+    }
+    const { [MemoryScopeField.NEXT_CURSOR]: _paged, ...rest } = first ?? {};
+    // Said, never silent: a reader past the page ceiling holds less than the project knows.
+    return { ...rest, entries, ...(more ? { truncated: true } : {}) };
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Reading what the dashboard answers. Every field is read defensively: an older platform, a proxy
+ * or a half-written body must degrade to "nothing confirmed", never to a throw inside the cycle.
+ * Kept apart from the cycle (`sync-cycle.ts`), which is the protocol; this is only how its replies
+ * are parsed.
+ */
+export interface StatusResponse {
+    knownRunIds?: string[];
+    truncated?: boolean;
+    stateHashes?: Record<string, string | null>;
+    /** What this platform reads. Absent on a platform that predates the handshake. */
+    accepts?: unknown;
+}
+export interface PullResponse {
+    triage?: Array<{
+        fingerprint: string;
+        status: string;
+        flowName?: string | null;
+        title?: string;
+        at: number;
+    }>;
+    cursor?: string;
+    more?: boolean;
+}
+export declare const asJson: (text: string) => unknown;
+export declare const isRecord: (v: unknown) => v is Record<string, unknown>;
+/** A list of numbers, or undefined when the server did not send a list at all. */
+export declare const numbersIn: (v: unknown) => number[] | undefined;
+/** A numeric field of an artifact, or undefined when it has none. */
+export declare const numberAt: (v: unknown, field: string) => number | undefined;
+/** The name a person knows a flow by, falling back to its position. */
+export declare const flowName: (flow: unknown, index: number) => string;
+/** The server's per-part answer: accepted count and rejection list, each read defensively. */
+export declare function partResult(body: Record<string, unknown>, part: string): {
+    accepted: number;
+    rejected: {
+        index: number;
+        reason: string;
+        code: unknown;
+        version: unknown;
+        current: unknown;
+    }[];
+};

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

@@ -0,0 +1,42 @@
+/**
+ * Reading what the dashboard answers. Every field is read defensively: an older platform, a proxy
+ * or a half-written body must degrade to "nothing confirmed", never to a throw inside the cycle.
+ * Kept apart from the cycle (`sync-cycle.ts`), which is the protocol; this is only how its replies
+ * are parsed.
+ */
+export const asJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+export const isRecord = (v) => 'object' === typeof v && null !== v;
+/** A list of numbers, or undefined when the server did not send a list at all. */
+export const numbersIn = (v) => Array.isArray(v) ? v.filter((n) => 'number' === typeof n) : undefined;
+/** A numeric field of an artifact, or undefined when it has none. */
+export const numberAt = (v, field) => {
+    const n = isRecord(v) ? v[field] : undefined;
+    return 'number' === typeof n ? n : undefined;
+};
+/** The name a person knows a flow by, falling back to its position. */
+export const flowName = (flow, index) => {
+    const name = isRecord(flow) ? flow['name'] : undefined;
+    return 'string' === typeof name && name.length > 0 ? name : `flow #${String(index)}`;
+};
+/** The server's per-part answer: accepted count and rejection list, each read defensively. */
+export function partResult(body, part) {
+    const raw = isRecord(body[part]) ? body[part] : {};
+    const accepted = 'number' === typeof raw['accepted'] ? raw['accepted'] : 0;
+    const rejected = (Array.isArray(raw['rejected']) ? raw['rejected'] : [])
+        .filter(isRecord)
+        .map((r) => ({
+        index: 'number' === typeof r['index'] ? r['index'] : -1,
+        reason: 'string' === typeof r['reason'] ? r['reason'] : 'no reason given',
+        code: r['code'],
+        version: r['version'],
+        current: r['current'],
+    }));
+    return { accepted, rejected };
+}

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

@@ -1,4 +1,5 @@
 import { type ScreenshotSyncState } from './sync-screenshots.js';
+export { FLOW_CONFLICT_CODE } from './sync-flow-versions.js';
 /**
  * The derived records that ride along with runs, and the file each one lives in.
  *
@@ -56,6 +57,11 @@ export interface SyncSink {
     writeIssues: (issues: PulledIssues) => void;
     /** Persist the cursor and the bookkeeping. */
     writeState: (state: CloudSyncState) => void;
+    /**
+     * Keep this machine's edit of a flow as a named copy beside it and write the platform's version in
+     * its place; answers the copy's name. Absent (a dry run): the conflict is reported as a refusal.
+     */
+    resolveFlowConflict?: (name: string, theirs: unknown) => string | undefined;
 }
 /** A decision a human made on the dashboard, as the machine stores it. */
 interface PulledIssue {
@@ -106,6 +112,17 @@ export interface CloudSyncState extends ScreenshotSyncState {
      * a changed set is sent on its own, and an unchanged one is not sent again.
      */
     sentFlowsHash?: string;
+    /**
+     * The hash of each flow, by name, as the platform last took it from here. A flow goes when IT
+     * changed: re-sending the whole set on every save sent each of a repo's flows once per save, and
+     * the platform stamped every one of them as updated. `sentFlowsHash` is read only to adopt a
+     * record from before this existed, so an upgrade does not re-send an unchanged set.
+     */
+    sentFlowHashes?: Record<string, string>;
+    /** The platform's version of each flow as last taken or adopted here: what a push is based on. */
+    flowVersions?: Record<string, string>;
+    /** Conflict copies still on disk: this machine's edits kept beside the platform's version. */
+    flowConflicts?: string[];
     sentCapsulesHash?: string;
     /**
      * The hash of each derived record the platform last ACCEPTED from here. A platform that reports
@@ -129,16 +146,29 @@ export interface CloudSyncState extends ScreenshotSyncState {
     refusedSets?: Partial<Record<SetPart, RefusedSet>>;
 }
 type SetPart = 'flow' | 'capsule';
-interface RefusedSet {
+interface RefusedSet extends RefusalStamp {
     hash: string;
-    acceptsHash: string;
     count: number;
     reason: string;
 }
-interface RefusedRun {
+/**
+ * What could change a refusal's answer besides the item itself. A refusal used to stand until the
+ * item changed or the platform's `accepts` did, so a refused flow set stayed refused after the
+ * platform relaxed its rule, until somebody deleted the entry by hand. The platform sends no version
+ * of its own, so the CLI's version stands in for "the conversation changed", and age bounds the rest.
+ */
+interface RefusalStamp {
+    acceptsHash: string;
+    /** The CLI version that heard the refusal. Absent on a refusal recorded before this existed. */
+    version?: string;
+    /** When it was heard. Absent on a refusal recorded before this existed. */
+    at?: number;
+}
+/** A refusal older than this is offered again, whatever else is unchanged. */
+export declare const REFUSAL_RETRY_AFTER_MS: number;
+interface RefusedRun extends RefusalStamp {
     reason: string;
     payloadHash: string;
-    acceptsHash: string;
 }
 export interface SyncReport {
     /**
@@ -157,6 +187,8 @@ export interface SyncReport {
         reason: string;
     }>;
     flowsSent: number;
+    /** Open conflict copies: edits of a flow another machine saved over first, kept beside it. */
+    flowConflicts?: string[];
     /** Capsules the server accepted. Zero when it reported none, which includes not knowing the field. */
     capsulesSent: number;
     /** Derived records the server ACCEPTED this cycle. Empty on a quiet cycle, the normal case. */
@@ -219,6 +251,8 @@ interface SyncDeps {
     sink: SyncSink;
     state: CloudSyncState;
     now: () => number;
+    /** This CLI's version, stamped on each refusal: a new one asks the platform again. */
+    clientVersion?: string;
     /** Injected so a cycle can be driven against a scripted server with no network. */
     request: (url: string, init: {
         method: string;
@@ -229,16 +263,12 @@ interface SyncDeps {
         text: string;
     }>;
 }
-/** The server's per-part answer: accepted count and rejection list, each read defensively. */
 /** A 200 that never confirmed the runs it was sent. Kept queued, and said, rather than dropped. */
 export declare const MSG_RUNS_UNCONFIRMED = "sync 200 without a runs result: the server did not confirm the runs it was sent, so they stay queued";
+/** 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";
 /**
  * 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.
  */
-/** 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 {};