@reticlehq/server 2.0.0

package/dist/pool/playwright-launcher.js

@@ -0,0 +1,51 @@
+/**
+ * The real Playwright adapter behind BrowserPool: wraps `chromium.launch` into the pool's small
+ * PooledBrowser/Context/Page interfaces. Kept thin and separate so the pool's lifecycle logic stays
+ * unit-tested with a fake while this glue is exercised only by the e2e battery (it needs Chromium).
+ *
+ * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
+ */
+import { chromium } from 'playwright';
+function wrapBrowser(browser) {
+    return {
+        isConnected: () => browser.isConnected(),
+        newContext: async () => {
+            const context = await browser.newContext();
+            return {
+                newPage: async () => {
+                    const page = await context.newPage();
+                    return {
+                        goto: (url, opts) => page.goto(url, opts?.timeoutMs === undefined ? undefined : { timeout: opts.timeoutMs }),
+                        close: () => page.close(),
+                        onCrash: (handler) => page.on('crash', handler),
+                    };
+                },
+                close: () => context.close(),
+            };
+        },
+        close: () => browser.close(),
+        onDisconnected: (handler) => browser.on('disconnected', handler),
+    };
+}
+/** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
+export function playwrightLauncher(opts = {}) {
+    const headless = opts.headless ?? true;
+    return async () => wrapBrowser(await chromium.launch({ headless }));
+}
+const MAX_CONTEXTS_CEILING = 8;
+const MAX_CONTEXTS_FLOOR = 1;
+/**
+ * Resolve the pool's concurrency cap. An explicit RETICLE_MAX_CONTEXTS wins (clamped to >=1); otherwise
+ * scale with the machine but never above a sane ceiling so a big box can't fan out into a fork bomb.
+ * Pure (env value + cpu count passed in) so it's testable.
+ */
+export function resolveMaxContexts(envValue, cpuCount) {
+    if (envValue !== undefined) {
+        const parsed = parseInt(envValue, 10);
+        if (!isNaN(parsed) && parsed >= MAX_CONTEXTS_FLOOR)
+            return parsed;
+    }
+    const byCpu = Math.max(MAX_CONTEXTS_FLOOR, cpuCount - 1);
+    return Math.min(MAX_CONTEXTS_CEILING, byCpu);
+}
+//# sourceMappingURL=playwright-launcher.js.map

package/dist/pool/playwright-launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-launcher.js","sourceRoot":"","sources":["../../src/pool/playwright-launcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAgB,MAAM,YAAY,CAAC;AAGpD,SAAS,WAAW,CAAC,OAAgB;IACnC,OAAO;QACL,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE;QACxC,UAAU,EAAE,KAAK,IAA4B,EAAE;YAC7C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;YAC3C,OAAO;gBACL,OAAO,EAAE,KAAK,IAAyB,EAAE;oBACvC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;oBACrC,OAAO;wBACL,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAClB,IAAI,CAAC,IAAI,CACP,GAAG,EACH,IAAI,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,CACxE;wBACH,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE;wBACzB,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC;qBAChD,CAAC;gBACJ,CAAC;gBACD,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;aAC7B,CAAC;QACJ,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;QAC5B,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,cAAc,EAAE,OAAO,CAAC;KACjE,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,kBAAkB,CAAC,OAA+B,EAAE;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;IACvC,OAAO,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAC/B,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAA4B,EAAE,QAAgB;IAC/E,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,kBAAkB;YAAE,OAAO,MAAM,CAAC;IACpE,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC;IACzD,OAAO,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/dist/project/baselines.d.ts

@@ -0,0 +1,22 @@
+export interface Baseline {
+    name: string;
+    lines: string[];
+    route: string;
+}
+interface DiffResult {
+    removed: string[];
+    added: string[];
+}
+/** Strip volatile ref ids so snapshots compare by semantics, not by ref number. */
+export declare function normalizeLines(tree: string): string[];
+/** Multiset diff: what's in baseline-but-not-current (removed) and current-but-not-baseline (added). */
+export declare function diffLines(baseline: string[], current: string[]): DiffResult;
+/** In-memory baseline store (per server run). */
+export declare class BaselineStore {
+    #private;
+    save(baseline: Baseline): void;
+    get(name: string): Baseline | undefined;
+    list(): string[];
+}
+export {};
+//# sourceMappingURL=baselines.d.ts.map

package/dist/project/baselines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baselines.d.ts","sourceRoot":"","sources":["../../src/project/baselines.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKrD;AAQD,wGAAwG;AACxG,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,UAAU,CAc3E;AAED,iDAAiD;AACjD,qBAAa,aAAa;;IAGxB,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAI9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAIvC,IAAI,IAAI,MAAM,EAAE;CAGjB"}

package/dist/project/baselines.js

@@ -0,0 +1,45 @@
+/** Strip volatile ref ids so snapshots compare by semantics, not by ref number. */
+export function normalizeLines(tree) {
+    return tree
+        .split('\n')
+        .map((line) => line.replace(/\s*\(ref=e\d+\)/, '').trim())
+        .filter((line) => line.length > 0);
+}
+function frequency(lines) {
+    const map = new Map();
+    for (const line of lines)
+        map.set(line, (map.get(line) ?? 0) + 1);
+    return map;
+}
+/** Multiset diff: what's in baseline-but-not-current (removed) and current-but-not-baseline (added). */
+export function diffLines(baseline, current) {
+    const b = frequency(baseline);
+    const c = frequency(current);
+    const removed = [];
+    const added = [];
+    for (const [line, n] of b) {
+        const have = c.get(line) ?? 0;
+        for (let i = 0; i < n - have; i += 1)
+            removed.push(line);
+    }
+    for (const [line, n] of c) {
+        const had = b.get(line) ?? 0;
+        for (let i = 0; i < n - had; i += 1)
+            added.push(line);
+    }
+    return { removed, added };
+}
+/** In-memory baseline store (per server run). */
+export class BaselineStore {
+    #map = new Map();
+    save(baseline) {
+        this.#map.set(baseline.name, baseline);
+    }
+    get(name) {
+        return this.#map.get(name);
+    }
+    list() {
+        return [...this.#map.keys()];
+    }
+}
+//# sourceMappingURL=baselines.js.map

package/dist/project/baselines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baselines.js","sourceRoot":"","sources":["../../src/project/baselines.ts"],"names":[],"mappings":"AAWA,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;SACzD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,SAAS,CAAC,KAAe;IAChC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,SAAS,CAAC,QAAkB,EAAE,OAAiB;IAC7D,MAAM,CAAC,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,iDAAiD;AACjD,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE5C,IAAI,CAAC,QAAkB;QACrB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/project/fs-port.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The injectable filesystem seam. Server logic depends on this interface, never on node:fs
+ * directly — so tests pass an in-memory or temp-dir adapter and never touch the repo's .reticle/.
+ */
+export interface FileSystemPort {
+    /** Read a UTF-8 file. Rejects (ENOENT) if absent. */
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string): Promise<void>;
+    /** Read raw bytes (PNG baselines). Rejects (ENOENT) if absent. */
+    readFileBytes(path: string): Promise<Uint8Array>;
+    /** Write raw bytes (PNG screenshots/diffs). */
+    writeFileBytes(path: string, data: Uint8Array): Promise<void>;
+    /** Recursive + idempotent: no throw if the directory already exists. */
+    mkdir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    /** List entries of a directory (for flows/baselines listing). */
+    readdir(path: string): Promise<string[]>;
+    /** Atomically replace `to` with `from` (same-FS rename) — for crash-safe writes. */
+    rename(from: string, to: string): Promise<void>;
+    /** Idempotent remove (no throw if absent) — for retention pruning + cleaning temp files. */
+    rm(path: string): Promise<void>;
+    /** ENOENT classifier — narrows unknown without `any`, so callers can distinguish missing-file. */
+    isNotFound(error: unknown): boolean;
+}
+/** Production adapter — the single import site of node:fs/promises in the server. */
+export declare function createNodeFileSystem(): FileSystemPort;
+//# sourceMappingURL=fs-port.d.ts.map

package/dist/project/fs-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-port.d.ts","sourceRoot":"","sources":["../../src/project/fs-port.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,kEAAkE;IAClE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjD,+CAA+C;IAC/C,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,wEAAwE;IACxE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,iEAAiE;IACjE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,oFAAoF;IACpF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,4FAA4F;IAC5F,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,kGAAkG;IAClG,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CACrC;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,IAAI,cAAc,CA2BrD"}

package/dist/project/fs-port.js

@@ -0,0 +1,32 @@
+import { access, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+/** Production adapter — the single import site of node:fs/promises in the server. */
+export function createNodeFileSystem() {
+    return {
+        readFile: (path) => readFile(path, 'utf8'),
+        writeFile: (path, data) => writeFile(path, data, 'utf8'),
+        readFileBytes: async (path) => {
+            const buf = await readFile(path);
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        },
+        writeFileBytes: (path, data) => writeFile(path, data),
+        mkdir: async (path) => {
+            await mkdir(path, { recursive: true });
+        },
+        exists: async (path) => {
+            try {
+                await access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        readdir: (path) => readdir(path),
+        rename: (from, to) => rename(from, to),
+        rm: async (path) => {
+            await rm(path, { force: true });
+        },
+        isNotFound: (error) => error?.code === 'ENOENT',
+    };
+}
+//# sourceMappingURL=fs-port.js.map

package/dist/project/fs-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-port.js","sourceRoot":"","sources":["../../src/project/fs-port.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AA2B3F,qFAAqF;AACrF,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAC1C,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC;QACxD,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;QACpE,CAAC;QACD,cAAc,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC;QACrD,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACpB,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACrB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;gBACnB,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;QAChC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACtC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACjB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAA2C,EAAE,IAAI,KAAK,QAAQ;KACvF,CAAC;AACJ,CAAC"}

package/dist/project/project-store.d.ts

@@ -0,0 +1,32 @@
+import { ProjectReadError, type ProjectFile, type RunRecord } from '@reticlehq/core';
+import type { FileSystemPort } from './fs-port.js';
+import type { Clock } from '../flows/flows.js';
+/** Never-throws read result (mirrors ReadContractResult). */
+export type ReadProjectResult = {
+    ok: true;
+    file: ProjectFile;
+} | {
+    ok: false;
+    reason: ProjectReadError;
+};
+/**
+ * Cross-run outcome memory persisted at .reticle/project.json. Models FlowStore:
+ * injected FileSystemPort + Clock, byte-stable serialize, never-throws read. The clock is the
+ * single `at`-stamp site so handlers pass an un-stamped record and no Date.now leaks into logic.
+ */
+export declare class ProjectStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string, clock: Clock);
+    /** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. Mirrors readContract. */
+    read(): Promise<ReadProjectResult>;
+    /**
+     * Append a run, stamping `at` from the injected clock (the one clock site). A MISSING **or
+     * MALFORMED** existing file self-heals to a fresh empty file so corrupt history never blocks
+     * recording — unlike the read path, which surfaces MALFORMED honestly. Truncates per policy
+     * (last PER_NAME of any one name, then cap to TOTAL overall) and writes byte-stably.
+     */
+    recordRun(record: Omit<RunRecord, 'at'>): Promise<void>;
+    /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
+    lastRun(name: string): Promise<RunRecord | undefined>;
+}
+//# sourceMappingURL=project-store.d.ts.map

package/dist/project/project-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-store.d.ts","sourceRoot":"","sources":["../../src/project/project-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,gBAAgB,EAChB,KAAK,WAAW,EAEhB,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAK/C,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAI5C;;;;GAIG;AACH,qBAAa,YAAY;;gBAKX,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;IAoB1D,mGAAmG;IAC7F,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC;IA0BxC;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7D,iGAAiG;IAC3F,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;CAS5D"}

package/dist/project/project-store.js

@@ -0,0 +1,127 @@
+import { PROJECT_FILE_VERSION, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
+import { reticleDirPaths } from './reticle-dir.js';
+const JSON_INDENT = 2;
+const EMPTY_PROJECT = { version: PROJECT_FILE_VERSION, runs: [] };
+/**
+ * Cross-run outcome memory persisted at .reticle/project.json. Models FlowStore:
+ * injected FileSystemPort + Clock, byte-stable serialize, never-throws read. The clock is the
+ * single `at`-stamp site so handlers pass an un-stamped record and no Date.now leaks into logic.
+ */
+export class ProjectStore {
+    #fs;
+    #root;
+    #clock;
+    constructor(fs, root, clock) {
+        this.#fs = fs;
+        this.#root = root;
+        this.#clock = clock;
+    }
+    /**
+     * Byte-stable serializer: fixed field order (rebuilt literals, never insertion order), 2-space
+     * indent + trailing newline. `runs` stays chronological (append order = the data, never sorted);
+     * `learned` arrays ARE sorted for diff-stability. Two semantically-equal files → identical bytes.
+     */
+    #serialize(file) {
+        const envelope = {
+            version: PROJECT_FILE_VERSION,
+            ...(file.learned !== undefined ? { learned: serializeLearned(file.learned) } : {}),
+            runs: file.runs.map(serializeRun),
+        };
+        return `${JSON.stringify(envelope, null, JSON_INDENT)}\n`;
+    }
+    /** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. Mirrors readContract. */
+    async read() {
+        const path = reticleDirPaths(this.#root).project;
+        if (!(await this.#fs.exists(path)))
+            return { ok: false, reason: ProjectReadError.MISSING };
+        let text;
+        try {
+            text = await this.#fs.readFile(path);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: this.#fs.isNotFound(error) ? ProjectReadError.MISSING : ProjectReadError.MALFORMED,
+            };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return { ok: false, reason: ProjectReadError.MALFORMED };
+        }
+        const result = ProjectFileSchema.safeParse(parsed);
+        if (!result.success)
+            return { ok: false, reason: ProjectReadError.MALFORMED };
+        return { ok: true, file: result.data };
+    }
+    /**
+     * Append a run, stamping `at` from the injected clock (the one clock site). A MISSING **or
+     * MALFORMED** existing file self-heals to a fresh empty file so corrupt history never blocks
+     * recording — unlike the read path, which surfaces MALFORMED honestly. Truncates per policy
+     * (last PER_NAME of any one name, then cap to TOTAL overall) and writes byte-stably.
+     */
+    async recordRun(record) {
+        const existing = await this.read();
+        const base = existing.ok ? existing.file : EMPTY_PROJECT;
+        const stamped = { ...record, at: this.#clock.now() };
+        const runs = truncate([...base.runs, stamped]);
+        const next = { ...base, runs };
+        await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+        await this.#fs.writeFile(reticleDirPaths(this.#root).project, this.#serialize(next));
+    }
+    /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
+    async lastRun(name) {
+        const read = await this.read();
+        if (!read.ok)
+            return undefined;
+        for (let i = read.file.runs.length - 1; i >= 0; i -= 1) {
+            const run = read.file.runs[i];
+            if (run !== undefined && run.name === name)
+                return run;
+        }
+        return undefined;
+    }
+}
+/** Field-ordered rebuild of one run record so serialization is byte-stable. */
+function serializeRun(run) {
+    return {
+        kind: run.kind,
+        name: run.name,
+        status: run.status,
+        at: run.at,
+        ...(run.summary !== undefined ? { summary: run.summary } : {}),
+        ...(run.evidence !== undefined ? { evidence: run.evidence } : {}),
+        ...(run.durationMs !== undefined ? { durationMs: run.durationMs } : {}),
+    };
+}
+/** Sorted, field-ordered rebuild of the learned map for diff-stability. */
+function serializeLearned(learned) {
+    return {
+        ...(learned.flows !== undefined ? { flows: [...learned.flows].sort() } : {}),
+        ...(learned.routes !== undefined ? { routes: [...learned.routes].sort() } : {}),
+    };
+}
+/**
+ * Keep at most PER_NAME most-recent runs of any single name, then cap the whole list to TOTAL
+ * most-recent overall. Chronological order (oldest→newest) is preserved throughout.
+ */
+function truncate(runs) {
+    const perName = new Map();
+    const keptReversed = [];
+    for (let i = runs.length - 1; i >= 0; i -= 1) {
+        const run = runs[i];
+        if (run === undefined)
+            continue;
+        const count = perName.get(run.name) ?? 0;
+        if (count >= PROJECT_RUN_CAP.PER_NAME)
+            continue;
+        perName.set(run.name, count + 1);
+        keptReversed.push(run);
+        if (keptReversed.length >= PROJECT_RUN_CAP.TOTAL)
+            break;
+    }
+    return keptReversed.reverse();
+}
+//# sourceMappingURL=project-store.js.map

package/dist/project/project-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-store.js","sourceRoot":"","sources":["../../src/project/project-store.ts"],"names":[],"mappings":"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"}

package/dist/project/project-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDef } from '../tools/tools.js';
+/**
+ * The cross-run memory tools. `reticle_project` reads .reticle/project.json (optionally
+ * scoped to a name, with a diff-vs-last summary); `reticle_run_record` explicitly records an outcome
+ * (the manual companion to the auto-record on reticle_flow_replay). Both keep the agent's "did this
+ * behave like last run?" question answerable without re-deriving it from raw observations.
+ */
+export declare const PROJECT_TOOLS: ToolDef[];
+//# sourceMappingURL=project-tools.d.ts.map

package/dist/project/project-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-tools.d.ts","sourceRoot":"","sources":["../../src/project/project-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AA4D3D;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,OAAO,EAoElC,CAAC"}

package/dist/project/project-tools.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { ProjectReadError, RunKind, RunStatus } from '@reticlehq/core';
+import { ReticleTool } from '../tools/tool-names.js';
+import { asString } from '../tools/tools-helpers.js';
+const sessionIdShape = {
+    sessionId: z
+        .string()
+        .optional()
+        .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+};
+const REGRESSION_STATUSES = new Set([
+    RunStatus.FAIL,
+    RunStatus.DRIFT,
+    RunStatus.ERROR,
+]);
+function diffRuns(previous, current) {
+    const consoleErrorsDelta = numericDelta(previous.evidence?.consoleErrors, current.evidence?.consoleErrors);
+    const driftStepsDelta = numericDelta(previous.evidence?.driftSteps, current.evidence?.driftSteps);
+    return {
+        statusChanged: previous.status !== current.status,
+        previousStatus: previous.status,
+        currentStatus: current.status,
+        // Regressed = current is a non-pass outcome that the previous run was not.
+        regressed: REGRESSION_STATUSES.has(current.status) && !REGRESSION_STATUSES.has(previous.status),
+        ...(consoleErrorsDelta !== undefined ? { consoleErrorsDelta } : {}),
+        ...(driftStepsDelta !== undefined ? { driftStepsDelta } : {}),
+    };
+}
+function numericDelta(before, after) {
+    if (before === undefined && after === undefined)
+        return undefined;
+    return (after ?? 0) - (before ?? 0);
+}
+/** The two most-recent runs for `name`, oldest-first, or undefined if there are fewer than two. */
+function lastTwoFor(runs, name) {
+    const matching = runs.filter((r) => r.name === name);
+    const n = matching.length;
+    if (n < 2)
+        return undefined;
+    const previous = matching[n - 2];
+    const current = matching[n - 1];
+    if (previous === undefined || current === undefined)
+        return undefined;
+    return [previous, current];
+}
+/**
+ * The cross-run memory tools. `reticle_project` reads .reticle/project.json (optionally
+ * scoped to a name, with a diff-vs-last summary); `reticle_run_record` explicitly records an outcome
+ * (the manual companion to the auto-record on reticle_flow_replay). Both keep the agent's "did this
+ * behave like last run?" question answerable without re-deriving it from raw observations.
+ */
+export const PROJECT_TOOLS = [
+    {
+        name: ReticleTool.PROJECT,
+        description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". Returns { runs, learned?, lastRun?, diff? } or { error, reason } when no/invalid history exists.',
+        inputSchema: {
+            name: z.string().optional().describe('Filter runs by this name. Omit to return all runs.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            runs: z.array(z.unknown()),
+            diff: z.unknown().optional(),
+        },
+        handler: async (deps, args) => {
+            const read = await deps.project.read();
+            if (!read.ok) {
+                return {
+                    error: read.reason === ProjectReadError.MISSING
+                        ? 'no .reticle/project.json yet — run a flow (reticle_flow_replay) or reticle_run_record first'
+                        : '.reticle/project.json is malformed — it will self-heal on the next recorded run',
+                    reason: read.reason,
+                };
+            }
+            const name = asString(args['name']);
+            if (name === undefined) {
+                return { runs: read.file.runs, learned: read.file.learned };
+            }
+            const lastRun = await deps.project.lastRun(name);
+            const pair = lastTwoFor(read.file.runs, name);
+            return {
+                runs: read.file.runs.filter((r) => r.name === name),
+                learned: read.file.learned,
+                lastRun,
+                ...(pair !== undefined ? { diff: diffRuns(pair[0], pair[1]) } : {}),
+            };
+        },
+    },
+    {
+        name: ReticleTool.RUN_RECORD,
+        description: 'Explicitly record a run outcome into .reticle/project.json (the manual companion to the auto-record on reticle_flow_replay). Use it to log the result of an assertion sequence or a manual journey so future runs can diff against it. Returns { recorded:true, name, status }.',
+        inputSchema: {
+            name: z.string().describe('Run name for grouping in reticle_project history.'),
+            status: z.nativeEnum(RunStatus).describe('Outcome: pass | fail | drift | error'),
+            kind: z.nativeEnum(RunKind).optional(),
+            summary: z.string().optional().describe('One-line human summary of what this run covered.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            recorded: z.boolean(),
+            runName: z.string(),
+            status: z.string(),
+        },
+        handler: async (deps, args) => {
+            const name = asString(args['name']) ?? '';
+            const status = args['status'];
+            const kindArg = args['kind'];
+            const summary = asString(args['summary']);
+            await deps.project.recordRun({
+                kind: typeof kindArg === 'string' ? kindArg : RunKind.MANUAL,
+                name,
+                status,
+                ...(summary !== undefined ? { summary } : {}),
+            });
+            return { recorded: true, runName: name, status };
+        },
+    },
+];
+//# sourceMappingURL=project-tools.js.map

package/dist/project/project-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-tools.js","sourceRoot":"","sources":["../../src/project/project-tools.ts"],"names":[],"mappings":"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"}

package/dist/project/reticle-dir.d.ts

@@ -0,0 +1,61 @@
+import { ContractReadError, type CapabilitiesContract, type RunId } from '@reticlehq/core';
+import type { FileSystemPort } from './fs-port.js';
+/** Resolved absolute paths inside a `.reticle/` root. Pure: join() only, no IO, no cwd. */
+export interface ReticleDirPaths {
+    /** .../.reticle */
+    root: string;
+    /** .../.reticle/contract.json */
+    contract: string;
+    /** .../.reticle/flows */
+    flows: string;
+    /** .../.reticle/baselines */
+    baselines: string;
+    /** .../.reticle/project.json (cross-run outcome memory) */
+    project: string;
+    /** .../.reticle/visual (PNG baselines + diffs) */
+    visual: string;
+    /** .../.reticle/runs (verification-run artifacts) */
+    runs: string;
+}
+export declare function reticleDirPaths(root: string): ReticleDirPaths;
+/** The verification-run artifact path for `runId` (.reticle/runs/<runId>.json). */
+export declare function runPath(root: string, runId: string): string;
+/**
+ * A runId must be a single safe path segment — same guard as flow names (rejects '../', '/', '\\',
+ * absolute, dotfiles). uuid-style ids (hyphens/underscores) pass. Guards every disk op before join.
+ */
+export declare function isValidRunId(runId: string): runId is RunId;
+/** The PNG baseline path for `name` (.reticle/visual/<name>.png). */
+export declare function visualPath(root: string, name: string): string;
+/** The overlay-diff PNG path for `name` (.reticle/visual/<name>.diff.png). */
+export declare function visualDiffPath(root: string, name: string): string;
+/**
+ * Path to a flow file. With a `projectId`, the flow lives in a per-project subdir
+ * (`.reticle/flows/<projectId>/<name>.json`) so a shared daemon serving many apps can't collide two
+ * apps' flows of the same name; without one it's the flat legacy path (`.reticle/flows/<name>.json`),
+ * which is also where pre-existing (untagged) flows stay. Callers pass ONLY a validated projectId.
+ */
+export declare function flowPath(root: string, name: string, projectId?: string): string;
+/** The directory a flow write targets: the per-project subdir, or the flat flows root for global. */
+export declare function flowDir(root: string, projectId?: string): string;
+/**
+ * A flow name must be a single safe path segment — rejects '../', '/', '\\', absolute, dotfiles.
+ * Guards every disk op before a path is ever joined, so a traversal name never escapes .reticle/.
+ */
+export declare function isValidFlowName(name: string): boolean;
+export declare function baselinePath(root: string, name: string): string;
+/** Idempotent: creates .reticle/, .reticle/flows/, .reticle/baselines/ (recursive mkdir → safe to re-run). */
+export declare function ensureReticleDir(fs: FileSystemPort, root: string): Promise<void>;
+/** Write the contract to .reticle/contract.json (auto-creating .reticle/ first). */
+export declare function writeContract(fs: FileSystemPort, root: string, capabilities: CapabilitiesContract, now: () => number): Promise<void>;
+export type ReadContractResult = {
+    ok: true;
+    capabilities: CapabilitiesContract;
+    generatedAt: number;
+} | {
+    ok: false;
+    reason: ContractReadError;
+};
+/** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. */
+export declare function readContract(fs: FileSystemPort, root: string): Promise<ReadContractResult>;
+//# sourceMappingURL=reticle-dir.d.ts.map

package/dist/project/reticle-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reticle-dir.d.ts","sourceRoot":"","sources":["../../src/project/reticle-dir.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,iBAAiB,EAGjB,KAAK,oBAAoB,EAEzB,KAAK,KAAK,EACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAU7D;AAED,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,KAAK,CAE1D;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/E;AAED,qGAAqG;AACrG,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,8GAA8G;AAC9G,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKtF;AAiDD,oFAAoF;AACpF,wBAAsB,aAAa,CACjC,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,oBAAoB,EAClC,GAAG,EAAE,MAAM,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,oBAAoB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAE7C,6EAA6E;AAC7E,wBAAsB,YAAY,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAyBhG"}