@reticlehq/server 3.2.0 → 3.4.0

package/dist/surface/tools/act/proved-controls.js

@@ -0,0 +1,11 @@
+import { Verified } from '@reticlehq/core';
+/**
+ * Remember the control an act_and_wait PROVED, for the coverage ledger's `proved` level.
+ *
+ * Structural rather than `Session`, and optional, so a test stub that never proves anything need not
+ * implement it — the same reason `beginAction` is optional on the crawl session.
+ */
+export function noteProved(session, verified, actPayload) {
+    if (Verified.YES === verified)
+        session.recordProvedFrom?.(actPayload);
+}

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

@@ -35,6 +35,11 @@ export interface StepExpectation {
     /** What was seen instead, on a miss — the half of the answer a repair actually needs. */
     observed?: string;
     expected?: string;
+    /**
+     * Contradiction kinds positively observed in this step's window — deciding ones only, the same
+     * filter act_and_wait applies. A held step with one is a UI that advanced over a failed write.
+     */
+    contradicted?: readonly string[];
 }
 export interface SequenceGrade {
     verified: Verified;

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

@@ -27,7 +27,9 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     const total = Math.max(plan.planned, steps.length);
     const declaring = steps.filter((step) => step.declared);
     const declared = declaring.length;
-    const missed = declaring.find((step) => true !== step.held);
+    // `held: false` on an undeclared step means it could not be performed at all — the journey broke
+    // there whether or not anything was declared about it.
+    const missed = steps.find((step) => (step.declared ? true !== step.held : false === step.held));
     // A miss decides the grade before coverage does. How much of the plan declared nothing is
     // context on a red, never a softening of it.
     if (missed !== undefined) {
@@ -39,6 +41,17 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
             because: `a declared consequence did not hold — observed ${observed}`,
         };
     }
+    // Same rule as a single action: an observed contradiction outranks a consequence that held.
+    const contradictedAt = steps.findIndex((step) => (step.contradicted ?? []).length > 0);
+    if (contradictedAt >= 0) {
+        const kinds = (steps[contradictedAt]?.contradicted ?? []).join(', ');
+        return {
+            verified: Verified.NO,
+            declared,
+            total,
+            because: `step ${String(contradictedAt + 1)}: channels disagree about this action (${kinds}) even though it went on`,
+        };
+    }
     /*
      * `unknown` rather than `no-fault`, and the distinction is load-bearing.
      *
@@ -68,6 +81,24 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
                         : `nothing was dispatched, so none of the ${String(total)} step(s) ran — read the per-step \`error\` for the one that was refused, and fix that before adding an \`expect\``,
         };
     }
+    // A journey is proved at its END. Declaring only early steps checks that it started, and a yes
+    // there was the one a single act_and_wait on the last step would never have given.
+    if (steps.length < total) {
+        return {
+            verified: Verified.UNKNOWN,
+            declared,
+            total,
+            because: `only ${String(steps.length)} of ${String(total)} steps ran, so the journey never reached its end`,
+        };
+    }
+    if (true !== steps.at(-1)?.declared) {
+        return {
+            verified: Verified.UNKNOWN,
+            declared,
+            total,
+            because: `the last step, where the journey ends, declared nothing — give it an \`expect\` naming the end state (${String(declared)} of ${String(total)} steps declared one)`,
+        };
+    }
     return {
         verified: Verified.YES,
         declared,

package/dist/surface/tools/act/settle-in-flight.d.ts

@@ -34,6 +34,10 @@ export interface SettleSource {
         data: Record<string, unknown>;
     }[];
     elapsed(): number;
+    /** The page under test — what makes a request third-party. Absent: nothing is foreign. */
+    url?: string;
+    /** Same-origin endpoints the project declared as background. Absent: nothing is excluded. */
+    background?: readonly string[];
 }
 interface WaitOpts {
     /** Injected so the wait is testable without real time passing (rule: never call the clock inline). */
@@ -49,7 +53,7 @@ interface WaitOpts {
 export declare function inFlightRequestIds(events: readonly {
     type: string;
     data: Record<string, unknown>;
-}[]): string[];
+}[], appOrigin?: string, background?: readonly string[]): string[];
 /**
  * The same outstanding requests, as "METHOD url" — what an unsettled verdict has to be able to name.
  *
@@ -61,7 +65,7 @@ export declare function inFlightRequestIds(events: readonly {
 export declare function inFlightRequestLabels(events: readonly {
     type: string;
     data: Record<string, unknown>;
-}[]): string[];
+}[], appOrigin?: string, background?: readonly string[]): string[];
 /**
  * Endpoints called MORE THAN ONCE in this window, busiest first, as "METHOD url ×N".
  *

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 } from '@reticlehq/core';
+import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic } from '@reticlehq/core';
 /**
  * The dev toolchain talking about ITSELF is not the app finishing its work.
  *
@@ -37,6 +37,25 @@ import { EventType, NetInitiator, isDevToolingUrl } from '@reticlehq/core';
  * 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);
+/**
+ * Somebody else's host is not the app finishing its work.
+ *
+ * The comment above makes this argument for dev tooling and it holds identically here:
+ * `splitForeignTraffic` drops dev tooling AND third-party traffic, and this file dropped only the
+ * first — so the exclusion stayed cosmetic exactly where it decides a verdict, for the other half.
+ *
+ * Reported from the field repeatedly: an app embedding a wallet SDK that continuously POSTs
+ * telemetry to its vendor host never settles, so EVERY assertion on that app returns
+ * `unknown / outcome_pending` whatever the feature under test was. A third-party beacon cannot
+ * answer "has the app finished?", and nothing makes it stop, so waiting for it is waiting forever.
+ *
+ * Fails OPEN: with no known app origin nothing is foreign, because suppressing a request we cannot
+ * classify is how a verdict starts resting on evidence it discarded.
+ *
+ * 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);
 /**
  * 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
@@ -54,7 +73,7 @@ const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
  * the act cursor, so a response belonging to an earlier action can land inside it, and counting that
  * as progress would let unrelated traffic close the window early.
  */
-export function inFlightRequestIds(events) {
+export function inFlightRequestIds(events, appOrigin, background = []) {
     const settled = new Set();
     for (const e of events) {
         if (e.type !== EventType.NET_REQUEST)
@@ -67,6 +86,8 @@ export function inFlightRequestIds(events) {
     for (const e of events) {
         if (e.type !== EventType.NET_PENDING || isDevTooling(e.data) || isDeparture(e.data))
             continue;
+        if (isForeign(e.data, appOrigin, background))
+            continue;
         const id = idOf(e.data);
         if (id !== undefined && !settled.has(id) && !open.includes(id))
             open.push(id);
@@ -81,8 +102,8 @@ export function inFlightRequestIds(events) {
  * directly. Read off the NET_PENDING the window already holds, so this costs one pass over events
  * that are in hand.
  */
-export function inFlightRequestLabels(events) {
-    const open = new Set(inFlightRequestIds(events));
+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)
@@ -136,7 +157,9 @@ export function repeatedRequestLabels(events) {
  * timeout reaching the predicate, and a negative deadline must mean "stop", never "loop forever".
  */
 export async function waitForInFlight(session, since, budgetMs, opts) {
-    let open = inFlightRequestIds(session.eventsSince(since));
+    // 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)
         return { settled: true, stillInFlight: [] };
     if (budgetMs <= 0)
@@ -145,7 +168,7 @@ export async function waitForInFlight(session, since, budgetMs, opts) {
     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 = inFlightRequestIds(session.eventsSince(since));
+        open = outstanding();
         if (0 === open.length)
             return { settled: true, stillInFlight: [] };
     }

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

@@ -28,6 +28,13 @@ interface CapsuleSaveInputs {
      */
     root?: string | undefined;
 }
+/**
+ * What the act claimed would happen, in words: `route /settings`, `POST /v1/pay → 200`,
+ * `element "Issues"`. Read off the predicate the agent declared, because the causal links only name
+ * signals and requests: a failed route, element or text claim used to be filed as "declared
+ * consequence", which tells whoever reads the capsule nothing about what was expected.
+ */
+export declare function describeExpected(predicate: unknown): string | undefined;
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
 export declare function saveFailedAssertCapsule(inputs: CapsuleSaveInputs): Promise<string | undefined>;
 export {};

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

@@ -10,16 +10,59 @@
  * must never fail the run that found it.
  */
 import { ActionType, AnchorKind } from '@reticlehq/core';
-import { CapsuleStore, capsuleId, CAPSULE_VERSION } from '../../judgement/capsule/capsule-store.js';
+import { CapsuleStore, capsuleFingerprint, capsuleId, CAPSULE_VERSION, } from '../../judgement/capsule/capsule-store.js';
 import { ReticleTool } from '@reticlehq/core';
 import { asRecord, asString } from '@reticlehq/core';
 import { sessionRoot } from '../../memory/project/session-root.js';
+/**
+ * What the act claimed would happen, in words: `route /settings`, `POST /v1/pay → 200`,
+ * `element "Issues"`. Read off the predicate the agent declared, because the causal links only name
+ * signals and requests: a failed route, element or text claim used to be filed as "declared
+ * consequence", which tells whoever reads the capsule nothing about what was expected.
+ */
+export function describeExpected(predicate) {
+    const p = asRecord(predicate);
+    const kind = asString(p['kind']);
+    if (kind === undefined)
+        return undefined;
+    const all = (key, joiner) => {
+        const parts = (Array.isArray(p[key]) ? p[key] : [])
+            .map(describeExpected)
+            .filter((d) => d !== undefined);
+        return 0 === parts.length ? undefined : parts.join(joiner);
+    };
+    const q = asRecord(p['query']);
+    const named = asString(p['name']) ?? asString(q['name']) ?? asString(q['value']) ?? asString(q['testid']);
+    switch (kind) {
+        case 'route':
+            return `route ${asString(p['pathname']) ?? asString(p['contains']) ?? '?'}`;
+        case 'net': {
+            const status = 'number' === typeof p['status'] ? ` → ${String(p['status'])}` : '';
+            return `${asString(p['method']) ?? 'a'} ${asString(p['urlContains']) ?? 'request'}${status}`;
+        }
+        case 'signal':
+            return `signal ${asString(p['name']) ?? '?'}`;
+        case 'element':
+            return `${true === p['absent'] ? 'no ' : ''}element ${named === undefined ? '?' : `"${named}"`}`;
+        case 'text':
+            return `${true === p['absent'] ? 'no ' : ''}text "${asString(p['contains']) ?? '?'}"`;
+        case 'allOf':
+            return all('predicates', ' AND ');
+        case 'anyOf':
+            return all('predicates', ' OR ');
+        case 'not': {
+            const inner = describeExpected(p['predicate']);
+            return inner === undefined ? undefined : `not ${inner}`;
+        }
+        default:
+            return kind;
+    }
+}
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
 export async function saveFailedAssertCapsule(inputs) {
     const { deps, verdict, capsule, links, args, actResult, actedSource, root: given } = inputs;
     if (verdict.pass || capsule === undefined)
         return undefined;
-    const id = capsuleId(deps.now(), asString(args['ref']) ?? 'assert');
     const expectedText = links
         .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
         .join(' AND ');
@@ -33,26 +76,43 @@ export async function saveFailedAssertCapsule(inputs) {
     // verdict is already built, and losing the capsule must never also lose the verdict.
     if (root === undefined)
         return undefined;
-    const saved = await new CapsuleStore(deps.fs, root).save({
+    // Built BEFORE the id, because the id carries the fingerprint of this body — that is what lets a
+    // retry of the same broken step fold into the capsule already on disk instead of adding a file.
+    /*
+     * What this capsule is ABOUT, for its filename and its anchor.
+     *
+     * The testid is the element said in a name a human chose; `args.ref` is a volatile handle minted
+     * per session, meaningless an hour later and anywhere else. The anchor may still fall back to the
+     * ref, because the anchor has to address the element and the ref is what addressed it. The NAME
+     * must not: a capsule is durable, meant to be committed, and read by somebody who was not there.
+     */
+    const testid = asString(asRecord(actResult.result)['testid']);
+    const action = asString(args['action']) ?? ActionType.CLICK;
+    const body = {
         version: CAPSULE_VERSION,
-        id,
-        createdAt: deps.now(),
         origin: 'failed-assert',
-        expected: expectedText.length > 0 ? expectedText : 'declared consequence',
+        expected: describeExpected(args['until'] ?? args['predicate']) ??
+            (expectedText.length > 0 ? expectedText : 'declared consequence'),
         observed: capsule.firstDivergence?.observed ?? verdict.failureReason ?? 'not observed',
         steps: [
             {
                 tool: ReticleTool.ACT,
                 anchor: {
                     kind: AnchorKind.TESTID,
-                    value: asString(asRecord(actResult.result)['testid']) ?? asString(args['ref']) ?? '',
+                    value: testid ?? asString(args['ref']) ?? '',
                     // Carried so the saved capsule — which outlives this turn and becomes a regression flow
                     // when it goes green — still knows which file the failure came from.
                     ...(actedSource === undefined ? {} : { source: actedSource }),
                 },
-                action: (asString(args['action']) ?? ActionType.CLICK),
+                action: action,
             },
         ],
+    };
+    const id = capsuleId(deps.now(), testid ?? action, capsuleFingerprint(body));
+    const saved = await new CapsuleStore(deps.fs, root).save({
+        ...body,
+        id,
+        createdAt: deps.now(),
     });
     return saved ? id : undefined;
 }

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

@@ -11,12 +11,12 @@
  */
 import { z } from 'zod';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
-import { compileSequenceStep } from '../../language/flows/replay.js';
+import { compileSequenceStep, pathOf } from '../../language/flows/replay.js';
 import { sequenceStepArgs } from './act/act-preflight.js';
 import { ReticleTool } from '@reticlehq/core';
 import { healthEnvelope } from '../../portal/session/session-health.js';
 import { pausedShortCircuit, pausedOutputShape, withControl, } from '../../portal/session/control-envelope.js';
-import { asRecord } from '@reticlehq/core';
+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';
@@ -59,10 +59,9 @@ function effectOf(session, since) {
 const BURST_MAX_GAP_MS = 500;
 export const ACT_SEQUENCE_TOOL = {
     name: ReticleTool.ACT_SEQUENCE,
-    // The example is required for a core tool, and this one carries weight: the measured loop it
-    // replaces is literally a login form driven as three separate reticle_act calls (98 clicks and
-    // 21 fills inside looping sessions, 2026-08-10/11). Showing fill -> fill -> click is showing the
-    // exact shape an agent otherwise spends three round trips on.
+    // The example is required for a core tool, and this one carries weight: the loop it replaces is
+    // a login form driven as three separate reticle_act calls. Showing fill -> fill -> click is showing
+    // the exact shape an agent otherwise spends three round trips on.
     example: {
         steps: [
             { ref: 'e12', action: 'fill', args: { value: 'a@b.com' } },
@@ -133,6 +132,7 @@ export const ACT_SEQUENCE_TOOL = {
         if (paused !== undefined)
             return paused;
         const since = session.elapsed();
+        const pageBefore = pathOf(session.url);
         session.beginAction(ReticleTool.ACT_SEQUENCE, asRecord(args));
         try {
             const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
@@ -230,8 +230,12 @@ 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 });
+                        expectations.push({ declared: false, ...disagreement });
                         stepResults.push(described);
                     }
                     else {
@@ -240,6 +244,7 @@ export const ACT_SEQUENCE_TOOL = {
                         expectations.push({
                             declared: true,
                             held,
+                            ...disagreement,
                             ...(verdict.observed === undefined ? {} : { observed: verdict.observed }),
                             ...(verdict.expected === undefined ? {} : { expected: verdict.expected }),
                         });
@@ -287,7 +292,19 @@ export const ACT_SEQUENCE_TOOL = {
             // 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) {
-                deps.recordings.capture(compileSequenceStep(args, { count: inputSteps.length, steps: stepResults }));
+                // 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 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,
+                });
+                deps.recordings.capture(pageBefore === undefined ? recorded : { ...recorded, page: pageBefore });
+                deps.recordings.markEnded(pathOf(session.url));
             }
             /*
              * The grade, and the coverage it is never allowed to hide.