@reticlehq/server 3.6.0 → 3.7.0

package/dist/language/flows/narrow-write.d.ts

@@ -25,7 +25,14 @@ export interface NarrowWritePort {
     resolvePath: (name: string, projectId?: ProjectId) => Promise<string | null>;
     write: (path: string, contents: string) => Promise<void>;
     serialize: (flow: FlowFile) => string;
+    /** The file as it is on disk, so a change lands in it and nothing else moves. */
+    readRaw?: (path: string) => Promise<string>;
 }
+/**
+ * `raw` with only what changed between `before` and `after` applied, everything else as written:
+ * its key order, its fields the reader fills in by default, its own spelling. Pure.
+ */
+export declare function withChangesOnly(raw: unknown, before: unknown, after: unknown): unknown;
 export declare function changeInPlace<T>(port: NarrowWritePort, name: string, projectId: ProjectId | undefined, change: (flow: FlowFile) => {
     next: FlowFile;
     value: T;

package/dist/language/flows/narrow-write.js

@@ -2,6 +2,28 @@ import { FlowErrorCode, FlowFileSchema } from '@reticlehq/core';
 import { describeFlowZodFailure } from './flow-expect-grammar.js';
 import { isValidFlowName } from '../../memory/project/dir/reticle-dir.js';
 import { safeProjectId } from './flow-result.js';
+const isPlain = (v) => 'object' === typeof v && null !== v && !Array.isArray(v);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * `raw` with only what changed between `before` and `after` applied, everything else as written:
+ * its key order, its fields the reader fills in by default, its own spelling. Pure.
+ */
+export function withChangesOnly(raw, before, after) {
+    if (Array.isArray(raw) && Array.isArray(before) && Array.isArray(after))
+        return raw.length === before.length && before.length === after.length
+            ? raw.map((item, i) => withChangesOnly(item, before[i], after[i]))
+            : after;
+    if (!isPlain(raw) || !isPlain(before) || !isPlain(after))
+        return after;
+    const out = { ...raw };
+    for (const key of Object.keys(after))
+        if (!same(after[key], before[key]))
+            out[key] = key in raw ? withChangesOnly(raw[key], before[key], after[key]) : after[key];
+    for (const key of Object.keys(before))
+        if (!(key in after))
+            delete out[key];
+    return out;
+}
 export async function changeInPlace(port, name, projectId, change) {
     if (!isValidFlowName(name))
         return { ok: false, code: FlowErrorCode.INVALID_NAME };
@@ -21,6 +43,19 @@ export async function changeInPlace(port, name, projectId, change) {
             detail: describeFlowZodFailure(parsed.error),
         };
     }
-    await port.write(path, port.serialize(parsed.data));
+    // A replay that learned nothing new leaves a committed file alone: every replay used to rewrite
+    // it (keys reordered, defaults written in), and `git status` called it modified.
+    if (port.serialize(parsed.data) === port.serialize(loaded.value))
+        return { ok: true, value };
+    let raw;
+    try {
+        raw = JSON.parse((await port.readRaw?.(path)) ?? 'null');
+    }
+    catch {
+        raw = null;
+    }
+    await port.write(path, isPlain(raw)
+        ? `${JSON.stringify(withChangesOnly(raw, loaded.value, parsed.data), null, 2)}\n`
+        : port.serialize(parsed.data));
     return { ok: true, value };
 }

package/dist/language/flows/recording/recording-backtrack.js

@@ -27,6 +27,19 @@ function recordingRouteOf(pathname, hash = '') {
         return routePathOf(0 === pathname.length ? '/' : pathname, fragment);
     return pathname;
 }
+/**
+ * A startPath as a page key: its query dropped, hash kept. A startPath keeps the app's query so
+ * replay starts on the filtered page (#1411), but a ROUTE_CHANGE contributes only pathname and
+ * hash, so `/products?scope=X` then `/checkout` then `/products` must compare the first and last
+ * as one page or the backtrack goes unseen.
+ */
+function pageKeyOf(startPath) {
+    const hashAt = startPath.indexOf('#');
+    const queryAt = startPath.indexOf('?');
+    if (queryAt < 0 || (hashAt >= 0 && queryAt > hashAt))
+        return startPath;
+    return startPath.slice(0, queryAt) + (hashAt >= 0 ? startPath.slice(hashAt) : '');
+}
 function collapseConsecutive(routes) {
     const out = [];
     for (const route of routes) {
@@ -60,7 +73,7 @@ export function recordingBacktrackWarning(routes) {
 export function routesFromRecording(startPath, events) {
     const raw = [];
     if (undefined !== startPath)
-        raw.push(recordingRouteOf(startPath));
+        raw.push(recordingRouteOf(pageKeyOf(startPath)));
     for (const event of events) {
         if (EventType.ROUTE_CHANGE !== event.type)
             continue;

package/dist/language/flows/recording/tape/recordings.d.ts

@@ -7,6 +7,8 @@ export interface RecordedStep {
     args: Record<string, unknown>;
     /** false if any ref could not be normalized to a testid (replay only valid in-session). */
     stable: boolean;
+    /** The caller's per-step wait budget, when one was explicitly provided. */
+    timeoutMs?: number;
     /** Optional post-condition annotation carried into the on-disk flow's expect. */
     expect?: Predicate;
     /**
@@ -27,6 +29,12 @@ export interface RecordedStep {
      * `invoke` first and treats the step as a call.
      */
     invoke?: string;
+    /**
+     * Network mocks were active on this step's tab when it ran. RECORDER-INTERNAL, ambient tape only,
+     * like `route`: a journey that ran against mocked responses replays against the real backend,
+     * so it is not auto-saved (#1459).
+     */
+    mocked?: true;
     /** The page this step ran on. Written to the saved step (unlike `route`, which cuts journeys). */
     page?: string;
     /** The page it ended on once it settled — see `markEnded`. */
@@ -51,6 +59,11 @@ interface ActiveRecording {
     steps: RecordedStep[];
     /** The route the journey began on. See CompiledProgram.startPath. */
     startPath?: string;
+    /**
+     * The document the tab was on at start. A full-page load makes a new one even when the SDK keeps
+     * its session id, and its clock is from a different connection, so this is how stop tells (#1411).
+     */
+    document?: string;
     /**
      * For each recording that was ALREADY in flight when this one started, how many steps it had.
      *
@@ -101,12 +114,20 @@ export declare const INVOKE_TOOL: string;
  * buffer.
  */
 export declare const AMBIENT_RECORDING = "__ambient__";
+/**
+ * One ambient tape per tab. It was one for the whole daemon, so a drive in ANOTHER app (the console
+ * beside the repo's own app) was cut into a flow and saved into this repo's committed `flows/`, and
+ * synced to its project. A tape now holds one tab's steps, and that tab's end takes only its own.
+ */
+export declare const ambientRecordingOf: (session: string | undefined) => string;
+/** Whether a recording is an ambient tape: the daemon's own, never one somebody opened. */
+export declare const isAmbient: (name: string) => boolean;
 export declare class RecordingStore {
     #private;
     private readonly byHarness;
     /** `byHarness`: whether the step being captured was driven by the Harness, which tapes its own. */
     constructor(byHarness?: () => boolean);
-    start(name: string, cursor: number, startPath?: string, session?: string): void;
+    start(name: string, cursor: number, startPath?: string, session?: string, document?: string): void;
     isRecording(name: string): boolean;
     /**
      * Number of steps captured so far in the named ACTIVE recording (0 if it
@@ -127,6 +148,11 @@ export declare class RecordingStore {
      * Opened lazily on the first step rather than in the constructor: a store that never records
      * anything should not carry an empty tape, and "did anything happen at all" stays answerable.
      */
+    /**
+     * Whether a tab has network mocks installed from now on. Each ambient step on it is marked while
+     * they are, so the journey it belongs to is not auto-saved as a flow (#1459).
+     */
+    markMocked(session: string | undefined, active: boolean): void;
     capture(step: RecordedStep, route?: string, session?: string): void;
     /**
      * Add a consequence to the last captured step of every active recording.
@@ -176,6 +202,8 @@ export declare class RecordingStore {
     saveCompiled(program: CompiledProgram): void;
     getCompiled(name: string): CompiledProgram | undefined;
     active(): string[];
+    /** The ambient tape of one tab (or of steps no tab named), taken: what its session end saves. */
+    takeAmbient(session: string | undefined): ActiveRecording | undefined;
     /**
      * Names of recordings that have been STOPPED and compiled.
      *

package/dist/language/flows/recording/tape/recordings.js

@@ -20,6 +20,14 @@ export const INVOKE_TOOL = FlowStepTool.INVOKE;
  * buffer.
  */
 export const AMBIENT_RECORDING = '__ambient__';
+/**
+ * One ambient tape per tab. It was one for the whole daemon, so a drive in ANOTHER app (the console
+ * beside the repo's own app) was cut into a flow and saved into this repo's committed `flows/`, and
+ * synced to its project. A tape now holds one tab's steps, and that tab's end takes only its own.
+ */
+export const ambientRecordingOf = (session) => session === undefined ? AMBIENT_RECORDING : `${AMBIENT_RECORDING}:${session}`;
+/** Whether a recording is an ambient tape: the daemon's own, never one somebody opened. */
+export const isAmbient = (name) => AMBIENT_RECORDING === name || name.startsWith(`${AMBIENT_RECORDING}:`);
 /**
  * How long a journey the ambient tape will hold.
  *
@@ -32,13 +40,17 @@ export class RecordingStore {
     byHarness;
     #active = new Map();
     #compiled = new Map();
+    /** The ambient tape the last step went on: the one a refuted claim is taken off. */
+    #lastAmbient;
     /** A navigation came after the last captured step — see markNavigated. */
     #navigatedSinceStep = false;
+    /** Tabs with network mocks installed now, keyed by session ('' for none named). See markMocked. */
+    #mocked = new Set();
     /** `byHarness`: whether the step being captured was driven by the Harness, which tapes its own. */
     constructor(byHarness = () => false) {
         this.byHarness = byHarness;
     }
-    start(name, cursor, startPath, session) {
+    start(name, cursor, startPath, session, document) {
         const openedOver = new Map();
         for (const [outer, rec] of this.#targets(session))
             openedOver.set(outer, rec.steps.length);
@@ -48,6 +60,7 @@ export class RecordingStore {
             openedOver,
             ...(startPath === undefined ? {} : { startPath }),
             ...(session === undefined ? {} : { session }),
+            ...(document === undefined ? {} : { document }),
         });
     }
     /** The open recordings a step from `session` belongs to. See ActiveRecording.session. */
@@ -78,27 +91,44 @@ export class RecordingStore {
      * Opened lazily on the first step rather than in the constructor: a store that never records
      * anything should not carry an empty tape, and "did anything happen at all" stays answerable.
      */
+    /**
+     * Whether a tab has network mocks installed from now on. Each ambient step on it is marked while
+     * they are, so the journey it belongs to is not auto-saved as a flow (#1459).
+     */
+    markMocked(session, active) {
+        if (active)
+            this.#mocked.add(session ?? '');
+        else
+            this.#mocked.delete(session ?? '');
+    }
     capture(step, route, session) {
         this.#navigatedSinceStep = false;
-        if (!this.#active.has(AMBIENT_RECORDING)) {
-            this.#active.set(AMBIENT_RECORDING, {
+        const mocked = this.#mocked.has(session ?? '');
+        const ambient = ambientRecordingOf(session);
+        if (!this.#active.has(ambient)) {
+            this.#active.set(ambient, {
                 cursor: 0,
                 steps: [],
                 openedOver: new Map(),
+                ...(session === undefined ? {} : { session }),
             });
         }
+        this.#lastAmbient = ambient;
         for (const [name, rec] of this.#targets(session)) {
+            // Another tab's tape is that tab's journey, whatever else this step belongs to.
+            if (isAmbient(name) && name !== ambient)
+                continue;
             // The ambient tape is opened by the system and closed by nobody, so it is the one recording
             // with no human deciding when it has seen enough. Bounded here rather than left to grow for
             // the length of a daemon's life. Appending STOPS at the cap instead of dropping the oldest: a
             // flow replays from its FIRST step, so a tape missing its beginning is not a shorter journey,
             // it is a different one that starts in a state nothing established. A recording somebody
             // opened on purpose is not capped — they said when it starts and they say when it stops.
-            if (AMBIENT_RECORDING === name && rec.steps.length >= AMBIENT_STEP_CAP)
+            if (isAmbient(name) && rec.steps.length >= AMBIENT_STEP_CAP)
                 continue;
             // The Harness saves its own recordings. Taping its steps too saved every drive twice: once as
             // the Harness's flow and again, at session end, as a `drive-*` copy with a guessed name.
-            if (AMBIENT_RECORDING === name && this.byHarness())
+            if (isAmbient(name) && this.byHarness())
                 continue;
             // A step nobody marked ended where the next one began.
             const previous = rec.steps.at(-1);
@@ -108,7 +138,13 @@ export class RecordingStore {
             // The route rides on the AMBIENT tape only: a recording somebody opened deliberately is
             // already one journey by construction, and stamping a route on its steps would change what a
             // deliberate recording contains.
-            rec.steps.push(AMBIENT_RECORDING === name && route !== undefined ? { ...step, route } : step);
+            rec.steps.push(isAmbient(name) && (route !== undefined || mocked)
+                ? {
+                    ...step,
+                    ...(route === undefined ? {} : { route }),
+                    ...(mocked ? { mocked: true } : {}),
+                }
+                : step);
         }
     }
     /**
@@ -121,10 +157,17 @@ export class RecordingStore {
     attachExpect(expect, session) {
         if (this.#navigatedSinceStep)
             return;
-        for (const [, rec] of this.#targets(session)) {
+        const mocked = this.#mocked.has(session ?? '');
+        for (const [name, rec] of this.#targets(session)) {
+            if (isAmbient(name) && name !== ambientRecordingOf(session))
+                continue;
             const last = rec.steps.at(-1);
             if (last === undefined)
                 continue;
+            // A proof read while mocks are active rests on mocked responses even when the act before it
+            // ran unmocked, so the ambient step it joins is marked too (#1459).
+            if (mocked && isAmbient(name))
+                last.mocked = true;
             const held = last.expect;
             last.expect =
                 held === undefined
@@ -153,7 +196,7 @@ export class RecordingStore {
      * is left as they drove it.
      */
     unassertLast() {
-        const tape = this.#active.get(AMBIENT_RECORDING);
+        const tape = this.#lastAmbient === undefined ? undefined : this.#active.get(this.#lastAmbient);
         const last = tape?.steps.at(-1);
         if (tape === undefined || last === undefined || last.expect === undefined)
             return;
@@ -169,7 +212,9 @@ export class RecordingStore {
     markEnded(page, session) {
         if (page === undefined)
             return;
-        for (const [, rec] of this.#targets(session)) {
+        for (const [name, rec] of this.#targets(session)) {
+            if (isAmbient(name) && name !== ambientRecordingOf(session))
+                continue;
             const last = rec.steps.at(-1);
             if (last !== undefined && last.endPage === undefined)
                 last.endPage = page;
@@ -214,7 +259,12 @@ export class RecordingStore {
         return this.#compiled.get(name);
     }
     active() {
-        return [...this.#active.keys()];
+        // One tab's tape is that tab's: the list names what somebody opened, and the plain tape as before.
+        return [...this.#active.keys()].filter((name) => !name.startsWith(`${AMBIENT_RECORDING}:`));
+    }
+    /** The ambient tape of one tab (or of steps no tab named), taken: what its session end saves. */
+    takeAmbient(session) {
+        return this.stop(ambientRecordingOf(session));
     }
     /**
      * Names of recordings that have been STOPPED and compiled.

package/dist/language/flows/replay.js

@@ -1,7 +1,7 @@
-import { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
+import { REDACTED_FILL, SECRET_NAME_ARG, secretEnvKey, secretValue, } from './fields/flow-secret-field.js';
 import { FlowPredicateSchema, Verified } from '@reticlehq/core';
 import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
-import { ReticleTool } from '@reticlehq/core';
+import { ReticleTool, invokedFlowMissing } from '@reticlehq/core';
 import { formatStepAddress } from 'open-verification';
 import { refFor } from './flow-anchor.js';
 import { asRecord, asString } from '@reticlehq/core';
@@ -44,10 +44,11 @@ export function queryRefs(result) {
 export function replayActionArgs(value, confirmDangerous = false, field) {
     const args = { ...asRecord(value) };
     delete args[DANGEROUS_ACTION_CONFIRM_ARG];
+    delete args[SECRET_NAME_ARG];
     if (confirmDangerous)
         args[DANGEROUS_ACTION_CONFIRM_ARG] = true;
     if (REDACTED_FILL === args['value'] && field !== undefined) {
-        const supplied = process.env[secretEnvKey(field)];
+        const supplied = secretValue(secretEnvKey(field), process.env);
         if (supplied !== undefined && supplied.length > 0)
             args['value'] = supplied;
     }
@@ -176,7 +177,23 @@ function enforceableExpect(raw) {
  */
 export function compileActStep(args, res) {
     const { args: compiled, stable } = compileAnchorArgs(asRecord(res), asString(args['ref']) ?? '', asString(args['action']) ?? '', replayActionArgs(args['args']));
-    return { tool: ReticleTool.ACT, stable, args: compiled };
+    const timeoutMs = explicitTimeoutMs(args);
+    return {
+        tool: ReticleTool.ACT,
+        stable,
+        args: compiled,
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    };
+}
+/** Keep only the timeout shape accepted by the public tool, including an intentional zero. */
+function explicitTimeoutMs(args) {
+    const timeoutMs = args['timeout_ms'];
+    return 'number' === typeof timeoutMs &&
+        Number.isFinite(timeoutMs) &&
+        Number.isInteger(timeoutMs) &&
+        0 <= timeoutMs
+        ? timeoutMs
+        : undefined;
 }
 /**
  * The ONE anchor chooser: testid (gold) > role+name (identifies an instance) > component/source
@@ -258,7 +275,13 @@ export function compileSequenceStep(args, res) {
         const expect = enforceableExpect(step['expect']);
         return expect === undefined ? compiled.args : { ...compiled.args, expect };
     });
-    return { tool: ReticleTool.ACT_SEQUENCE, stable, args: { steps: subSteps } };
+    const timeoutMs = explicitTimeoutMs(args);
+    return {
+        tool: ReticleTool.ACT_SEQUENCE,
+        stable,
+        args: { steps: subSteps },
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    };
 }
 /**
  * Resolve a recorded step's element to a live ref, by whichever anchor the compiler chose.
@@ -368,7 +391,7 @@ via = []) {
                     tool: step.tool,
                     ok: false,
                     at: address,
-                    error: `cannot replay "${step.invoke}": it was not found, so this journey would report green having never run it`,
+                    error: invokedFlowMissing(step.invoke),
                 });
                 break;
             }

package/dist/language/flows/single-replay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `reticle_flow_replay`'s answer: one flow replayed, written down as a run, ending with the Reticle
+ * result block. The run id is minted first, so each replayed step's screenshot is filed under it.
+ */
+import { type FlowReplayResult } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+export declare function replayOneFlow(deps: ToolDeps, args: Record<string, unknown>, appUrl: string | undefined): Promise<FlowReplayResult>;

package/dist/language/flows/single-replay.js

@@ -0,0 +1,26 @@
+/**
+ * `reticle_flow_replay`'s answer: one flow replayed, written down as a run, ending with the Reticle
+ * result block. The run id is minted first, so each replayed step's screenshot is filed under it.
+ */
+import { asString } from '@reticlehq/core';
+import { defaultRunId, withShotRun } from '../../judgement/runs/default-run-id.js';
+import { persistAndSyncVerificationRun } from '../../judgement/runs/verification-sync.js';
+import { rootForTarget, safeSessionTarget } from '../../memory/project/session-root.js';
+import { replayResult, resultField } from '../../surface/tools/reticle-result.js';
+import { replaySeededOrNot } from './flow-learning.js';
+export function replayOneFlow(deps, args, appUrl) {
+    return withShotRun(defaultRunId(), async () => {
+        const start = deps.now();
+        const replay = await replaySeededOrNot(deps, args, appUrl);
+        const durationMs = deps.now() - start;
+        const target = safeSessionTarget(deps, asString(args['sessionId']));
+        // Written down as a run, and named in the answer: the platform's Re-verify ties its check to
+        // it, and a check with no run could never resolve the issue it was for.
+        const runId = await persistAndSyncVerificationRun(deps, [{ replay, durationMs }], target);
+        return {
+            ...replay,
+            ...(runId === undefined ? {} : { runId }),
+            ...resultField(() => replayResult(rootForTarget(deps, target), replay, durationMs, runId)),
+        };
+    });
+}

package/dist/language/flows/verify-change-tools.d.ts

@@ -1,2 +1,3 @@
 import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/** Every answer carries the Reticle result block, under the verdict this tool decided. */
 export declare const VERIFY_CHANGE_TOOLS: ToolDef[];