@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,79 @@
+/**
+ * What a planned sequence proved, from what its steps DECLARED.
+ *
+ * A batch that acts without declaring a consequence is the fastest way yet built to prove nothing —
+ * it drives a whole journey in one round trip and every step reports `ok`, which reads as success and
+ * is not. The engine already refuses this shape for a single action (`no-fault`: "nothing was declared
+ * to prove -- this is not verification"); a plan has to refuse it too, or batching becomes a false
+ * green with a speed improvement attached.
+ *
+ * Pure on purpose: the decision is separable from the driving, so it is tested without a browser,
+ * exactly as `runVerify` is separable from the connection it runs over.
+ *
+ * The coverage is never averaged away. A plan of twelve steps where three declared and all three held
+ * is verified FOR THOSE THREE and silent about nine, and `because` says so — reporting it as "25%
+ * verified" would be the arithmetic that hides the nine.
+ */
+import { Verified } from '@reticlehq/core';
+/**
+ * What to do when a step's declared consequence does not hold.
+ *
+ * `halt` is the default because a dependent chain is the common case: continuing past a broken login
+ * produces a run of meaningless failures that bury the one real finding. `continue` is right for a
+ * sweep of independent controls, where stopping at the first would hide the other thirteen.
+ */
+export declare const DeviationMode: {
+    readonly HALT: "halt";
+    readonly CONTINUE: "continue";
+};
+export type DeviationMode = (typeof DeviationMode)[keyof typeof DeviationMode];
+/** What one step's declared consequence produced. `declared: false` means the step asserted nothing. */
+export interface StepExpectation {
+    declared: boolean;
+    /** Whether the declared consequence held. Absent when nothing was declared. */
+    held?: boolean;
+    /** What was seen instead, on a miss — the half of the answer a repair actually needs. */
+    observed?: string;
+    expected?: string;
+}
+export interface SequenceGrade {
+    verified: Verified;
+    /** Steps that declared a consequence. */
+    declared: number;
+    total: number;
+    /** One sentence naming the deciding evidence — a miss first, coverage otherwise. */
+    because: string;
+}
+/**
+ * The plan this grade is about, which is not the same as the steps that were reached.
+ *
+ * `total` used to be `steps.length` — the steps that got far enough to carry an expectation — while
+ * the caller's `coverage.total` counted the plan. A two-step sequence refused at step one answered
+ * "all 1 step(s) declared nothing" beside `coverage: { total: 2 }`: two numbers for one plan.
+ */
+interface SequencePlan {
+    /** How many steps the caller asked for. */
+    readonly planned: number;
+    /** Whether anything actually reached the page. */
+    readonly dispatched: boolean;
+}
+export declare function gradeSequence(steps: readonly StepExpectation[], plan?: SequencePlan): SequenceGrade;
+/**
+ * The offer to keep a driven plan as a flow, or nothing.
+ *
+ * A completed sequence is already a compiled program — anchors resolved, actions ordered, and, where
+ * a step declared one, a consequence. It is a flow minus somebody deciding to save it, and the agent
+ * holds the whole thing at the moment it is cheapest to keep.
+ *
+ * The gate is the part that matters: **no consequence, no save.** A plan where every step drove and
+ * none declared replays green whatever the app does, so offering to keep it would manufacture
+ * regression coverage that cannot go red — the same false green `unverifiable` names on the suite,
+ * one step earlier. A plan whose consequence did NOT hold is not offered either: that journey is the
+ * bug report, not the regression test, and saving it now would pin the broken behaviour as expected.
+ *
+ * The coverage travels in the sentence for the same reason it travels on the verdict. Keeping a
+ * two-of-twelve plan as a regression flow is a reasonable thing to do and a bad thing to do without
+ * knowing it.
+ */
+export declare function offerToKeep(grade: SequenceGrade): string | undefined;
+export {};

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

@@ -0,0 +1,104 @@
+/**
+ * What a planned sequence proved, from what its steps DECLARED.
+ *
+ * A batch that acts without declaring a consequence is the fastest way yet built to prove nothing —
+ * it drives a whole journey in one round trip and every step reports `ok`, which reads as success and
+ * is not. The engine already refuses this shape for a single action (`no-fault`: "nothing was declared
+ * to prove -- this is not verification"); a plan has to refuse it too, or batching becomes a false
+ * green with a speed improvement attached.
+ *
+ * Pure on purpose: the decision is separable from the driving, so it is tested without a browser,
+ * exactly as `runVerify` is separable from the connection it runs over.
+ *
+ * The coverage is never averaged away. A plan of twelve steps where three declared and all three held
+ * is verified FOR THOSE THREE and silent about nine, and `because` says so — reporting it as "25%
+ * verified" would be the arithmetic that hides the nine.
+ */
+import { Verified } from '@reticlehq/core';
+/**
+ * What to do when a step's declared consequence does not hold.
+ *
+ * `halt` is the default because a dependent chain is the common case: continuing past a broken login
+ * produces a run of meaningless failures that bury the one real finding. `continue` is right for a
+ * sweep of independent controls, where stopping at the first would hide the other thirteen.
+ */
+export const DeviationMode = { HALT: 'halt', CONTINUE: 'continue' };
+export function gradeSequence(steps, plan = { planned: steps.length, dispatched: true }) {
+    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);
+    // 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) {
+        const observed = missed.observed ?? 'nothing that matched';
+        return {
+            verified: Verified.NO,
+            declared,
+            total,
+            because: `a declared consequence did not hold — observed ${observed}`,
+        };
+    }
+    /*
+     * `unknown` rather than `no-fault`, and the distinction is load-bearing.
+     *
+     * "Nothing was declared" is what `no-fault` means for a single action -- but the engine only says
+     * it over a SETTLED window, because no-fault claims the whole window was observed. Nothing on
+     * this path observes settledness: the caller tracks dispatch and stalls, never settle. Saying
+     * `no-fault` here would claim evidence nobody collected, in the one place this product cannot
+     * afford to overclaim.
+     *
+     * So the enum stays conservative and the SENTENCE carries the whole answer: it names declaring a
+     * consequence as the next move, which is what an agent reading `no-fault` would have done.
+     * Upgrading means plumbing `settled` from the act results through `SequencePlan`.
+     */
+    if (0 === declared) {
+        return {
+            verified: Verified.UNKNOWN,
+            declared,
+            total,
+            because: 0 === total
+                ? 'the plan had no steps, so nothing was driven and nothing was proved'
+                : // "the app was driven" was said unconditionally, including on a call whose own
+                    // `dispatched` was false in the same object. A step refused before dispatch is a
+                    // malformed call, and telling its author to add an `expect` sends them at the wrong
+                    // thing entirely.
+                    plan.dispatched
+                        ? `all ${String(total)} step(s) declared nothing, so the app was driven but not verified — give each step an \`expect\` naming the consequence it causes`
+                        : `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\``,
+        };
+    }
+    return {
+        verified: Verified.YES,
+        declared,
+        total,
+        because: declared === total
+            ? `every declared consequence held (${String(declared)} of ${String(total)} steps)`
+            : `every declared consequence held, but only ${String(declared)} of ${String(total)} steps declared one — the rest were driven, not verified`,
+    };
+}
+/**
+ * The offer to keep a driven plan as a flow, or nothing.
+ *
+ * A completed sequence is already a compiled program — anchors resolved, actions ordered, and, where
+ * a step declared one, a consequence. It is a flow minus somebody deciding to save it, and the agent
+ * holds the whole thing at the moment it is cheapest to keep.
+ *
+ * The gate is the part that matters: **no consequence, no save.** A plan where every step drove and
+ * none declared replays green whatever the app does, so offering to keep it would manufacture
+ * regression coverage that cannot go red — the same false green `unverifiable` names on the suite,
+ * one step earlier. A plan whose consequence did NOT hold is not offered either: that journey is the
+ * bug report, not the regression test, and saving it now would pin the broken behaviour as expected.
+ *
+ * The coverage travels in the sentence for the same reason it travels on the verdict. Keeping a
+ * two-of-twelve plan as a regression flow is a reasonable thing to do and a bad thing to do without
+ * knowing it.
+ */
+export function offerToKeep(grade) {
+    if (grade.verified !== Verified.YES || 0 === grade.declared)
+        return undefined;
+    return (`this plan proved something (${String(grade.declared)} of ${String(grade.total)} steps declared a ` +
+        'consequence and every one held) — keep it as a regression flow with ' +
+        'reticle_flow_save { saveAs: "<name>" }, and the steps that declared nothing will replay ' +
+        'without proving anything, exactly as they did here');
+}

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

@@ -0,0 +1,33 @@
+import type { ExpectedLink } from '../../judgement/capsule/divergence.js';
+import type { DivergenceCapsule } from '../../judgement/capsule/capsule.js';
+import type { ToolDeps } from './tool-kit.js';
+interface CapsuleSaveInputs {
+    deps: ToolDeps;
+    verdict: {
+        pass: boolean;
+        failureReason?: string;
+    };
+    capsule?: DivergenceCapsule | undefined;
+    links: readonly ExpectedLink[];
+    args: Record<string, unknown>;
+    actResult: {
+        result?: unknown;
+    };
+    actedSource?: {
+        file: string;
+        line: number;
+    };
+    /**
+     * The `.reticle` this capsule belongs in, from the session the act ACTUALLY drove.
+     *
+     * Passed in rather than re-resolved here, because re-resolving loses twice: `args.sessionId` is
+     * frequently absent, and `sessions.resolve(undefined)` throws whenever more than one tab is
+     * connected — which is precisely the multi-project case this routing exists for, so it failed in
+     * exactly the situation it was written to fix. The caller also knows about a session the act
+     * FOLLOWED through a navigation; this file cannot.
+     */
+    root?: 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

@@ -0,0 +1,79 @@
+/**
+ * Persist a failed assertion as a replayable fail-to-pass capsule.
+ *
+ * : a red assertion is the ONE moment the evidence explaining it is in hand. Persist it as a
+        // replayable fail-to-pass capsule so the bug survives the turn — and becomes a regression flow
+        // the moment it goes green. Best-effort: capturing evidence must never fail the run that found it.
+ *
+ * Split out of act-tools.ts when it crossed the 600-line cap. The seam is real: this is the only
+ * part of the act path that writes to disk, and it is best-effort by design — capturing evidence
+ * 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 { ReticleTool } from '@reticlehq/core';
+import { asRecord, asString } from '@reticlehq/core';
+import { sessionRoot } from '../../memory/project/session-root.js';
+/** 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 ');
+    // The capsule belongs to the project whose app just failed, not to wherever the daemon stands.
+    // Same rule and same resolver as every other artifact: a capsule written into a sibling repo is
+    // evidence filed against a codebase that did not produce it, and it outlives the turn.
+    // The caller's answer wins; the resolver is the fallback for callers that have no session.
+    const root = given ?? bestEffortRoot(deps, asString(args['sessionId']));
+    // No directory this capsule could honestly belong to, so it is not filed. The two things this
+    // must not do are write it somewhere arbitrary and throw: the assertion has already failed, the
+    // 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({
+        version: CAPSULE_VERSION,
+        id,
+        createdAt: deps.now(),
+        origin: 'failed-assert',
+        expected: 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']) ?? '',
+                    // 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),
+            },
+        ],
+    });
+    return saved ? id : undefined;
+}
+/**
+ * Where this capsule goes, or nothing — never a throw and never somebody else's checkout.
+ *
+ * `sessionRoot` refuses a `sessionId` that names no session, because for a tool the agent CALLED
+ * the alternative is silently writing into the daemon's own project. Here the caller is not a tool
+ * the agent called: it is the evidence capture hanging off a verdict that has already been decided,
+ * and on this path a refusal would convert a red assertion into a tool error. Both of the answers
+ * that refusal exists to prevent are still prevented — nothing is written, and nothing is written
+ * to the wrong root — by declining to file the capsule at all.
+ *
+ * Reachable only when the act's own session AND its navigation successor are gone by the time the
+ * verdict lands, since `act_and_wait` passes the root of the session it actually drove.
+ */
+function bestEffortRoot(deps, sessionId) {
+    try {
+        return sessionRoot(deps, sessionId);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { ToolDef } from './tool-kit.js';
+/**
+ * `reticle_act`, absorbing `reticle_act_sequence`, routed on SHAPE rather than on a discriminator.
+ *
+ * Every other merge in this package dispatches on an `action` field. This one cannot: `reticle_act`
+ * already owns `action`, and it means the DOM action (click/fill/press). Adding a dispatch enum of
+ * the same name silently replaces it and makes the whole family unroutable — see
+ * `refuseDiscriminatorCollision`, which now refuses that at build time because this is the merge
+ * that found it.
+ *
+ * So the routing is the one thing the two calls genuinely disagree about: a sequence has `steps`,
+ * a single action does not. That is not a heuristic — `steps` is required on one and absent from the
+ * other's schema, so the two shapes are disjoint by construction.
+ *
+ * `act_and_wait` is deliberately NOT part of this. It is the only acting tool that names the expected
+ * consequence BEFORE the action and returns a verdict, and folding it in here would turn the proof
+ * into an optional parameter. A forgotten tool name is an error; a forgotten parameter is a silent
+ * non-verdict, which is the shape of the only false green this repository has ever measured.
+ */
+export declare function mergeActWithSequence(act: ToolDef, sequence: ToolDef): ToolDef;

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

@@ -0,0 +1,53 @@
+/**
+ * `reticle_act`, absorbing `reticle_act_sequence`, routed on SHAPE rather than on a discriminator.
+ *
+ * Every other merge in this package dispatches on an `action` field. This one cannot: `reticle_act`
+ * already owns `action`, and it means the DOM action (click/fill/press). Adding a dispatch enum of
+ * the same name silently replaces it and makes the whole family unroutable — see
+ * `refuseDiscriminatorCollision`, which now refuses that at build time because this is the merge
+ * that found it.
+ *
+ * So the routing is the one thing the two calls genuinely disagree about: a sequence has `steps`,
+ * a single action does not. That is not a heuristic — `steps` is required on one and absent from the
+ * other's schema, so the two shapes are disjoint by construction.
+ *
+ * `act_and_wait` is deliberately NOT part of this. It is the only acting tool that names the expected
+ * consequence BEFORE the action and returns a verdict, and folding it in here would turn the proof
+ * into an optional parameter. A forgotten tool name is an error; a forgotten parameter is a silent
+ * non-verdict, which is the shape of the only false green this repository has ever measured.
+ */
+export function mergeActWithSequence(act, sequence) {
+    const optional = (shape) => {
+        const out = {};
+        for (const [key, schema] of Object.entries(shape)) {
+            out[key] = schema.isOptional() ? schema : schema.optional();
+        }
+        return out;
+    };
+    return {
+        name: act.name,
+        description: `${act.description}\n\nSEQUENCE: pass \`steps\` instead of \`ref\`/\`action\` to run several ` +
+            `actions in one call, which is one round trip rather than one per step. ${sequence.description}`,
+        ...(act.example === undefined ? {} : { example: act.example }),
+        inputSchema: { ...optional(act.inputSchema), ...optional(sequence.inputSchema) },
+        handler: (deps, args) => {
+            // `steps` is required by the sequence schema and absent from act's, so presence is the whole
+            // question. An empty array still routes to the sequence handler, which already refuses it and
+            // says why — better than act's "no ref" complaint about a call that named no ref on purpose.
+            const batched = Array.isArray(args['steps']);
+            const single = args['ref'] !== undefined || args['target'] !== undefined;
+            // Both halves named at once is AMBIGUOUS, and routing on `steps` would silently run the
+            // sequence and drop the single action the caller also wrote. Merging made this reachable:
+            // before it, the two calls were two tools and the question could not be asked. Refused rather
+            // than guessed, for the reason every ambiguity in this codebase is refused — a guess that
+            // happens to be right teaches the caller that the call was right.
+            if (batched && single) {
+                return Promise.resolve({
+                    error: 'ambiguous call: `steps` runs a sequence and `ref`/`target` runs one action, and this ' +
+                        'names both. Send `steps` on its own to batch, or `ref` + `action` on its own for one.',
+                });
+            }
+            return batched ? sequence.handler(deps, args) : act.handler(deps, args);
+        },
+    };
+}