@reticlehq/server 3.9.0 → 3.10.0

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

@@ -27,7 +27,7 @@
  *   - 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, urlForMatch, } from '@reticlehq/core';
+import { EventType, isDevToolingUrl, isForeignTraffic, neverAnswered, urlForMatch, } from '@reticlehq/core';
 /**
  * What a URL is matched against, as opposed to what is shown.
  *
@@ -81,10 +81,11 @@ const isForeign = (data, appOrigin, background) => isForeignTraffic(matchUrlOf(d
  * 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.
+ * The `settled` predicate asks the same question in `evalSettled`. Both read core's `neverAnswered`,
+ * which keeps the two answers one rule. It also covers a request whose page unloaded before its
+ * answer arrived (#1944).
  */
-const isDeparture = (data) => data['initiator'] === NetInitiator.NAVIGATION;
+const isDeparture = neverAnswered;
 /** How often to re-read the buffer. Short enough to return promptly, long enough not to spin. */
 const POLL_MS = 50;
 const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
@@ -98,21 +99,26 @@ const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
 export function inFlightRequestIds(events, appOrigin, background = []) {
     const settled = new Set();
     for (const e of events) {
-        if (e.type !== EventType.NET_REQUEST)
+        if (e.type !== EventType.NET_REQUEST) {
             continue;
+        }
         const id = idOf(e.data);
-        if (id !== undefined)
+        if (id !== undefined) {
             settled.add(id);
+        }
     }
     const open = [];
     for (const e of events) {
-        if (e.type !== EventType.NET_PENDING || isDevTooling(e.data) || isDeparture(e.data))
+        if (e.type !== EventType.NET_PENDING || isDevTooling(e.data) || isDeparture(e.data)) {
             continue;
-        if (isForeign(e.data, appOrigin, background))
+        }
+        if (isForeign(e.data, appOrigin, background)) {
             continue;
+        }
         const id = idOf(e.data);
-        if (id !== undefined && !settled.has(id) && !open.includes(id))
+        if (id !== undefined && !settled.has(id) && !open.includes(id)) {
             open.push(id);
+        }
     }
     return open;
 }
@@ -128,11 +134,13 @@ export function inFlightRequestLabels(events, appOrigin, background = []) {
     const open = new Set(inFlightRequestIds(events, appOrigin, background));
     const labels = [];
     for (const e of events) {
-        if (e.type !== EventType.NET_PENDING)
+        if (e.type !== EventType.NET_PENDING) {
             continue;
+        }
         const id = idOf(e.data);
-        if (id === undefined || !open.has(id))
+        if (id === undefined || !open.has(id)) {
             continue;
+        }
         open.delete(id); // one label per request, however many times its start was recorded
         const method = 'string' === typeof e.data['method'] ? e.data['method'] : 'request';
         const url = 'string' === typeof e.data['url'] ? e.data['url'] : 'an unreported url';
@@ -158,8 +166,9 @@ const MIN_REPEATS = 2;
 export function repeatedRequestLabels(events) {
     const counts = new Map();
     for (const e of events) {
-        if (e.type !== EventType.NET_REQUEST || isDevTooling(e.data))
+        if (e.type !== EventType.NET_REQUEST || isDevTooling(e.data)) {
             continue;
+        }
         const method = 'string' === typeof e.data['method'] ? e.data['method'] : 'request';
         const url = 'string' === typeof e.data['url'] ? e.data['url'] : 'an unreported url';
         const key = `${method} ${url}`;
@@ -182,17 +191,20 @@ export async function waitForInFlight(session, since, budgetMs, opts) {
     // The verdict's own scope: waiting on a request the verdict will not count is latency for nothing.
     const outstanding = () => inFlightRequestIds(session.eventsSince(since), session.url, session.background);
     let open = outstanding();
-    if (0 === open.length)
+    if (0 === open.length) {
         return { settled: true, stillInFlight: [] };
-    if (budgetMs <= 0)
+    }
+    if (budgetMs <= 0) {
         return { settled: false, stillInFlight: open };
+    }
     const deadline = session.elapsed() + budgetMs;
     while (session.elapsed() < deadline) {
         // Never overshoot the budget: the last sleep is trimmed to whatever is actually left.
         await opts.sleep(Math.min(POLL_MS, deadline - session.elapsed()));
         open = outstanding();
-        if (0 === open.length)
+        if (0 === open.length) {
             return { settled: true, stillInFlight: [] };
+        }
     }
     return { settled: false, stillInFlight: open };
 }

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

@@ -0,0 +1,23 @@
+/**
+ * The single dispatch point for every ACT and ACT_SEQUENCE command, extracted from
+ * act-tools.ts at the 1000-line cap.
+ *
+ * Attribution: this dispatch does NOT open its own window — the CALLER wraps it in
+ * `session.beginAction` / `finishAction` with the tool it serves (act, act_and_wait, act_sequence
+ * pass their own `command`), so the window covers the whole flow around the dispatch, not just
+ * the send.
+ */
+import { ReticleCommand } from '@reticlehq/core';
+import type { Session } from '../../portal/session/session.js';
+import 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, command: ReticleCommand, rawActArgs: Record<string, unknown>, timeoutMs?: number, realTried?: boolean): Promise<import('@reticlehq/core').CommandResult>;

package/dist/surface/tools/act-command.js

@@ -0,0 +1,50 @@
+/**
+ * The single dispatch point for every ACT and ACT_SEQUENCE command, extracted from
+ * act-tools.ts at the 1000-line cap.
+ *
+ * Attribution: this dispatch does NOT open its own window — the CALLER wraps it in
+ * `session.beginAction` / `finishAction` with the tool it serves (act, act_and_wait, act_sequence
+ * pass their own `command`), so the window covers the whole flow around the dispatch, not just
+ * the send.
+ */
+import { ActionType, ReticleCommand, asRecord, asString } from '@reticlehq/core';
+import { rewriteUploadArgs, tryRealInput, HOVER_NEEDS_POINTER_MSG } from './real-input-attempt.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { normalizeTypeSpelling } from './type-spelling.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 async function actCommand(deps, session, command, rawActArgs, timeoutMs, realTried = false) {
+    const actArgs = normalizeTypeSpelling(rawActArgs);
+    const rewritten = await rewriteUploadArgs({ fs: deps.fs, reticleRoot: sessionRoot(deps, session.id) }, 'string' === typeof actArgs['action'] ? actArgs['action'] : '', asRecord(actArgs['args']));
+    // Sequence and act_and_wait dispatch through here without the ACT handler's tryRealInput.
+    // A synthetic hover reports dispatched/settled while CSS :hover never applies — drive a real
+    // pointer when one is available, otherwise refuse rather than lie. A press on a lease takes its
+    // real keyboard, as reticle_act does: a synthetic Tab moves no focus.
+    const hover = ActionType.HOVER === actArgs['action'];
+    if (!realTried && (hover || ActionType.PRESS === actArgs['action'])) {
+        const ref = asString(actArgs['ref']);
+        if (hover && ref === undefined) {
+            throw new Error(HOVER_NEEDS_POINTER_MSG);
+        }
+        const action = hover ? ActionType.HOVER : ActionType.PRESS;
+        const real = await tryRealInput(deps, session, ref ?? '', action, actArgs);
+        if (hover && real.result === undefined) {
+            throw new Error(HOVER_NEEDS_POINTER_MSG);
+        }
+        if (real.result !== undefined) {
+            const result = { dispatched: true, settled: real.settled, ...asRecord(real.result) };
+            return { kind: 'command_result', id: action, ok: true, result };
+        }
+    }
+    const bridgeArgs = { ...actArgs, args: rewritten };
+    // What the acted element shows (test id, source) is noted in `Session.command`, Harness acts too.
+    return session.command(command, bridgeArgs, timeoutMs);
+}

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 = {
@@ -183,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'] : [];
@@ -228,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
@@ -255,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;
@@ -268,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,
@@ -287,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)
@@ -304,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 }),
                         });
@@ -339,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,
@@ -366,8 +391,9 @@ export const ACT_SEQUENCE_TOOL = {
                         });
                         if (!held) {
                             stoppedAt ??= i;
-                            if (DeviationMode.HALT === onDeviation)
+                            if (DeviationMode.HALT === onDeviation) {
                                 break;
+                            }
                         }
                     }
                 }
@@ -395,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);
             }
@@ -419,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);
@@ -428,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.
@@ -442,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

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