@reticlehq/server 3.6.0 → 3.7.0

package/dist/surface/tools/read-tools.js

@@ -8,9 +8,13 @@ import { z } from 'zod';
 import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode, StorageArea, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { advanceMsSchema, depthSchema } from './args/numeric-bounds.js';
+import { aliasParam, aliasUsed } from './args/alias-args.js';
+/** `name` for `recordingName`: the spelling every other naming argument uses. */
+const RECORDING_NAME_ALIAS = z.string().optional().describe('Alias for `recordingName`.');
 import { proposeConsequences } from '../../judgement/oracles/propose-consequences.js';
 import { recordingBacktrackWarning, routesFromRecording, } from '../../language/flows/recording/recording-backtrack.js';
 import { replayProgram } from '../../language/flows/replay.js';
+import { redactRecordedSteps } from '../../language/flows/flows.js';
 import { diffLines } from '../../memory/project/baselines.js';
 import { selectPath, capDepth, projectComponentState } from '../../portal/session/state-select.js';
 import { costHint } from '../../portal/session/output-budget.js';
@@ -18,10 +22,10 @@ import { buildReactionReport, summarizeReaction } from '@reticlehq/engine/questi
 import { asNumber, asString, parseInteractive } from '@reticlehq/core';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../../portal/session/session-health.js';
-import { routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
+import { navigablePath, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 /** The route part of a session URL. A host belongs to the machine, not to the journey. */
 /**
- * The page a recording started on, as a NAVIGABLE path: pathname + hash.
+ * The page a recording started on, as a NAVIGABLE path: pathname + query + hash.
  *
  * The hash matters and the pathname alone is not enough. Under a hash router every page has the
  * document pathname `/`, so a recording made on `#/posts/12` stored `/`, the replay's start-path
@@ -32,8 +36,13 @@ function pathnameOf(url) {
     if (url === undefined)
         return undefined;
     const parts = routeOfUrl(url);
-    return parts === undefined ? undefined : `${parts.docPath}${parts.hash}`;
+    // The query too, minus Reticle's own params: `/products?scope=TOPWEAR` and `/products` are different
+    // pages, and replay compares the query when the flow recorded one (#1059), so dropping it here
+    // started the replay on the unfiltered page (#1411).
+    return parts === undefined ? undefined : navigablePath(parts);
 }
+/** What record-stop says when the span crossed a full-page load (#1411). */
+const RECORDING_CROSSED_RELOAD = 'The recording crossed a full-page load: the page it started on unloaded, so the reaction report and the proposed consequences cover only the page that loaded after it.';
 /**
  * What record-stop says about a step that compiled to no anchor at all.
  *
@@ -105,6 +114,9 @@ export const READ_TOOLS = [
             baseline: z
                 .string()
                 .describe('Baseline name to compare against. Call reticle_baseline{action:"list"} to get available names; names are created by reticle_baseline{action:"save"}.'),
+            // Read below as an alias, so declared: a merged tool refuses a key its chosen action does not
+            // declare, and `name` is what the saving sibling calls the same thing (#1536).
+            name: z.string().optional().describe('Alias for `baseline`.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -148,22 +160,30 @@ export const READ_TOOLS = [
         inputSchema: {
             recordingName: z
                 .string()
+                .optional()
                 .describe('Identifier for this recording. Pass the same name to reticle_record{action:"stop"} and reticle_replay.'),
+            name: RECORDING_NAME_ALIAS,
             ...sessionIdShape,
         },
         outputSchema: {
             recordingName: z.string(),
             since: z.number(),
+            normalized: z.array(z.string()).optional(),
         },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const name = asString(args['recordingName']) ?? 'default';
+            const normalized = aliasUsed(args, 'recordingName', ['name']);
+            const name = asString(aliasParam(args, 'recordingName', ['name'])['recordingName']) ?? 'default';
             const cursor = session.elapsed();
             // Where the journey begins, so a saved flow can navigate here before step 1 instead of
             // replaying from wherever the page happens to be. Pathname only: a host or port belongs to
             // the machine that recorded it, not to the journey.
-            deps.recordings.start(name, cursor, pathnameOf(session.url), session.id);
-            return Promise.resolve({ recordingName: name, since: cursor });
+            deps.recordings.start(name, cursor, pathnameOf(session.url), session.id, session.currentDocumentId);
+            return Promise.resolve({
+                recordingName: name,
+                since: cursor,
+                ...(0 === normalized.length ? {} : { normalized }),
+            });
         },
     },
     {
@@ -172,7 +192,9 @@ export const READ_TOOLS = [
         inputSchema: {
             recordingName: z
                 .string()
+                .optional()
                 .describe('Identifier of an active recording started with reticle_record{action:"start"}.'),
+            name: RECORDING_NAME_ALIAS,
             ...sessionIdShape,
         },
         outputSchema: {
@@ -189,7 +211,7 @@ export const READ_TOOLS = [
             // The recording actually RUNNING when there is exactly one, not the literal name `default` —
             // the same defaulting that made `annotate` report "no steps" against a recording full of them.
             // With several running, `default` stays the documented answer rather than a guess.
-            const name = resolveAnnotateTarget(asString(args['recordingName']), deps.recordings.active());
+            const name = resolveAnnotateTarget(asString(aliasParam(args, 'recordingName', ['name'])['recordingName']), deps.recordings.active());
             const rec = deps.recordings.stop(name);
             if (rec === undefined) {
                 const active = deps.recordings.active();
@@ -197,7 +219,18 @@ export const READ_TOOLS = [
                     ? `no active recording named '${name}' — none is in progress`
                     : `no active recording named '${name}'; in progress: ${active.map((r) => `'${r}'`).join(', ')}`);
             }
-            const events = session.eventsSince(rec.cursor);
+            // A full-page load mid-recording reconnects the page as a NEW Session, whose clock restarts
+            // below the cursor stored at start: the window came out negative and the span empty (#1411).
+            // Detected by the session that answers now not being the one that started it, or by the tab
+            // being on another document. A reconnect can keep the id, and its clock comes from another
+            // connection, so comparing clocks alone misses a reload once the new page has run past the
+            // cursor. The clock check stays for an SDK that stamps no document. The new page is then read
+            // from its start, and the warning says the report covers only it.
+            const crossedReload = (rec.session !== undefined && rec.session !== session.id) ||
+                (rec.document !== undefined && rec.document !== session.currentDocumentId) ||
+                session.elapsed() < rec.cursor;
+            const from = crossedReload ? 0 : rec.cursor;
+            const events = session.eventsSince(from);
             const routes = routesFromRecording(rec.startPath, events);
             const program = {
                 name,
@@ -208,7 +241,7 @@ export const READ_TOOLS = [
             };
             deps.recordings.saveCompiled(program);
             const unstable = rec.steps.filter((s) => !s.stable).length;
-            const report = buildReactionReport(events, session.elapsed() - rec.cursor);
+            const report = buildReactionReport(events, session.elapsed() - from);
             // Self-generating oracles: propose ranked mustHold from what the recorded window actually did.
             const proposedConsequences = proposeConsequences(events);
             const digest = summarizeReaction(report);
@@ -220,7 +253,7 @@ export const READ_TOOLS = [
             // same rule the capped diff arrays follow: a trim is never silent.
             const timeline = events.length > 0
                 ? {
-                    timeline_omitted: `${String(events.length)} event(s) were recorded and are not included here. Call reticle_observe { since: ${String(rec.cursor)} } for the raw timeline.`,
+                    timeline_omitted: `${String(events.length)} event(s) were recorded and are not included here. Call reticle_observe { since: ${String(from)} } for the raw timeline.`,
                 }
                 : {};
             const unanchored = 0 < unstable ? unanchoredWarning(unstable) : undefined;
@@ -230,10 +263,12 @@ export const READ_TOOLS = [
                 ? `${String(unkept)} step(s) proved a consequence this flow does not keep: ${UNKEPT_EXPECT}.`
                 : undefined;
             const backtrack = recordingBacktrackWarning(routes);
-            const warning = [unanchored, backtrack, lostChecks].filter((part) => part !== undefined);
+            const reloaded = crossedReload ? RECORDING_CROSSED_RELOAD : undefined;
+            const warning = [reloaded, unanchored, backtrack, lostChecks].filter((part) => part !== undefined);
             const body = {
                 recordingName: name,
-                program,
+                // Redacted as the saved flow is; the store above keeps the real values for replay.
+                program: { ...program, steps: redactRecordedSteps(program.steps) },
                 ...timeline,
                 ...(0 === warning.length ? {} : { warning: warning.join(' ') }),
                 ...(proposedConsequences.length > 0 ? { proposedConsequences } : {}),
@@ -251,7 +286,9 @@ export const READ_TOOLS = [
         inputSchema: {
             recordingName: z
                 .string()
+                .optional()
                 .describe('Name of a compiled recording (from reticle_record{action:"stop"}) to re-execute.'),
+            name: RECORDING_NAME_ALIAS,
             confirmDangerous: z
                 .boolean()
                 .optional()
@@ -269,7 +306,7 @@ export const READ_TOOLS = [
             })),
         },
         handler: async (deps, args) => {
-            const name = asString(args['recordingName']) ?? 'default';
+            const name = asString(aliasParam(args, 'recordingName', ['name'])['recordingName']) ?? 'default';
             const program = deps.recordings.getCompiled(name);
             if (program === undefined)
                 throw new Error(`no compiled recording named '${name}'`);
@@ -470,7 +507,21 @@ export const READ_TOOLS = [
             // Back-compat: an older browser returned the whole store; scope it here (may already be
             // size-truncated in transit for a very large store — that is the limitation this fix removes
             // for current SDKs).
-            const base = store !== undefined ? (root.stores ?? {})[store] : result;
+            const stores = root.stores;
+            const hasStore = store !== undefined &&
+                'object' === typeof stores &&
+                stores !== null &&
+                Object.prototype.hasOwnProperty.call(stores, store);
+            if (store !== undefined && path === undefined && !hasStore) {
+                return {
+                    store,
+                    found: false,
+                    value: null,
+                    availableKeys: names,
+                    storeNames: names,
+                };
+            }
+            const base = store !== undefined ? (stores ?? {})[store] : result;
             const selection = path !== undefined ? selectPath(base, path) : { found: true, value: base };
             const value = selection.found && depth !== undefined ? capDepth(selection.value, depth) : selection.value;
             return {

package/dist/surface/tools/reticle-result.d.ts

@@ -0,0 +1,120 @@
+import { Verified, VerdictStatus, type FlowReplayResult, type JournalAction, type SuiteVerdict } from '@reticlehq/core';
+import type { TimedReplay } from '../../judgement/runs/verification-sync.js';
+import type { ToolDeps } from './tool-kit.js';
+export declare const ResultWord: {
+    readonly PROVED: "proved";
+    readonly NOT_PROVED: "not proved";
+    readonly FAILED: "failed";
+};
+export type ResultWord = (typeof ResultWord)[keyof typeof ResultWord];
+/** The output field every result that ends a verification carries. */
+export declare const RESULT_FIELD = "reticleResult";
+export interface ResultFacts {
+    yes: number;
+    no: number;
+    undecided: number;
+    /** The journeys or flows the checks covered. */
+    covered?: readonly string[];
+    /** The journeys, flows or claims that did not hold. */
+    failed?: readonly string[];
+    flowsReplayed?: number;
+    /** Harness journeys answered by replaying saved flows (no model), and driven by the model. */
+    journeysReplayed?: number;
+    journeysDriven?: number;
+    wallMs?: number;
+    screenshots?: readonly string[];
+    /** From `platformLine`. */
+    platform: string;
+}
+/**
+ * Each fact once. The headline carries the check count, so the metrics do not repeat it; with one
+ * check the headline is the whole tally, so the per-word count line is left out.
+ */
+export declare function buildReticleResult(f: ResultFacts): string;
+/**
+ * The same block under a verdict decided above the counts: `reticle_verify { change }` can turn a
+ * green suite into `no` (a channel disagreed) or `unknown` (the flows do not cover the files).
+ */
+export declare function retitleResult(block: string, verified: Verified, because: string): string;
+/** The platform line when the key was refused: one true sentence, and the fix. */
+export declare const KEY_REFUSED_HEAD = "Not on the platform: ";
+/** The line for a key refused for no reason the platform named. */
+export declare const KEY_REFUSED_LINE: string;
+/** The platform line: where the run lives when linked, what linking adds when not. One line. */
+export declare function platformLine(root: string, env: Record<string, string | undefined>, runId?: string): string;
+/**
+ * The block for a replayed suite: the flows are the journeys, each flow's verdict one check, decided
+ * as the run decides it (`mapReplayToFlowResult`): a green a channel contradicted is undecided, as
+ * the suite's `unverifiable` status says, never held.
+ */
+export declare function suiteResult(root: string, verdict: SuiteVerdict, timed: readonly TimedReplay[], runId: string | undefined): string;
+/**
+ * `reticle_verify { change }`'s answer with the block on it. Its verdict is decided ABOVE the suite
+ * (uncovered files, a disagreeing channel), so the suite's own block is retitled with that verdict
+ * and moved to the top level: a nested block saying "proved" under an outer `no` is a false green.
+ */
+export declare function changeResult(root: string, out: unknown): unknown;
+/**
+ * The block for one replayed flow: one check, decided as the synced run decides it — a pass whose
+ * flow asserts nothing, or whose channels disagreed, is undecided, never held.
+ */
+export declare function replayResult(root: string, replay: FlowReplayResult, durationMs: number, runId: string | undefined): string;
+/** What a Harness drive's answer says about itself, as the block reads it. */
+export interface DriveFacts {
+    checks: {
+        held: number;
+        failed: number;
+        undecided: number;
+    };
+    /** The end-state goals the Harness graded itself. */
+    goals: readonly {
+        verified: string;
+    }[];
+    goalMet?: boolean;
+    journeys?: readonly {
+        title: string;
+        status: string;
+        by?: string;
+    }[];
+    runIds?: readonly string[];
+}
+/**
+ * The block for a Harness drive: its checks and its graded goals are the checks; a plan's journeys
+ * are what it covered, with how many were replayed and how many the model drove. Checks that held
+ * over a goal the drive did not reach are not proved, as the answer's own `proved` says.
+ */
+export declare function exploreResult(root: string, drive: DriveFacts): string;
+/**
+ * The block for a session ending: every verdict the journal holds is one check. `no-fault` (nothing
+ * declared) counts as undecided, never as held — a session that proved nothing must not read as one
+ * that proved something.
+ */
+export declare function sessionResult(deps: ToolDeps, sessionId: string, actions: readonly JournalAction[], wallMs: number | undefined, runId?: string): string;
+/**
+ * What an ending agent session reports: its own calls since its previous end in the tab, never the
+ * Harness drives the tab also holds, and the run they are kept under.
+ */
+export declare function endedAgentSession(sessionId: string, actions: readonly JournalAction[], at: number | undefined, claim?: VerdictStatus): {
+    actions: JournalAction[];
+    runId: string;
+    wallMs?: number;
+};
+/**
+ * The agent's own claim beside what grading the session's checks gave: the comparison a dashboard
+ * makes, said where the agent can read it. The claim never becomes the verdict.
+ */
+export declare function claimAgainstGrade(claim: VerdictStatus, actions: readonly JournalAction[]): {
+    claimed: VerdictStatus;
+    graded: VerdictStatus;
+    agrees: boolean;
+};
+/**
+ * A verdict tool's call, remembered until it settles, so a session that ends meanwhile counts it.
+ * An agent ended its session while a `reticle_assert { wait }` was still waiting: the end folded
+ * first ("proved · 1 of 1"), a PASS on the dashboard, and the failure landed in the next run.
+ */
+export declare function trackVerdict<T>(tool: string, call: Promise<T>): Promise<T>;
+/** Resolves once every verdict in flight now has been decided (and journaled). */
+export declare function verdictsSettled(): Promise<void>;
+/** The block as a field, or no field: the block is advice, never the reason a result throws. */
+export declare function resultField(build: () => string): Partial<Record<typeof RESULT_FIELD, string>>;