@reticlehq/server 3.5.0 → 3.7.0

package/dist/language/flows/replay-from-hud.d.ts

@@ -0,0 +1,20 @@
+import { ReticleCommand } from '@reticlehq/core';
+import type { FlowReplayResult } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/** The session a HUD replay reports to. Resolved per message: a replay usually reloads the page. */
+interface ProgressTarget {
+    pushNarration(text: string): void;
+    pushView(name: typeof ReticleCommand.FLOW_PROGRESS, args: object): void;
+}
+/** A human-facing one-liner for a panel replay verdict — ✓ passed / ⚠ drifted / ✗ errored / ? unverifiable. */
+export declare function replayVerdictLine(result: FlowReplayResult): string;
+/**
+ * Replay a saved flow because a person pressed ▶ in the HUD, with no agent involved.
+ *
+ * The chip they pressed shows the replay as it runs: a progress push after every step, and the
+ * verdict at the end, sent to whichever session holds the tab at that moment (a replay reloads the
+ * page, and the session object from before the reload no longer has a socket). The verdict also
+ * lands in the Agent Log as a line, where the "See the logs" link on the chip leads.
+ */
+export declare function replayFromHud(deps: ToolDeps, resolve: (sessionId: string) => ProgressTarget | undefined, sessionId: string, flowName: string): Promise<void>;
+export {};

package/dist/language/flows/replay-from-hud.js

@@ -0,0 +1,51 @@
+import { FlowProgressStatus, ReplayStatus, ReticleCommand } from '@reticlehq/core';
+import { replayAndLearn } from './flow-learning.js';
+/** A human-facing one-liner for a panel replay verdict — ✓ passed / ⚠ drifted / ✗ errored / ? unverifiable. */
+export function replayVerdictLine(result) {
+    if (result.status === ReplayStatus.OK)
+        return `✓ "${result.name}" passed`;
+    if (result.status === ReplayStatus.DRIFT)
+        return `⚠ "${result.name}" drifted — a step no longer matches`;
+    if (result.status === ReplayStatus.UNVERIFIABLE)
+        return `? "${result.name}" unverifiable — ${result.unverifiable?.reason ?? 'could not be graded'}`;
+    return `✗ "${result.name}" failed — ${result.error?.message ?? 'could not replay'}`;
+}
+/**
+ * Replay a saved flow because a person pressed ▶ in the HUD, with no agent involved.
+ *
+ * The chip they pressed shows the replay as it runs: a progress push after every step, and the
+ * verdict at the end, sent to whichever session holds the tab at that moment (a replay reloads the
+ * page, and the session object from before the reload no longer has a socket). The verdict also
+ * lands in the Agent Log as a line, where the "See the logs" link on the chip leads.
+ */
+export async function replayFromHud(deps, resolve, sessionId, flowName) {
+    const progress = (done, total, status) => resolve(sessionId)?.pushView(ReticleCommand.FLOW_PROGRESS, {
+        name: flowName,
+        done,
+        total,
+        status,
+    });
+    resolve(sessionId)?.pushNarration(`▶ Replaying "${flowName}"…`);
+    progress(0, 0, FlowProgressStatus.PLAYING);
+    let total = 0;
+    let done = 0;
+    try {
+        const result = await replayAndLearn(deps, {
+            flowName,
+            sessionId,
+            onStep: (stepsDone, stepsTotal) => {
+                done = stepsDone;
+                total = stepsTotal;
+                progress(done, total, FlowProgressStatus.PLAYING);
+            },
+        });
+        const passed = ReplayStatus.OK === result.status;
+        progress(passed ? total : done, total, passed ? FlowProgressStatus.PASSED : FlowProgressStatus.FAILED);
+        resolve(sessionId)?.pushNarration(replayVerdictLine(result));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        progress(done, total, FlowProgressStatus.FAILED);
+        resolve(sessionId)?.pushNarration(`✗ Replay "${flowName}" failed — ${message}`);
+    }
+}

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

@@ -35,6 +35,8 @@ export declare function replayActionArgs(value: unknown, confirmDangerous?: bool
  * a hash-routed app makes meaningless in the document location — see routeOfEvent.
  */
 export declare function pathOf(url: string | undefined): string | undefined;
+/** What a saved flow could not keep, and the fix. See RecordedStep.unkeptExpect. */
+export declare const UNKEPT_EXPECT: string;
 /**
  * Capture an act into every in-flight recording, or do nothing when none is running.
  *
@@ -44,21 +46,23 @@ export declare function pathOf(url: string | undefined): string | undefined;
  */
 export declare function captureAct(recordings: {
     active: () => string[];
-    capture: (step: RecordedStep, route?: string) => void;
+    capture: (step: RecordedStep, route?: string, session?: 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;
+route?: string, 
+/** The session that acted: only recordings it started take the step. */
+session?: string): void;
 /**
  * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
  * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
  * a regression test asserting something never once observed to hold because of the action. The
  * action itself is always recorded: it happened, and replay needs it to reach the next step.
  */
-export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined): void;
+export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined, session?: string): void;
 /** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
 export declare function captureAssertion(recordings: {
-    attachExpect: (expect: Predicate) => void;
-}, raw: unknown): void;
+    attachExpect: (expect: Predicate, session?: string) => void;
+}, raw: unknown, session?: 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

package/dist/language/flows/replay.js

@@ -1,8 +1,9 @@
-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';
 /**
  * The note attached when a testid resolves to multiple live elements (the first match is used).
@@ -12,6 +13,9 @@ import { asRecord, asString } from '@reticlehq/core';
 export function ambiguousTestidNote(value) {
     return `ambiguous testid '${value}', used first match`;
 }
+function ambiguousRoleNote(role, name) {
+    return `ambiguous ${role} named '${name}', used first match`;
+}
 /**
  * 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
@@ -40,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;
     }
@@ -87,6 +92,9 @@ export function pathOf(url) {
         return undefined;
     }
 }
+/** What a saved flow could not keep, and the fix. See RecordedStep.unkeptExpect. */
+export const UNKEPT_EXPECT = 'its proved `until` names something a saved flow cannot replay (a session ref such as e12): ' +
+    'name the element by testid, role and name, or text, and the check is kept';
 /**
  * Capture an act into every in-flight recording, or do nothing when none is running.
  *
@@ -96,7 +104,9 @@ export function pathOf(url) {
  */
 export function captureAct(recordings, args, res, 
 /** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
-route) {
+route, 
+/** The session that acted: only recordings it started take the step. */
+session) {
     // NO `active()` gate. `RecordingStore.capture` opens the AMBIENT tape on its first step, and that
     // branch was unreachable from here: this returned early whenever nothing was open, and the only
     // thing that opened anything was `reticle_record { action: "start" }`. So the comment on `capture`
@@ -111,15 +121,18 @@ route) {
     // success means — the large majority of calls carry one — and dropping it produced a flow graded
     // "assertion-free: it will pass even if the feature is broken", which is the regression-suite
     // story failing at its last step. See enforceableExpect below.
-    const expect = enforceableExpect(args['until'] ?? args['predicate']);
+    const declared = args['until'] ?? args['predicate'];
+    const expect = enforceableExpect(declared);
     if (expect !== undefined)
         step.expect = expect;
+    else if (declared !== undefined)
+        step.unkeptExpect = UNKEPT_EXPECT;
     if (route !== undefined)
         step.page = route;
     const intent = asString(args['intent'])?.trim();
     if (intent !== undefined && intent.length > 0)
         step.intent = intent;
-    recordings.capture(step, route);
+    recordings.capture(step, route, session);
 }
 /**
  * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
@@ -127,15 +140,15 @@ route) {
  * a regression test asserting something never once observed to hold because of the action. The
  * action itself is always recorded: it happened, and replay needs it to reach the next step.
  */
-export function captureVerdictedAct(recordings, args, res, route, verified) {
+export function captureVerdictedAct(recordings, args, res, route, verified, session) {
     const { until: _until, predicate: _predicate, ...unproved } = args;
-    captureAct(recordings, Verified.YES === verified ? args : unproved, res, route);
+    captureAct(recordings, Verified.YES === verified ? args : unproved, res, route, session);
 }
 /** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
-export function captureAssertion(recordings, raw) {
+export function captureAssertion(recordings, raw, session) {
     const expect = enforceableExpect(raw);
     if (expect !== undefined)
-        recordings.attachExpect(expect);
+        recordings.attachExpect(expect, session);
 }
 /**
  * A declared predicate, as a recorded expectation — or nothing.
@@ -164,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
@@ -207,6 +236,10 @@ function compileAnchorArgs(r, ref, action, actArgs) {
         };
         if (source !== undefined)
             roleArgs['source'] = source;
+        if ('number' === typeof r['nth'] && 'number' === typeof r['of']) {
+            roleArgs['nth'] = r['nth'];
+            roleArgs['of'] = r['of'];
+        }
         return { args: roleArgs, stable: true };
     }
     const component = asString(r['component']);
@@ -242,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.
@@ -275,11 +314,13 @@ async function resolveRef(session, step) {
         const result = await session.command(ReticleCommand.QUERY, query);
         if (!result.ok)
             throw new Error(result.error ?? 'query failed');
-        const ref = queryRefs(result)[0];
+        const refs = queryRefs(result);
+        const meant = refFor(step, refs);
+        const ref = meant ?? refs[0];
         if (ref === undefined) {
             throw new Error(`${value} named '${String(name)}' did not resolve in current page`);
         }
-        return { ref };
+        return meant === undefined ? { ref, note: ambiguousRoleNote(value, String(name)) } : { ref };
     }
     if (by === QueryBy.COMPONENT) {
         const component = asString(step.component);
@@ -350,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/suite/suite-flakes.js

@@ -26,6 +26,8 @@ import { FlakeStore } from '../stores/flake-store.js';
 export async function recordSuiteFlakes(fs, reticleRoot, runs) {
     const flakes = new FlakeStore(fs, reticleRoot);
     for (const { replay } of runs) {
+        if (replay.status === ReplayStatus.UNVERIFIABLE)
+            continue;
         await flakes.record(replay.name, ReplayStatus.OK === replay.status).catch(() => undefined);
     }
     return flakes.flakyFlows().catch(() => []);

package/dist/language/flows/suite-selection.d.ts

@@ -1,17 +1,4 @@
-/**
- * Which flows a suite run replays, resolved against the store.
- *
- * Shared by the MCP tool and the `reticle verify` command so the two cannot disagree about what a
- * selection means.
- *
- * Lives beside the flow store rather than under `suite/` on purpose: it needs `flowsForSession`, and
- * from `suite/` that import made `suite` and `flows` need EACH OTHER -- a mutual pair, which the
- * reach guard forbids growing because two directories that need each other cannot be read, moved or
- * tested apart. Here it adds no edge at all: `flows` reaching itself is nothing, and `cli -> flows`
- * already existed. The pure rule lives in core (`selectFlows`); this is the part that has to read
- * the files, because a label lives in one and `list` returns only names.
- */
-import { type ProjectId } from '@reticlehq/core';
+import type { ProjectTarget } from '../../memory/project/session-root.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /**
  * Resolve what a suite run should replay, and what it is holding back.
@@ -23,7 +10,7 @@ import type { ToolDeps } from '../../surface/tools/tool-kit.js';
  * would turn a corrupt file into missing coverage nobody is told about, and replay reports the parse
  * failure far better than a silent omission does.
  */
-export declare function resolveSuiteSelection(deps: ToolDeps, projectId: ProjectId | undefined, args: Record<string, unknown>): Promise<{
+export declare function resolveSuiteSelection(deps: ToolDeps, target: ProjectTarget, args: Record<string, unknown>): Promise<{
     run: string[];
     quarantined: string[];
     unmatched: string[];

package/dist/language/flows/suite-selection.js

@@ -11,7 +11,7 @@
  * already existed. The pure rule lives in core (`selectFlows`); this is the part that has to read
  * the files, because a label lives in one and `list` returns only names.
  */
-import { FLOW_FILE_VERSION, orderFlows, selectFlows, } from '@reticlehq/core';
+import { FLOW_FILE_VERSION, orderFlows, selectFlows } from '@reticlehq/core';
 import { flowsForSession } from './flow-store-for-session.js';
 /**
  * Resolve what a suite run should replay, and what it is holding back.
@@ -23,8 +23,9 @@ import { flowsForSession } from './flow-store-for-session.js';
  * would turn a corrupt file into missing coverage nobody is told about, and replay reports the parse
  * failure far better than a silent omission does.
  */
-export async function resolveSuiteSelection(deps, projectId, args) {
-    const store = flowsForSession(deps, projectId).flows;
+export async function resolveSuiteSelection(deps, target, args) {
+    const { projectId } = target;
+    const store = flowsForSession(deps, target).flows;
     const names = await store.list(projectId);
     const asStrings = (value) => Array.isArray(value) ? value.filter((v) => 'string' === typeof v) : [];
     const wantedNames = asStrings(args['names']);

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[];