@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/act/settle-in-flight.js

@@ -27,7 +27,26 @@
  *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
  *     limit instead of an early exit.
  */
-import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic } from '@reticlehq/core';
+import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic, urlForMatch, } from '@reticlehq/core';
+/**
+ * What a URL is matched against, as opposed to what is shown.
+ *
+ * Redaction runs at emit time and rewrites a sensitive path segment in place: `/verify/refresh-token`
+ * becomes `/verify/[REDACTED]`, and the original survives only in `urlRaw`. A project that DECLARED
+ * `/verify/refresh-token` in `.reticle.json` `background` is matched with `String.includes`, so
+ * classifying on the displayed URL silently put the endpoint back into the in-flight count and held
+ * the settle window open — the exact defect this file exists to prevent, reached through the one
+ * field the classifier did not consult.
+ *
+ * The same division every other URL comparison in the product already uses (`urlContains`, `netCall`):
+ * match against `urlForMatch`, DISCLOSE `url`. The transcript keeps the redacted spelling.
+ */
+const matchUrlOf = (data) => {
+    // `urlForMatch` answers with the empty string when the event carries no URL at all, and every
+    // classifier below takes `undefined` to mean "nothing to judge". Fails OPEN either way.
+    const url = urlForMatch(data);
+    return 0 === url.length ? undefined : url;
+};
 /**
  * The dev toolchain talking about ITSELF is not the app finishing its work.
  *
@@ -36,7 +55,7 @@ import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic } from '@ret
  * deliberately disabled control — no state change, no storage change, zero application requests —
  * was graded on the strength of a Next webpack hot-update the same payload printed as ignored.
  */
-const isDevTooling = (data) => isDevToolingUrl('string' === typeof data['url'] ? data['url'] : undefined);
+const isDevTooling = (data) => isDevToolingUrl(matchUrlOf(data));
 /**
  * Somebody else's host is not the app finishing its work.
  *
@@ -55,12 +74,15 @@ const isDevTooling = (data) => isDevToolingUrl('string' === typeof data['url'] ?
  * SAME-ORIGIN background traffic is never guessed: nothing in a URL separates the app's telemetry
  * from the app's work. It is excluded only when the project DECLARED it (`background`).
  */
-const isForeign = (data, appOrigin, background) => isForeignTraffic('string' === typeof data['url'] ? data['url'] : undefined, appOrigin, background);
+const isForeign = (data, appOrigin, background) => isForeignTraffic(matchUrlOf(data), appOrigin, background);
 /**
  * A departure records where the browser was SENT, not a request whose result we will see — the
  * response is delivered to a document this session does not live into. It can never be matched by a
  * NET_REQUEST, so counting it as outstanding would mean no page containing an outbound link or a
  * download button ever settles again. See `NetInitiator.NAVIGATION`.
+ *
+ * The `settled` predicate asks the same question in `evalSettled`; it spells it against this same
+ * constant rather than against a string, which is what keeps the two answers one vocabulary.
  */
 const isDeparture = (data) => data['initiator'] === NetInitiator.NAVIGATION;
 /** How often to re-read the buffer. Short enough to return promptly, long enough not to spin. */

package/dist/surface/tools/act-sequence-tool.js

@@ -12,22 +12,28 @@
 import { z } from 'zod';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
 import { compileSequenceStep, pathOf } from '../../language/flows/replay.js';
+import { DEFAULT_SEQUENCE_STEP_TIMEOUT_MS } from '../../language/flows/flow-step-runners.js';
 import { sequenceStepArgs } from './act/act-preflight.js';
-import { ReticleTool } from '@reticlehq/core';
+import { REPLAY_PROGRAM_VERSION, ReticleTool, Verified, VerifiedReason, } from '@reticlehq/core';
 import { healthEnvelope } from '../../portal/session/session-health.js';
 import { pausedShortCircuit, pausedOutputShape, withControl, } from '../../portal/session/control-envelope.js';
 import { asRecord, isAbsenceDerived, isAdvisory } from '@reticlehq/core';
 import { sessionIdFromArgs } from './tools-helpers.js';
 import { describeStepResult, runStepWithStaleRetry } from './act/act-sequence-retry.js';
 import { assertSequenceSteps } from './act/act-preflight.js';
-import { sessionIdShape } from './tool-kit.js';
+import { EnvelopeKey, sessionIdShape } from './tool-kit.js';
+import { takeStepShot } from '../../features/visual/step-shots.js';
 import { actCommand } from './act-tools.js';
 import { PredicateSchema, waitForPredicate, } from '@reticlehq/engine/question/predicate/predicate.js';
-import { DeviationMode, gradeSequence, offerToKeep, } from './act/sequence-grade.js';
+import { DeviationMode, gradeSequence, JOURNEY_RECORDING, offerToKeep, } from './act/sequence-grade.js';
 import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
 // resolveActTarget moved out of act-tools into its own module on this branch; #706 was written
 // against the older layout where act-tools re-exported it.
 import { resolveActTarget } from './act/act-target.js';
+import { gradeOfPredicate } from './assert/assert-grade.js';
+import { describeWaitTarget } from '@reticlehq/engine/evidence/unsettled.js';
+import { sourceOf } from './tools-helpers.js';
+import { confirmedByDeclaration } from './act/act-danger.js';
 /**
  * The step's effect record, best-effort.
  *
@@ -45,6 +51,38 @@ function effectOf(session, since) {
         return {};
     }
 }
+/** The verdict effect for one step: the same rules act_and_wait applies to one action. */
+function stepVerdictEffect(check) {
+    const { verified, reason } = check.held
+        ? 0 < check.contradicted.length
+            ? { verified: Verified.NO, reason: VerifiedReason.CONTRADICTED }
+            : { verified: Verified.YES, reason: undefined }
+        : check.undecided
+            ? { verified: Verified.UNKNOWN, reason: VerifiedReason.OBSERVATION_LOST }
+            : { verified: Verified.NO, reason: VerifiedReason.ASSERTION_FAILED };
+    const source = sourceOf(check.source);
+    return {
+        claim: describeWaitTarget(check.expect),
+        verified,
+        ...(source === undefined ? {} : { source: `${source.file}:${String(source.line)}` }),
+        ...(check.expected === undefined ? {} : { expected: check.expected }),
+        ...(check.observed === undefined ? {} : { observed: check.observed }),
+        // Named in the step before the step ran — a check, not a rationalisation.
+        declaredBeforeActing: true,
+        grade: gradeOfPredicate(check.expect),
+        kind: check.expect.kind,
+        ...(reason === undefined ? {} : { reason }),
+    };
+}
+/** One step's check, journaled best-effort: the record must never fail the drive it records. */
+function journalStep(session, args, effect) {
+    try {
+        session.recordAction(ReticleTool.ACT_SEQUENCE, args, effect);
+    }
+    catch {
+        // ponytail: a session without a journal (a test double, journaling off) keeps no check.
+    }
+}
 /**
  * Ceiling for a burst gap. Past this it is not a burst, it is a paced walk.
  *
@@ -57,6 +95,8 @@ function effectOf(session, since) {
  * number: read its own slow endpoint.
  */
 const BURST_MAX_GAP_MS = 500;
+/** A step error that means nothing was acted on, or the page went away with the observation. */
+const UNJUDGED_STEP = /matched no element|no longer resolves|session disconnected|session (was )?replaced/i;
 export const ACT_SEQUENCE_TOOL = {
     name: ReticleTool.ACT_SEQUENCE,
     // The example is required for a core tool, and this one carries weight: the loop it replaces is
@@ -96,6 +136,8 @@ export const ACT_SEQUENCE_TOOL = {
         since: z.number(),
         dispatched: z.boolean(),
         completed: z.number(),
+        /** Number of steps included in the saved recording, when a recording was created. */
+        recorded: z.number(),
         stalled_at: z.number().optional(),
         /** Index of the step whose declared consequence did not hold, when one did not. */
         stopped_at: z.number().optional(),
@@ -137,8 +179,17 @@ export const ACT_SEQUENCE_TOOL = {
         try {
             const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
             assertSequenceSteps(inputSteps);
-            const perStepTimeout = 'number' === typeof args['timeout_ms'] ? args['timeout_ms'] : 8000;
+            const perStepTimeout = 'number' === typeof args['timeout_ms']
+                ? args['timeout_ms']
+                : DEFAULT_SEQUENCE_STEP_TIMEOUT_MS;
             const stepResults = [];
+            // Every step leaves a picture of the page as its outcome was decided — see step-shots.ts.
+            const pushStep = async (row) => {
+                stepResults.push({
+                    ...row,
+                    [EnvelopeKey.SCREENSHOT]: await takeStepShot(deps, session.id, ReticleTool.ACT),
+                });
+            };
             const expectations = [];
             // `true` means the default window; a number means that window exactly. 0 is legal and means
             // "no settle at all" — useful only when the app issues its request synchronously.
@@ -181,9 +232,9 @@ export const ACT_SEQUENCE_TOOL = {
                             // race rAF and return early anyway — a budget is a CEILING, not a floor, which is
                             // why an earlier attempt to pace with `settleMs` alone produced a 12ms step and
                             // no race at all.
-                            args: burstGapMs === undefined
-                                ? sequenceStepArgs(step)
-                                : { ...sequenceStepArgs(step), settleMs: 0 },
+                            // A step that names its dangerous control and declares its consequence is
+                            // confirmed by that declaration, as act_and_wait is — see confirmedByDeclaration.
+                            args: ((stepArgs) => burstGapMs === undefined ? stepArgs : { ...stepArgs, settleMs: 0 })(confirmedByDeclaration(sequenceStepArgs(step), step['target'], step['expect'] !== undefined)),
                         }, perStepTimeout);
                     }, session, since, perStepTimeout);
                     // Hold the gap BEFORE the next dispatch, measured from this step's own start so the
@@ -197,16 +248,19 @@ export const ACT_SEQUENCE_TOOL = {
                     }
                     if (!outcome.ok) {
                         stalledAt = i;
-                        stepResults.push({
+                        await pushStep({
                             ref: step['ref'],
                             action: step['action'],
                             dispatched: false,
                             error: outcome.error ?? 'step failed',
                         });
+                        const error = outcome.error ?? 'the step could not be performed';
                         expectations.push({
                             declared: undefined !== step['expect'],
                             held: false,
-                            observed: outcome.error ?? 'the step could not be performed',
+                            observed: error,
+                            // Nothing acted on, or the page gone with the observation: undecided, not a miss.
+                            ...(UNJUDGED_STEP.test(error) ? { undecided: error } : {}),
                         });
                         break;
                     }
@@ -218,10 +272,13 @@ export const ACT_SEQUENCE_TOOL = {
                      * cannot be read. Sharing the builder is what makes that true by construction rather than
                      * by two implementations agreeing today.
                      */
-                    const described = {
+                    const describe = () => ({
                         ...describeStepResult(step, asRecord(outcome.result)),
                         ...effectOf(session, stepSince),
-                    };
+                    });
+                    const deciding = (step) => (step.contradictions ?? [])
+                        .map((c) => c.kind)
+                        .filter((kind) => !isAdvisory(kind) && !isAbsenceDerived(kind));
                     /*
                      * Evaluate what the step SAID it would cause, in the window this step opened.
                      *
@@ -230,29 +287,61 @@ export const ACT_SEQUENCE_TOOL = {
                      * satisfy step four's assertion, which is a false green built out of correct parts.
                      */
                     const parsed = PredicateSchema.safeParse(step['expect']);
-                    const contradicted = (described.contradictions ?? [])
-                        .map((c) => c.kind)
-                        .filter((kind) => !isAdvisory(kind) && !isAbsenceDerived(kind));
-                    const disagreement = 0 === contradicted.length ? {} : { contradicted };
                     if (!parsed.success) {
-                        expectations.push({ declared: false, ...disagreement });
-                        stepResults.push(described);
+                        const described = describe();
+                        const contradicted = deciding(described);
+                        expectations.push({
+                            declared: false,
+                            ...(0 === contradicted.length ? {} : { contradicted }),
+                        });
+                        await pushStep(described);
                     }
                     else {
                         const verdict = await waitForPredicate(session, parsed.data, perStepTimeout, stepSince);
+                        // Described over the window the verdict was taken in, not the dispatch window before it:
+                        // a step that waited 1.5s for its declared 200 reported that request "still in flight"
+                        // beside `held: true`, a contradiction about a moment the verdict was not taken at.
+                        const described = describe();
+                        const contradicted = deciding(described);
+                        const disagreement = 0 === contradicted.length ? {} : { contradicted };
                         const held = true === verdict.pass;
+                        // A tab that went away (an external checkout page) or a predicate that could not be
+                        // read decided nothing: unknown, never a miss blamed on the app.
+                        const undecided = !held && (true === verdict.observationLost || verdict.inconclusive !== undefined);
+                        // One check per declared step, journaled as act_and_wait journals its own, so the
+                        // session's result, its run file and the dashboard all count it. See sequence-journal.ts.
+                        journalStep(session, { step: i, expect: step['expect'] }, stepVerdictEffect({
+                            expect: parsed.data,
+                            held,
+                            undecided,
+                            contradicted,
+                            expected: verdict.expected,
+                            observed: held ? undefined : (verdict.observed ?? verdict.failureReason),
+                            source: asRecord(outcome.result)['source'],
+                        }));
                         expectations.push({
                             declared: true,
                             held,
+                            ...(undecided
+                                ? {
+                                    undecided: true === verdict.observationLost
+                                        ? `${verdict.failureReason ?? 'the observation was lost'} (the page left)`
+                                        : (verdict.failureReason ?? 'the predicate could not be read'),
+                                }
+                                : {}),
                             ...disagreement,
                             ...(verdict.observed === undefined ? {} : { observed: verdict.observed }),
                             ...(verdict.expected === undefined ? {} : { expected: verdict.expected }),
                         });
-                        stepResults.push({
+                        await pushStep({
                             ...described,
                             expected: verdict.expected ?? true,
                             held,
                             ...(held ? {} : { observed: verdict.observed ?? verdict.failureReason }),
+                            // What would have held, on a case-only miss — the verdict stays a miss.
+                            ...(true === verdict.caseOnlyMiss
+                                ? { caseOnlyMiss: true, wouldHold: verdict.wouldHold }
+                                : {}),
                         });
                         if (!held) {
                             stoppedAt ??= i;
@@ -263,7 +352,7 @@ export const ACT_SEQUENCE_TOOL = {
                 }
                 catch (err) {
                     stalledAt = i;
-                    stepResults.push({
+                    await pushStep({
                         ref: step['ref'],
                         action: step['action'],
                         dispatched: null,
@@ -285,26 +374,32 @@ export const ACT_SEQUENCE_TOOL = {
              * The halted step counts: it WAS dispatched, and only the consequence it declared failed
              * afterwards. A stalled step never ran, which is why that index stays exclusive.
              */
-            const completed = stoppedAt !== undefined ? stoppedAt + 1 : (stalledAt ?? inputSteps.length);
+            const completed = DeviationMode.CONTINUE === onDeviation
+                ? (stalledAt ?? inputSteps.length)
+                : stoppedAt !== undefined
+                    ? stoppedAt + 1
+                    : (stalledAt ?? inputSteps.length);
             if (completed > 0) {
                 session.lastAct.markActed(since, undefined, undefined);
             }
             // Same as captureAct: no `active()` gate, so a sequence driven with nothing open still lands
-            // in the ambient tape. A stalled plan is still excluded — those steps never ran.
-            if (stalledAt === undefined) {
+            // in the ambient tape. A stalled plan keeps only the prefix whose steps actually ran.
+            let journey;
+            if (completed > 0) {
                 // A sub-step keeps its `expect` only if it held — same rule as act_and_wait, so a flow
                 // never replays an expectation that was never once observed to hold.
-                const proved = inputSteps.map((raw, i) => {
+                const proved = inputSteps.slice(0, completed).map((raw, i) => {
                     const step = asRecord(raw);
                     const { expect: _expect, ...rest } = step;
                     return true === expectations[i]?.held ? step : rest;
                 });
                 const recorded = compileSequenceStep({ ...args, steps: proved }, {
-                    count: inputSteps.length,
-                    steps: stepResults,
+                    count: completed,
+                    steps: stepResults.slice(0, completed),
                 });
-                deps.recordings.capture(pageBefore === undefined ? recorded : { ...recorded, page: pageBefore });
-                deps.recordings.markEnded(pathOf(session.url));
+                journey = recorded;
+                deps.recordings.capture(pageBefore === undefined ? recorded : { ...recorded, page: pageBefore }, undefined, session.id);
+                deps.recordings.markEnded(pathOf(session.url), session.id);
             }
             /*
              * The grade, and the coverage it is never allowed to hide.
@@ -317,12 +412,26 @@ export const ACT_SEQUENCE_TOOL = {
                 planned: inputSteps.length,
                 dispatched: completed > 0,
             });
-            const ran = stoppedAt ?? stalledAt ?? inputSteps.length;
-            const tail = inputSteps.slice(ran + (stoppedAt === undefined ? 0 : 1));
+            // The journey a `keep` offer names, held as a stopped recording so `reticle_flow_save
+            // { flowName: JOURNEY_RECORDING, saveAs }` saves exactly what was just driven. The offer used
+            // to name a save that refused with no recording, a dead end that cost a round trip.
+            if (journey !== undefined && offerToKeep(grade) !== undefined) {
+                deps.recordings.saveCompiled({
+                    name: JOURNEY_RECORDING,
+                    version: REPLAY_PROGRAM_VERSION,
+                    steps: [journey],
+                    ...(pageBefore === undefined ? {} : { startPath: pageBefore }),
+                });
+            }
+            const tailStart = DeviationMode.HALT === onDeviation && stoppedAt !== undefined
+                ? stoppedAt + 1
+                : (stalledAt ?? inputSteps.length);
+            const tail = inputSteps.slice(tailStart);
             return withControl(session, {
                 since,
                 dispatched: completed > 0,
                 completed,
+                recorded: journey === undefined ? 0 : completed,
                 ...(stalledAt !== undefined ? { stalled_at: stalledAt } : {}),
                 ...(stoppedAt !== undefined ? { stopped_at: stoppedAt } : {}),
                 verified: grade.verified,

package/dist/surface/tools/act-tools.d.ts

@@ -1,12 +1,3 @@
-/**
- * Action tools — reticle_act and reticle_act_and_wait. Split out of tools.ts to keep that file under
- * the line cap and assembled back into the tool list there via ...ACT_TOOLS; the native-input attempt
- * itself lives in real-input-attempt.ts for the same reason.
- *
- * `reticle_act_sequence` is a sibling file and is assembled by `tools.ts` directly. It used to be
- * re-exported through this list, which made a cycle out of nothing: that file needs `actCommand` from
- * here, and a registry is the right place to collect a definition from.
- */
 import type { Session } from '../../portal/session/session.js';
 import { type ToolDef, type ToolDeps } from './tool-kit.js';
 /**