@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,134 @@
+import { type FlowExpect } from '@reticlehq/core';
+/** One captured agent action, normalized for replay. */
+export interface RecordedStep {
+    /** ReticleTool.ACT | ReticleTool.ACT_SEQUENCE */
+    tool: string;
+    /** Normalized args: refs replaced by { by:'testid', value } where resolvable. */
+    args: Record<string, unknown>;
+    /** false if any ref could not be normalized to a testid (replay only valid in-session). */
+    stable: boolean;
+    /** Optional post-condition annotation carried into the on-disk flow's expect. */
+    expect?: FlowExpect;
+    /**
+     * The route this step ran on. RECORDER-INTERNAL: it never reaches the on-disk flow.
+     *
+     * It exists so an ambient tape — which records a whole session rather than a journey somebody
+     * chose — can be cut into journeys at session end. Without it the tape is one flow that starts at
+     * the login screen and ends wherever the agent stopped, and replaying a suite of those fails on
+     * the second one: the app is already authenticated, so the login steps no longer apply. See
+     * drive-flow.ts, and the same hazard written down in bench/harness/suite-rre.mjs.
+     */
+    route?: string;
+    /**
+     * The document this step runs, when the step is an INVOCATION rather than an action.
+     *
+     * Written by `stop` when a nested recording closes inside an outer one. `tool` and `args` are
+     * still present and still describe nothing the replayer should dispatch — a consumer reads
+     * `invoke` first and treats the step as a call.
+     */
+    invoke?: string;
+}
+interface ActiveRecording {
+    cursor: number;
+    steps: RecordedStep[];
+    /** The route the journey began on. See CompiledProgram.startPath. */
+    startPath?: string;
+    /**
+     * For each recording that was ALREADY in flight when this one started, how many steps it had.
+     *
+     * That mark is what makes a sub-flow boundary knowable. `capture` appends to every active
+     * recording, so a nested span lands in the outer one INLINED — which is a composite-shaped
+     * journey with none of composition's value: the drift still reports "step 34 of onboarding",
+     * repair still has to happen in every copy, and the sub-journey cannot be reused. With the mark,
+     * `stop` can replace exactly the span it owns with a single invocation.
+     *
+     * Recorded at START rather than derived at stop, because by then the outer recording has grown
+     * and there is nothing left to say where this one began.
+     */
+    openedOver: ReadonlyMap<string, number>;
+}
+/** A finished, replayable program compiled from a recording. */
+export interface CompiledProgram {
+    name: string;
+    version: number;
+    steps: RecordedStep[];
+    startPath?: string;
+    /**
+     * Pages the recording sat on, in order, consecutive stays collapsed. In-memory only — not written
+     * to the flow file. Lets save warn about a backtrack (a journey that cannot replay) without a
+     * format change.
+     */
+    routes?: string[];
+}
+/**
+ * The `tool` written on an invocation step — core's constant, re-exported for this module's callers.
+ *
+ * NOT a second spelling. It crosses the recorder, the saved file and the replayer, and core is where
+ * a string that crosses those is defined; a local copy is a rename away from a recorder that writes
+ * what no replayer reads, which is the drift `FlowStepTool` was created to end.
+ */
+export declare const INVOKE_TOOL: string;
+/**
+ * Tracks in-flight recordings (name -> { buffer cursor at record_start, captured steps })
+ * and the last compiled program per name (for reticle_replay).
+ */
+/**
+ * The recording that is always running.
+ *
+ * Reserved and double-underscored so an agent cannot name a flow this and silently merge with it.
+ * Taking it with `stop()` returns what has accumulated and leaves the store ready to open a fresh
+ * one on the next step, so a long session is a series of takeable tapes rather than one unbounded
+ * buffer.
+ */
+export declare const AMBIENT_RECORDING = "__ambient__";
+export declare class RecordingStore {
+    #private;
+    start(name: string, cursor: number, startPath?: string): void;
+    isRecording(name: string): boolean;
+    /**
+     * Number of steps captured so far in the named ACTIVE recording (0 if it
+     * exists but is empty, undefined if there is no active recording by that name). Lets the annotate
+     * compiler target the LAST captured step without exposing the mutable step array.
+     */
+    stepCount(name: string): number | undefined;
+    /**
+     * Append a captured step to every active recording (steps belong to all in-flight spans).
+     *
+     * The AMBIENT recording is opened here if it is not already, which is what makes recording a
+     * property of the system rather than a rule an agent has to remember. Before this, a step driven
+     * with no recording open went into the loop below, matched nothing, and was gone — so the journey
+     * that could have become a regression test, for free, out of work the agent was doing anyway,
+     * existed only when somebody called `record_start` first. A rule that must be remembered on every
+     * drive is a rule that is followed on some of them.
+     *
+     * 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.
+     */
+    capture(step: RecordedStep, route?: string): void;
+    /**
+     * Returns the active recording (cursor + steps) and clears it, or undefined if not recording.
+     *
+     * Closing a NESTED recording also rewrites its parents: the span this recording owned is replaced
+     * in each still-open outer recording by one `invoke` step. That is the moment a sub-flow boundary
+     * becomes knowable — the sub-journey is complete and it has a name, neither of which was true
+     * when it started.
+     *
+     * Only recordings this one opened OVER are rewritten. Overlapping spans are not nesting: a
+     * recording that began before this one did not contain it, and a document that invokes something
+     * it never drove replays a journey nobody took.
+     */
+    stop(name: string): ActiveRecording | undefined;
+    saveCompiled(program: CompiledProgram): void;
+    getCompiled(name: string): CompiledProgram | undefined;
+    active(): string[];
+    /**
+     * Names of recordings that have been STOPPED and compiled.
+     *
+     * The mirror of `active()`, and needed for the same defaulting: after `reticle_record stop` a
+     * recording is no longer active, so resolving "the obvious one" from `active()` finds nothing.
+     * Saving it then demanded the exact name back from the caller, which is a thing to remember for
+     * no reason when exactly one recording exists.
+     */
+    compiled(): string[];
+}
+export {};

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

@@ -0,0 +1,144 @@
+import { FlowStepTool } from '@reticlehq/core';
+/**
+ * The `tool` written on an invocation step — core's constant, re-exported for this module's callers.
+ *
+ * NOT a second spelling. It crosses the recorder, the saved file and the replayer, and core is where
+ * a string that crosses those is defined; a local copy is a rename away from a recorder that writes
+ * what no replayer reads, which is the drift `FlowStepTool` was created to end.
+ */
+export const INVOKE_TOOL = FlowStepTool.INVOKE;
+/**
+ * Tracks in-flight recordings (name -> { buffer cursor at record_start, captured steps })
+ * and the last compiled program per name (for reticle_replay).
+ */
+/**
+ * The recording that is always running.
+ *
+ * Reserved and double-underscored so an agent cannot name a flow this and silently merge with it.
+ * Taking it with `stop()` returns what has accumulated and leaves the store ready to open a fresh
+ * one on the next step, so a long session is a series of takeable tapes rather than one unbounded
+ * buffer.
+ */
+export const AMBIENT_RECORDING = '__ambient__';
+/**
+ * How long a journey the ambient tape will hold.
+ *
+ * Generous, because the cost of one truncated tape is one flow that has to be re-driven, while the
+ * cost of no cap is a daemon that grows for as long as it is up. Nothing in the product wants a
+ * 400-step regression test: the longest saved flow in the corpus is a small fraction of this.
+ */
+const AMBIENT_STEP_CAP = 400;
+export class RecordingStore {
+    #active = new Map();
+    #compiled = new Map();
+    start(name, cursor, startPath) {
+        const openedOver = new Map();
+        for (const [outer, rec] of this.#active)
+            openedOver.set(outer, rec.steps.length);
+        this.#active.set(name, {
+            cursor,
+            steps: [],
+            openedOver,
+            ...(startPath === undefined ? {} : { startPath }),
+        });
+    }
+    isRecording(name) {
+        return this.#active.has(name);
+    }
+    /**
+     * Number of steps captured so far in the named ACTIVE recording (0 if it
+     * exists but is empty, undefined if there is no active recording by that name). Lets the annotate
+     * compiler target the LAST captured step without exposing the mutable step array.
+     */
+    stepCount(name) {
+        return this.#active.get(name)?.steps.length;
+    }
+    /**
+     * Append a captured step to every active recording (steps belong to all in-flight spans).
+     *
+     * The AMBIENT recording is opened here if it is not already, which is what makes recording a
+     * property of the system rather than a rule an agent has to remember. Before this, a step driven
+     * with no recording open went into the loop below, matched nothing, and was gone — so the journey
+     * that could have become a regression test, for free, out of work the agent was doing anyway,
+     * existed only when somebody called `record_start` first. A rule that must be remembered on every
+     * drive is a rule that is followed on some of them.
+     *
+     * 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.
+     */
+    capture(step, route) {
+        if (!this.#active.has(AMBIENT_RECORDING)) {
+            this.#active.set(AMBIENT_RECORDING, {
+                cursor: 0,
+                steps: [],
+                openedOver: new Map(),
+            });
+        }
+        for (const [name, rec] of this.#active) {
+            // 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)
+                continue;
+            // 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);
+        }
+    }
+    /**
+     * Returns the active recording (cursor + steps) and clears it, or undefined if not recording.
+     *
+     * Closing a NESTED recording also rewrites its parents: the span this recording owned is replaced
+     * in each still-open outer recording by one `invoke` step. That is the moment a sub-flow boundary
+     * becomes knowable — the sub-journey is complete and it has a name, neither of which was true
+     * when it started.
+     *
+     * Only recordings this one opened OVER are rewritten. Overlapping spans are not nesting: a
+     * recording that began before this one did not contain it, and a document that invokes something
+     * it never drove replays a journey nobody took.
+     */
+    stop(name) {
+        const rec = this.#active.get(name);
+        this.#active.delete(name);
+        if (rec === undefined)
+            return undefined;
+        for (const [outer, mark] of rec.openedOver) {
+            const parent = this.#active.get(outer);
+            // Gone already, or somehow shorter than when we started: leave it exactly as it is rather
+            // than splice a range that no longer means what it meant.
+            if (parent === undefined || parent.steps.length < mark)
+                continue;
+            parent.steps.splice(mark, parent.steps.length - mark, {
+                tool: INVOKE_TOOL,
+                args: { flow: name },
+                stable: true,
+                invoke: name,
+            });
+        }
+        return rec;
+    }
+    saveCompiled(program) {
+        this.#compiled.set(program.name, program);
+    }
+    getCompiled(name) {
+        return this.#compiled.get(name);
+    }
+    active() {
+        return [...this.#active.keys()];
+    }
+    /**
+     * Names of recordings that have been STOPPED and compiled.
+     *
+     * The mirror of `active()`, and needed for the same defaulting: after `reticle_record stop` a
+     * recording is no longer active, so resolving "the obvious one" from `active()` finds nothing.
+     * Saving it then demanded the exact name back from the caller, which is a thing to remember for
+     * no reason when exactly one recording exists.
+     */
+    compiled() {
+        return [...this.#compiled.keys()];
+    }
+}

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

@@ -0,0 +1,83 @@
+import { type CommandResult } from '@reticlehq/core';
+import type { RecordedStep, CompiledProgram } from './recording/tape/recordings.js';
+import type { Session } from '../../portal/session/session.js';
+/**
+ * The note attached when a testid resolves to multiple live elements (the first match is used).
+ * Shared by BOTH replay engines (replayProgram + flow-replay's step runner) so the phrasing — which
+ * an agent reads to judge a brittle locator — can never drift between them.
+ */
+export declare function ambiguousTestidNote(value: string): string;
+/**
+ * The live element refs a QUERY resolved to (empty when it failed or matched nothing). Shared by BOTH
+ * replay engines (replayProgram + flow-replay's step runner) so element extraction — the core of anchor
+ * resolution — can't drift between them.
+ */
+export declare function queryRefs(result: CommandResult): string[];
+/**
+ * A destructive-action confirmation is one-shot and must never persist into a recording.
+ *
+ * This is also where a REDACTED fill is supplied back. Stripping credentials out of a git-checked
+ * flow is only half a fix: sign-in still has to replay, and a flow that drifts at step two forever
+ * because its own password was removed is a flow nobody keeps — along with everything behind the
+ * login it guards. The value comes from the environment, the one place a secret can live that is
+ * neither the customer's repository nor our database.
+ *
+ * Left as the PLACEHOLDER when nothing supplies it, rather than blanked. The replay then fails at
+ * the login form with `<redacted: supply at replay>` visible in the field, which names its own fix;
+ * an empty box fails identically and tells the reader nothing.
+ */
+export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean, field?: string): Record<string, unknown>;
+/**
+ * Capture an act into every in-flight recording, or do nothing when none is running.
+ *
+ * Every tool that drives the page must call this. reticle_act_and_wait did not, which is the tool
+ * the documented agent recipe drives with — so "record start -> drive -> record stop -> flow_save"
+ * saved a flow with zero steps.
+ */
+export declare function captureAct(recordings: {
+    active: () => string[];
+    capture: (step: RecordedStep, route?: string) => void;
+}, args: Record<string, unknown>, res: unknown, 
+/** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
+route?: string): void;
+/**
+ * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor
+ * priority mirrors synthesizeAnchor: a data-testid is the gold standard; failing that, the element's
+ * component identity / source location (the AUTO-ANCHOR) keeps the step STABLE instead of degrading to
+ * a volatile ref. Only when neither is available is the step ref-bound (in-session only).
+ */
+export declare function compileActStep(args: Record<string, unknown>, res: unknown): RecordedStep;
+/**
+ * Compile an reticle_act_sequence invocation, normalizing each sub-step through the SAME anchor
+ * priority a single act uses (see compileAnchorArgs) — not testid-or-nothing, which is what made
+ * every sequence unreplayable on an app without testids.
+ */
+export declare function compileSequenceStep(args: Record<string, unknown>, res: unknown): RecordedStep;
+interface ReplayStepResult {
+    tool: string;
+    ok: boolean;
+    error?: string;
+    note?: string;
+    /**
+     * Where this step lives, rendered, when the program is a composite.
+     *
+     * `mid#0 (invoked from top#0)`. Absent for a flat program, where the position in this array is
+     * already the answer and an address would be noise on every step of every replay.
+     */
+    at?: string;
+}
+/** Re-execute every step of a compiled program in order, stopping at the first failure. */
+export declare function replayProgram(session: Session, program: CompiledProgram, confirmDangerous?: boolean, 
+/**
+ * How to find an invoked document. Absent means this replayer cannot follow one — and an
+ * unfollowable invocation FAILS rather than being skipped, because a composite that reports green
+ * having silently not run a sub-journey is the false green this layer exists to prevent, arriving
+ * through the feature meant to strengthen it.
+ */
+resolve?: (name: string) => CompiledProgram | undefined, 
+/** The invocation chain that reached this program, nearest caller first. Empty at the top. */
+via?: readonly {
+    flow: string;
+    step: number;
+}[]): Promise<ReplayStepResult[]>;
+export {};