@reticlehq/server 3.8.2 → 3.10.0

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

@@ -11,30 +11,32 @@
  */
 import { z } from 'zod';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
-import { compileSequenceStep, pathOf, wroteSince } from '../../language/flows/replay.js';
+import { compileSequenceStep, pageOf, wroteSince } 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 { REPLAY_PROGRAM_VERSION, ReticleTool, Verified, VerifiedReason, checkIntent, } from '@reticlehq/core';
+import { REPLAY_PROGRAM_VERSION, ReticleCommand, ReticleTool, Verified, VerifiedReason, checkIntent, } 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 { asRecord, asString, isAbsenceDerived, isAdvisory } from '@reticlehq/core';
+import { couldNotEvaluate } from '@reticlehq/engine/evidence/verified.js';
 import { sessionIdFromArgs } from './tools-helpers.js';
-import { describeStepResult, runStepWithStaleRetry } from './act/act-sequence-retry.js';
+import { BURST_MAX_GAP_MS, describeStepResult, runStepWithStaleRetry, } from './act/act-sequence-retry.js';
 import { assertSequenceSteps } from './act/act-preflight.js';
 import { EnvelopeKey, sessionIdShape } from './tool-kit.js';
 import { takeStepShot } from '../../features/visual/step-shots.js';
-import { actCommand } from './act-tools.js';
+import { actCommand } from './act-command.js';
 import { PredicateSchema, waitForPredicate, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { DeviationMode, gradeSequence, JOURNEY_RECORDING, offerToKeep, } from './act/sequence-grade.js';
 import { stepEffect, appScope } 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 { hiddenTargetField } from './act/resolve-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';
-import { unreachableTargetNote } from './act/act-observation.js';
+import { diagnoseTimeout, unreachableTargetNote } from './act/act-observation.js';
 /**
  * The step's effect record, best-effort.
  *
@@ -54,20 +56,43 @@ function effectOf(session, since, expect) {
         return {};
     }
 }
+/**
+ * Why a step's check decided nothing, when the target was reachable.
+ *
+ * A read that could not be evaluated gets the sentence `reticle_act_and_wait` gives for it, with the
+ * same diagnosis of a timed-out read. The plan gave the raw error only, so it named no fix (#2204).
+ */
+function whyUndecided(verdict, session) {
+    if (true === verdict.observationLost) {
+        return `${verdict.failureReason ?? 'the observation was lost'} (the page left)`;
+    }
+    const missing = diagnoseTimeout(verdict.inconclusive, session);
+    if (missing !== undefined) {
+        return couldNotEvaluate(missing);
+    }
+    return verdict.failureReason ?? 'the predicate could not be read';
+}
+/** The step's action, for the sentence that names a step nobody could judge. */
+function actionOf(step) {
+    const action = asString(step['action']);
+    return action === undefined ? {} : { action };
+}
+/** One step's verdict and its reason. */
+function stepVerdict(check) {
+    if (check.held) {
+        return 0 < check.contradicted.length
+            ? { verified: Verified.NO, reason: VerifiedReason.CONTRADICTED }
+            : { verified: Verified.YES, reason: undefined };
+    }
+    if (check.undecided) {
+        const reason = true === check.unreachable ? VerifiedReason.INCONCLUSIVE : VerifiedReason.OBSERVATION_LOST;
+        return { verified: Verified.UNKNOWN, reason };
+    }
+    return { verified: Verified.NO, reason: VerifiedReason.ASSERTION_FAILED };
+}
 /** 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: true === check.unreachable
-                    ? VerifiedReason.INCONCLUSIVE
-                    : VerifiedReason.OBSERVATION_LOST,
-            }
-            : { verified: Verified.NO, reason: VerifiedReason.ASSERTION_FAILED };
+    const { verified, reason } = stepVerdict(check);
     const source = sourceOf(check.source);
     return {
         claim: describeWaitTarget(check.expect),
@@ -93,18 +118,6 @@ function journalStep(session, args, effect) {
         // 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.
- *
- * HOW TO PICK A GAP, because both edges are real and neither is guessable. It must outlast the
- * handler committing and dispatching its request, and undercut the response it is racing.
- * Measured against a superseded-filter race (the superseded query 700ms, the one replacing it 90ms):
- * at 0ms the first request was never issued at all, and at the ordinary settle (~500ms in a
- * throttled tab, where rAF never fires and the frame budget always times out) the two clicks
- * serialised and never overlapped. 50ms sat in the window. A different app needs a different
- * 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 = {
@@ -153,6 +166,8 @@ export const ACT_SEQUENCE_TOOL = {
         stopped_at: z.number().optional(),
         /** THE field to gate on: "yes" | "no" | "unknown" — see `because`. */
         verified: z.string().optional(),
+        /** The deciding clause of `verified`, from the same list as every other verdict. */
+        verifiedReason: z.string().optional(),
         because: z.string().optional(),
         /**
          * Present only when the plan PROVED something — see `offerToKeep`. A plan that declared nothing
@@ -181,10 +196,11 @@ export const ACT_SEQUENCE_TOOL = {
     handler: async (deps, args) => {
         const session = deps.sessions.resolve(sessionIdFromArgs(args));
         const paused = pausedShortCircuit(session);
-        if (paused !== undefined)
+        if (paused !== undefined) {
             return paused;
+        }
         const since = session.elapsed();
-        const pageBefore = pathOf(session.url);
+        const pageBefore = pageOf(session.url);
         session.beginAction(ReticleTool.ACT_SEQUENCE, asRecord(args));
         try {
             const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
@@ -226,13 +242,17 @@ export const ACT_SEQUENCE_TOOL = {
                     // Resolve `target` with the same helper reticle_act uses, then dispatch by ref. Passing
                     // the unresolved step through used to send `ref: undefined` and the browser blamed a
                     // stale empty ref — the caller went looking for a re-render instead of a missing locator.
+                    // Set by the resolve below, so the step row names a hidden match the step acted on.
+                    let hidden = {};
                     const outcome = await runStepWithStaleRetry(async () => {
                         const resolved = await resolveActTarget(session, step, perStepTimeout);
-                        if ('error' === resolved.kind)
+                        if ('error' === resolved.kind) {
                             return { ok: false, error: resolved.message };
+                        }
+                        hidden = hiddenTargetField(resolved);
                         // In burst mode every step carries a zero settle budget, so step N+1 is dispatched
                         // while step N is still in flight. That overlap IS the test — see `burst` above.
-                        return actCommand(deps, session, {
+                        return actCommand(deps, session, ReticleCommand.ACT, {
                             ref: resolved.ref,
                             action: step['action'],
                             // `sequenceStepArgs` reads a step's arguments flat OR nested — keep it, it is the
@@ -253,8 +273,9 @@ export const ACT_SEQUENCE_TOOL = {
                     if (burstGapMs !== undefined && i < inputSteps.length - 1) {
                         const elapsed = session.elapsed() - stepSince;
                         const remaining = burstGapMs - elapsed;
-                        if (remaining > 0)
+                        if (remaining > 0) {
                             await new Promise((r) => setTimeout(r, remaining));
+                        }
                     }
                     if (!outcome.ok) {
                         stalledAt = i;
@@ -266,6 +287,7 @@ export const ACT_SEQUENCE_TOOL = {
                         });
                         const error = outcome.error ?? 'the step could not be performed';
                         expectations.push({
+                            ...actionOf(step),
                             declared: undefined !== step['expect'],
                             held: false,
                             observed: error,
@@ -285,6 +307,7 @@ export const ACT_SEQUENCE_TOOL = {
                     const describe = () => ({
                         ...describeStepResult(step, asRecord(outcome.result)),
                         ...effectOf(session, stepSince, step['expect']),
+                        ...hidden,
                     });
                     const deciding = (step) => (step.contradictions ?? [])
                         .map((c) => c.kind)
@@ -302,8 +325,15 @@ export const ACT_SEQUENCE_TOOL = {
                     if (!parsed.success) {
                         const described = describe();
                         const contradicted = deciding(described);
+                        // What a quiet, undeclared plan is graded on — see gradeSequence.
+                        const doubted = (described.contradictions ?? [])
+                            .map((c) => c.kind)
+                            .filter((kind) => !isAdvisory(kind) && isAbsenceDerived(kind));
                         expectations.push({
+                            ...actionOf(step),
                             declared: false,
+                            settled: true === asRecord(outcome.result)['settled'],
+                            ...(0 === doubted.length ? {} : { doubted }),
                             ...(0 === contradicted.length ? {} : { contradicted }),
                             ...(unreachable === undefined ? {} : { undecided: unreachable }),
                         });
@@ -337,15 +367,12 @@ export const ACT_SEQUENCE_TOOL = {
                             assertion: verdict.assertion,
                         }));
                         expectations.push({
+                            ...actionOf(step),
                             declared: true,
                             held,
                             ...(undecided
                                 ? {
-                                    undecided: unreachable !== undefined
-                                        ? unreachable
-                                        : true === verdict.observationLost
-                                            ? `${verdict.failureReason ?? 'the observation was lost'} (the page left)`
-                                            : (verdict.failureReason ?? 'the predicate could not be read'),
+                                    undecided: unreachable ?? whyUndecided(verdict, session),
                                 }
                                 : {}),
                             ...disagreement,
@@ -364,8 +391,9 @@ export const ACT_SEQUENCE_TOOL = {
                         });
                         if (!held) {
                             stoppedAt ??= i;
-                            if (DeviationMode.HALT === onDeviation)
+                            if (DeviationMode.HALT === onDeviation) {
                                 break;
+                            }
                         }
                     }
                 }
@@ -393,11 +421,8 @@ 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 = DeviationMode.CONTINUE === onDeviation
-                ? (stalledAt ?? inputSteps.length)
-                : stoppedAt !== undefined
-                    ? stoppedAt + 1
-                    : (stalledAt ?? inputSteps.length);
+            const halted = DeviationMode.CONTINUE === onDeviation ? undefined : stoppedAt;
+            const completed = halted === undefined ? (stalledAt ?? inputSteps.length) : halted + 1;
             if (completed > 0) {
                 session.lastAct.markActed(since, undefined, undefined);
             }
@@ -417,8 +442,9 @@ export const ACT_SEQUENCE_TOOL = {
                 const compiled = (steps) => {
                     const step = compileSequenceStep({ ...args, steps }, { count: completed, steps: stepResults.slice(0, completed) });
                     // The journey sent a write request: saved `writes`, so a replay does not repeat it unasked.
-                    if (wroteSince(session, since))
+                    if (wroteSince(session, since)) {
                         step.writes = true;
+                    }
                     return step;
                 };
                 const recorded = compiled(proved);
@@ -426,9 +452,12 @@ export const ACT_SEQUENCE_TOOL = {
                 const onPage = (step) => pageBefore === undefined ? step : { ...step, page: pageBefore };
                 // Every step was on Reticle's own panel: nothing of the app's journey to record.
                 const onApp = asRecord(recorded.args)['steps'];
-                if (Array.isArray(onApp) && 0 < onApp.length)
-                    deps.recordings.capture(onPage(compiled(ran)), undefined, session.id, onPage(recorded));
-                deps.recordings.markEnded(pathOf(session.url), session.id);
+                // The route as act_and_wait gives it: the ambient tape is cut into journeys by route, and a
+                // step with none started a journey of its own and lost the act that came after it.
+                if (Array.isArray(onApp) && 0 < onApp.length) {
+                    deps.recordings.capture(onPage(compiled(ran)), pageBefore, session.id, onPage(recorded));
+                }
+                deps.recordings.markEnded(pageOf(session.url), session.id);
             }
             /*
              * The grade, and the coverage it is never allowed to hide.
@@ -440,6 +469,7 @@ export const ACT_SEQUENCE_TOOL = {
             const grade = gradeSequence(expectations, {
                 planned: inputSteps.length,
                 dispatched: completed > 0,
+                captureLost: session.lostSince(since),
             });
             // 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
@@ -464,6 +494,7 @@ export const ACT_SEQUENCE_TOOL = {
                 ...(stalledAt !== undefined ? { stalled_at: stalledAt } : {}),
                 ...(stoppedAt !== undefined ? { stopped_at: stoppedAt } : {}),
                 verified: grade.verified,
+                verifiedReason: grade.reason,
                 because: grade.because,
                 // Offered at the one moment the compiled program is in hand and free to keep.
                 ...(() => {

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

@@ -1,14 +1,2 @@
-import type { Session } from '../../portal/session/session.js';
-import { type ToolDef, type ToolDeps } from './tool-kit.js';
-/**
- * Single dispatch point for every ACT and ACT_SEQUENCE command.
- *
- * reticle_act, act_and_wait and act_sequence rewrite uploads here, once. The path resolves against
- * the session's project, not the daemon's folder, so a worktree uploads its own fixture (#1769).
- *
- * captureAct is called AFTER this, so the flow-recording captures the pre-rewrite args (the path
- * the agent actually wrote) rather than the base64 blob — replay would otherwise send 750 KiB of
- * base64 to the browser as if it were an inline content call.
- */
-export declare function actCommand(deps: ToolDeps, session: Session, actArgs: Record<string, unknown>, timeoutMs?: number): Promise<import('@reticlehq/core').CommandResult>;
+import { type ToolDef } from './tool-kit.js';
 export declare const ACT_TOOLS: ToolDef[];