@reticlehq/server 2.14.0 → 3.2.0

package/dist/setup/setup-options.js

@@ -1,68 +0,0 @@
-/**
- * The contract between the agent and the script.
- *
- * Everything setup does is deterministic except for the handful of things that require reading a
- * repository and a human's request and understanding both. Those are exactly what an agent is good
- * at and code is not, so they arrive here as ARGUMENTS rather than as steps somebody walks through:
- * the agent decides, the script executes, and neither does the other's job.
- *
- * What only an agent can know, and therefore what belongs in this type:
- *
- *   --flow      which journey proves the thing the user cares about. Code can enumerate buttons; it
- *               cannot know that checkout matters and the theme toggle does not. Measured, naming
- *               it took one app's drive from a ten-minute timeout to 138 seconds, because the turns
- *               go into FINDING a flow and naming one removes that search.
- *   --app       which app in a monorepo the user meant. init can find the ones that are servable;
- *               only the request says which of them is being worked on.
- *   --env       what the app needs to get past its own front door. A key in .env.example, a mock
- *               backend named in the README, the variable that skips an auth wall: all readable by
- *               an agent, none inferable by a script. Without this a real app sits on a login
- *               screen and there is no flow to drive at all.
- *   --url       the app is already running here, so do not start anything. This is also the answer
- *               when the project's own scripts do not name a dev command: start it yourself and say
- *               where. There is no flag that overrides the dev command; --url replaces the need.
- *
- * Everything else on this type is an operator's dial, not an agent's judgement.
- */
-/** The bridge port. NOT the dev server's, and conflating them is a documented setup failure. */
-export const DEFAULT_BRIDGE_PORT = 4400;
-/** Per-phase budget. The drive gets its own, much larger one. */
-export const DEFAULT_PHASE_TIMEOUT_MS = 120_000;
-/** What the drive may spend before it is stopped. */
-export const DEFAULT_DRIVE_BUDGET_USD = 3;
-export const DEFAULT_SETUP_OPTIONS = {
-    bridgePort: DEFAULT_BRIDGE_PORT,
-    phaseTimeoutMs: DEFAULT_PHASE_TIMEOUT_MS,
-    driveBudgetUsd: DEFAULT_DRIVE_BUDGET_USD,
-    registerAgents: true,
-    openBrowser: true,
-    drive: true,
-    escalateWeakFlow: true,
-    restartStaleDevServer: true,
-    filesOnly: false,
-};
-/** One `KEY=VALUE`, as an agent would pass it. Everything after the first `=` is the value. */
-export function parseEnvAssignment(pair) {
-    const at = pair.indexOf('=');
-    if (0 >= at)
-        return null;
-    const key = pair.slice(0, at).trim();
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
-        return null;
-    return { key, value: pair.slice(at + 1) };
-}
-/**
- * Fold repeated `--env KEY=VALUE` into one map, ignoring what cannot be a variable.
- *
- * A malformed pair is dropped rather than guessed at: an agent that meant `--env` and typed
- * something else should see its variable missing, not see setup invent one.
- */
-export function collectEnv(pairs) {
-    const env = {};
-    for (const pair of pairs) {
-        const parsed = parseEnvAssignment(pair);
-        if (null !== parsed)
-            env[parsed.key] = parsed.value;
-    }
-    return env;
-}

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

@@ -1,33 +0,0 @@
-import type { ExpectedLink } from '../capsule/divergence.js';
-import type { DivergenceCapsule } from '../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/tools/act-capsule.js

@@ -1,53 +0,0 @@
-/**
- * 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 '../capsule/capsule-store.js';
-import { ReticleTool } from './tool-names.js';
-import { asRecord, asString } from './tools-helpers.js';
-import { sessionRoot } from '../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 ?? sessionRoot(deps, asString(args['sessionId']));
-    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;
-}

package/dist/tools/act-danger.js

@@ -1,69 +0,0 @@
-import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, } from '@reticlehq/core';
-import { asRecord, asString } from './tools-helpers.js';
-/**
- * Refuse to drive a money-moving or destructive control by accident.
- *
- * A native click is indistinguishable from a user's, so an agent exploring an unfamiliar app can
- * refund a payment or delete an account while "just looking". The guard reads every text surface the
- * control exposes — its name, its text, its value, where it points, and the form it submits — because
- * a button labelled only with an icon still says what it does through its `formAction`.
- *
- * Opt in per action with `args.confirmDangerous: true`. Deliberately a THROW rather than a warning:
- * a caller that has not thought about it must not proceed by ignoring a field.
- */
-function descriptorText(value) {
-    const descriptor = asRecord(value);
-    return [
-        asString(descriptor['name']) ?? '',
-        asString(descriptor['text']) ?? '',
-        asString(descriptor['value']) ?? '',
-        asString(descriptor['href']) ?? '',
-        asString(descriptor['formAction']) ?? '',
-        asString(descriptor['formText']) ?? '',
-    ].join(' ');
-}
-function descriptorRole(value) {
-    const role = asString(asRecord(value)['role']);
-    return role !== undefined && role.length > 0 ? role : undefined;
-}
-function isDestructiveDescriptor(value) {
-    return isDangerousActionText(descriptorText(value), descriptorRole(value));
-}
-export function assertNotDestructive(action, innerArgs, inspected) {
-    if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
-        return;
-    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
-        return;
-    if (!isDestructiveDescriptor(inspected))
-        return;
-    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
-}
-/**
- * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
- * source alone never says so. Each end is classified on its own text and role, so a Payment
- * option dragged onto Save is not a payment.
- */
-export function assertDragNotDestructive(innerArgs, from, to) {
-    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
-        return;
-    if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to))
-        return;
-    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
-}
-/**
- * `reticle_act_and_wait` cannot drive native input, and used to take `args.native` and ignore it.
- *
- * An open `args` passthrough accepted the field, the handler drove the page through the SDK anyway,
- * and the result claimed success — so an agent asking for the one thing a synthetic click cannot do
- * (a file picker, the clipboard, an `isTrusted`-gated handler) got a synthetic click and no hint
- * that its request had been dropped. A silently ignored argument is a false promise; refusing with
- * the route that DOES work is the honest answer.
- */
-export const NATIVE_INPUT_UNSUPPORTED = `reticle_act_and_wait cannot drive native input, so args.${NATIVE_INPUT_ARG} would be ignored. ` +
-    `Use reticle_act { args: { ${NATIVE_INPUT_ARG}: true } } for the trusted click, then assert the ` +
-    'consequence with reticle_assert / reticle_observe using the `since` cursor it returns.';
-/** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
-export function assertNativeInputSupported(innerArgs) {
-    if (true === innerArgs[NATIVE_INPUT_ARG])
-        throw new Error(NATIVE_INPUT_UNSUPPORTED);
-}

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

@@ -1,17 +0,0 @@
-/**
- * Pure coercion + grading helpers behind the act tools.
- *
- * Split out when act-tools.ts crossed the 600-line cap. The seam is that nothing here touches a
- * session, a command, or a tool definition — these are total functions over their arguments, which
- * is why they can be tested without a browser and why they were the right thing to move.
- */
-import { ActionType } from '@reticlehq/core';
-import type { ElementBox } from '../input/real-input.js';
-import { HonestyGrade } from '../honesty/honesty.js';
-import type { ExpectedLink } from '../capsule/divergence.js';
-/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
-export declare function gradeOf(links: readonly ExpectedLink[]): HonestyGrade;
-/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
-export declare function asBox(value: unknown): ElementBox | undefined;
-/** Outcome of a real-input attempt — real success (result set) or synthetic with a reason. */
-export declare function asActionType(value: unknown): ActionType | undefined;

package/dist/tools/act-helpers.js

@@ -1,40 +0,0 @@
-/**
- * Pure coercion + grading helpers behind the act tools.
- *
- * Split out when act-tools.ts crossed the 600-line cap. The seam is that nothing here touches a
- * session, a command, or a tool definition — these are total functions over their arguments, which
- * is why they can be tested without a browser and why they were the right thing to move.
- */
-import { ActionType, ConsequenceKind } from '@reticlehq/core';
-import { HonestyGrade } from '../honesty/honesty.js';
-import { asNumber, asRecord, asString } from './tools-helpers.js';
-/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
-export function gradeOf(links) {
-    if (links.some((l) => ConsequenceKind.SIGNAL === l.kind))
-        return HonestyGrade.SIGNAL;
-    if (links.some((l) => ConsequenceKind.NET === l.kind))
-        return HonestyGrade.NET;
-    if (links.some((l) => ConsequenceKind.STATE === l.kind))
-        return HonestyGrade.STATE;
-    return HonestyGrade.PRESENCE;
-}
-/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
-export function asBox(value) {
-    const b = asRecord(asRecord(value)['box']);
-    const x = asNumber(b['x']);
-    const y = asNumber(b['y']);
-    const w = asNumber(b['width']);
-    const h = asNumber(b['height']);
-    if (x === undefined || y === undefined || w === undefined || h === undefined)
-        return undefined;
-    if (w <= 0 || h <= 0)
-        return undefined; // zero-area (display:none) ⇒ native click would miss
-    return { x, y, width: w, height: h };
-}
-/** Outcome of a real-input attempt — real success (result set) or synthetic with a reason. */
-export function asActionType(value) {
-    const raw = asString(value);
-    if (raw === undefined)
-        return undefined;
-    return Object.values(ActionType).includes(raw) ? raw : undefined;
-}

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

@@ -1,42 +0,0 @@
-/**
- * What to do when the observer left in the middle of an act.
- *
- * A full-document navigation — often the very thing the act CAUSED — tears the SDK down. The page
- * re-announces, and whatever this call still had in flight is gone. That is a fact about the
- * observer, never about the application, and the difference matters: every honest verdict this
- * engine can give depends on not converting "I stopped watching" into "your app is broken".
- *
- * Extracted from act-tools.ts, which had reached the file-size cap. It earns its own module because
- * it is one idea — follow the document that took over, and re-ask there — used from the two points
- * where observation can be lost: a write rejected at dispatch, and a wait cut off mid-predicate.
- */
-import type { Session } from '../session/session.js';
-import { type SuccessorRegistry } from '../session/session-successor.js';
-import type { EvalResult } from '../events/predicate-eval.js';
-interface FollowSuccessor {
-    sessions: SuccessorRegistry;
-    session: Session;
-    verdict: EvalResult;
-    /** Total budget the CALLER granted, in ms. */
-    timeout: number;
-    /** `session.elapsed()` at the moment the predicate started. */
-    predicateStarted: number;
-    /** Re-ask the declared consequence on `next`, with whatever budget is left. */
-    reevaluate: (next: Session, budgetMs: number) => Promise<EvalResult>;
-}
-interface FollowedOutcome {
-    session: Session;
-    verdict: EvalResult;
-    /** True when the wait moved to a new document, so the caller must reset its event cursor. */
-    followed: boolean;
-}
-/**
- * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
- *
- * `navigate` already waits for the HELLO and returns the new id; this path used to grade
- * `observation_lost` and leave the agent holding a DEAD id, so the next assert failed even though
- * the new page had loaded perfectly. Two live tabs at that origin is still a guess, and
- * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
- */
-export declare function followLostObservation(input: FollowSuccessor): Promise<FollowedOutcome>;
-export {};

package/dist/tools/act-observation.js

@@ -1,36 +0,0 @@
-/**
- * What to do when the observer left in the middle of an act.
- *
- * A full-document navigation — often the very thing the act CAUSED — tears the SDK down. The page
- * re-announces, and whatever this call still had in flight is gone. That is a fact about the
- * observer, never about the application, and the difference matters: every honest verdict this
- * engine can give depends on not converting "I stopped watching" into "your app is broken".
- *
- * Extracted from act-tools.ts, which had reached the file-size cap. It earns its own module because
- * it is one idea — follow the document that took over, and re-ask there — used from the two points
- * where observation can be lost: a write rejected at dispatch, and a wait cut off mid-predicate.
- */
-import { awaitDocumentSuccessor } from '../session/session-successor.js';
-/**
- * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
- *
- * `navigate` already waits for the HELLO and returns the new id; this path used to grade
- * `observation_lost` and leave the agent holding a DEAD id, so the next assert failed even though
- * the new page had loaded perfectly. Two live tabs at that origin is still a guess, and
- * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
- */
-export async function followLostObservation(input) {
-    const { sessions, session, verdict, timeout, predicateStarted, reevaluate } = input;
-    if (true !== verdict.observationLost || 0 >= timeout)
-        return { session, verdict, followed: false };
-    const remaining = timeout - (session.elapsed() - predicateStarted);
-    const next = remaining > 0 ? await awaitDocumentSuccessor(sessions, session, remaining) : null;
-    if (null === next)
-        return { session, verdict, followed: false };
-    // Computed on the DEPARTED session, before the caller points at the successor: the new session's
-    // elapsed() starts at 0 and would silently refund the whole budget the caller had already spent.
-    const leftover = timeout - (session.elapsed() - predicateStarted);
-    if (leftover <= 0)
-        return { session: next, verdict, followed: true };
-    return { session: next, verdict: await reevaluate(next, leftover), followed: true };
-}

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

@@ -1,20 +0,0 @@
-export declare function assertSequenceSteps(steps: readonly unknown[]): void;
-/**
- * Throws if this call cannot honestly be driven. Call it after the args are parsed and before the
- * first dispatch — anything that depends on what is actually rendered belongs after the action.
- */
-export declare function preflightAct(actArgs: Record<string, unknown>, until: unknown): void;
-/**
- * Dispatch a write, or report that its outcome went unobserved.
- *
- * Returns null — never throws — when the transport was displaced by a newer connection claiming the
- * same id. That happens on any full-document navigation the act itself causes: the page unloads,
- * re-announces, and the write in flight is rejected by the handle that just died.
- *
- * The write is deliberately NOT re-sent. Re-asking a READ on the successor is free; re-sending a
- * WRITE is not, because nothing can prove the first one did not reach the page — and a duplicated
- * click on a button that charges a card is a far worse outcome than a verdict of "I could not see".
- * Every other failure propagates unchanged: only a replacement is an observation problem, and
- * treating a timeout or a refusal as one would launder a real failure into a shrug.
- */
-export declare function dispatchAct<T>(send: () => Promise<T>): Promise<T | null>;

package/dist/tools/act-preflight.js

@@ -1,103 +0,0 @@
-/**
- * Everything refused BEFORE the action window opens.
- *
- * Both checks here share one property, and it is the reason they belong together: each is decidable
- * without touching the page, and each would otherwise be discovered only after the click had landed
- * — when the action is spent, the page has moved, and the honest answer has already been lost.
- *
- * Refusing early is not a convenience. `reticle_act_and_wait` promises a verdict, and a verdict that
- * blames the app for the caller's own mistake is the most damaging thing a verification tool can
- * produce: it sends somebody to fix code that is not broken. "Nothing was acted on" is a far better
- * outcome than "unknown".
- */
-import { isGlobalPressCall } from '@reticlehq/core';
-import { unevaluablePredicateReason } from '../events/predicate-precheck.js';
-import { SessionReplacedError } from '../session/pending-commands.js';
-import { assertNativeInputSupported } from './act-danger.js';
-/**
- * Refuse a sequence whose steps cannot be addressed.
- *
- * `steps` is a bare array of objects, so a step with neither `ref` nor `target` used to travel on
- * and dispatch as `ref: ''`. The browser then threw `ref '' no longer resolves to an element` —
- * a stale-ref diagnosis for a missing locator — and the caller went looking for a re-render.
- *
- * `target` is the same locator `reticle_act` / `reticle_act_and_wait` take; the handler resolves it
- * with `resolveActTarget` before dispatch. This check asks that every step names one of the two,
- * except a document-key press (Escape, Tab, a modifier shortcut), which is not aimed at an element.
- * It runs before the first step, so a typo in step three cannot leave one and two applied.
- */
-/**
- * Keys an agent reaches for when it means "and prove this happened".
- *
- * A sub-step reads `ref`/`target`/`action`/`args` and nothing else, and the schema is a permissive
- * record, so any of these was accepted and dropped. `until` is the likeliest of them by a distance:
- * it is what act_and_wait — the tool immediately next to this one — calls its assertion.
- *
- * Silently ignoring one manufactures a false green. A sequence carrying an impossible `until` came
- * back `completed: 1` with no error and nothing said about the predicate, which reads as the
- * consequence having held. act_sequence cannot grade one; refusing and naming the tool that can is
- * the same answer given to an unsupported native click, and for the same reason.
- */
-const CONSEQUENCE_KEYS = ['until', 'expect', 'assert', 'waitFor'];
-export function assertSequenceSteps(steps) {
-    if (0 === steps.length) {
-        throw new Error('reticle_act_sequence was given no steps. Pass steps: [{ ref, action, args? }] or [{ target, action, args? }] — nothing was acted on.');
-    }
-    steps.forEach((raw, i) => {
-        const step = 'object' === typeof raw && null !== raw ? raw : {};
-        const claimed = CONSEQUENCE_KEYS.find((k) => step[k] !== undefined);
-        if (claimed !== undefined) {
-            throw new Error(`step ${String(i)} carries \`${claimed}\`, and reticle_act_sequence cannot grade it. ` +
-                'Sub-steps are dispatched, never asserted — the key would be dropped and the sequence ' +
-                'would report success having checked nothing. Drive the steps here, then prove the ' +
-                'consequence with reticle_act_and_wait on the LAST action (its `until` is graded), or ' +
-                'with reticle_assert after this call. Nothing was acted on.');
-        }
-        if ('string' === typeof step['ref'] && step['ref'].length > 0)
-            return;
-        if (step['target'] !== undefined)
-            return;
-        if (isGlobalPressCall(step))
-            return;
-        throw new Error(`step ${String(i)} has no \`ref\` or \`target\`. ` +
-            'Sequence steps take `ref` (from reticle_query/reticle_snapshot) or `target` ' +
-            '(e.g. { testid } or { label }), the same locator reticle_act accepts. ' +
-            'A press of Escape, Tab, or a modifier shortcut is a document key and needs neither. ' +
-            'Nothing was acted on — the whole sequence is refused so a bad step cannot leave the earlier ones half-applied.');
-    });
-}
-/**
- * Throws if this call cannot honestly be driven. Call it after the args are parsed and before the
- * first dispatch — anything that depends on what is actually rendered belongs after the action.
- */
-export function preflightAct(actArgs, until) {
-    // This path cannot honour a native-input request, and taking the argument and ignoring it told
-    // the agent its trusted click had happened. See act-danger.
-    assertNativeInputSupported(actArgs);
-    const unevaluable = unevaluablePredicateReason(until);
-    if (unevaluable !== undefined)
-        throw new Error(unevaluable);
-}
-/**
- * Dispatch a write, or report that its outcome went unobserved.
- *
- * Returns null — never throws — when the transport was displaced by a newer connection claiming the
- * same id. That happens on any full-document navigation the act itself causes: the page unloads,
- * re-announces, and the write in flight is rejected by the handle that just died.
- *
- * The write is deliberately NOT re-sent. Re-asking a READ on the successor is free; re-sending a
- * WRITE is not, because nothing can prove the first one did not reach the page — and a duplicated
- * click on a button that charges a card is a far worse outcome than a verdict of "I could not see".
- * Every other failure propagates unchanged: only a replacement is an observation problem, and
- * treating a timeout or a refusal as one would launder a real failure into a shrug.
- */
-export async function dispatchAct(send) {
-    try {
-        return await send();
-    }
-    catch (error) {
-        if (error instanceof SessionReplacedError)
-            return null;
-        throw error;
-    }
-}

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

@@ -1,135 +0,0 @@
-/**
- * `reticle_act_sequence` — several actions compiled into one round trip.
- *
- * Split out of `act-tools.ts` when that file passed the 1000-line backstop. A tool seam rather than
- * an arbitrary one: its two neighbours drive ONE action and grade its consequence, while this one
- * compiles a list of steps and runs them inside a single action window, reporting per step.
- *
- * It keeps its own `beginAction` — the dispatch and the attribution window that must wrap it stay in
- * the same file, which is the property `dispatch-attribution.test.ts` enforces. An earlier attempt
- * split the shared `actCommand` helper out instead, which separated the two and that guard caught it.
- */
-import { z } from 'zod';
-import { timeoutMsSchema } from './numeric-bounds.js';
-import { compileSequenceStep } from '../flows/replay.js';
-import { ReticleTool } from './tool-names.js';
-import { healthEnvelope } from '../session/session-health.js';
-import { pausedShortCircuit, pausedOutputShape, withControl } from '../session/control-envelope.js';
-import { asRecord, sessionIdFromArgs } from './tools-helpers.js';
-import { describeStepResult, runStepWithStaleRetry } from './act-sequence-retry.js';
-import { assertSequenceSteps } from './act-preflight.js';
-import { sessionIdShape } from './tool-kit.js';
-import { actCommand } from './act-tools.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-target.js';
-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.
-    example: {
-        steps: [
-            { ref: 'e12', action: 'fill', args: { value: 'a@b.com' } },
-            { ref: 'e13', action: 'fill', args: { value: 'hunter2' } },
-            { ref: 'e14', action: 'click' },
-        ],
-    },
-    description: 'Run multiple actions in order (fill -> fill -> submit) in ONE round-trip. Prefer this over repeating reticle_act for a multi-step journey, then assert its consequence once. Returns per-step effects[] (see reticle_act).',
-    inputSchema: {
-        steps: z
-            .array(z.record(z.unknown()))
-            .describe('Ordered list of { ref | target, action, args? } objects. Each step is equivalent to one reticle_act call — give `ref` from a snapshot/query, or `target` ({ testid } | { label } | { role, name } | { text }) to resolve in this call. Put confirmDangerous:true in a destructive step args object.'),
-        timeout_ms: timeoutMsSchema
-            .optional()
-            .describe('Per-step timeout in milliseconds. Default: 8000. Each step gets this budget independently.'),
-        ...sessionIdShape,
-    },
-    outputSchema: {
-        since: z.number(),
-        dispatched: z.boolean(),
-        completed: z.number(),
-        stalled_at: z.number().optional(),
-        steps: z.array(z.record(z.unknown())).optional(),
-        result: z.unknown().optional(),
-        session: z
-            .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
-            .optional(),
-        // Short-circuits to pausedShortCircuit while paused — declare its fields (drained-once guidance).
-        ...pausedOutputShape,
-    },
-    handler: async (deps, args) => {
-        const session = deps.sessions.resolve(sessionIdFromArgs(args));
-        const paused = pausedShortCircuit(session);
-        if (paused !== undefined)
-            return paused;
-        const since = session.elapsed();
-        session.beginAction(ReticleTool.ACT_SEQUENCE, asRecord(args));
-        try {
-            const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
-            assertSequenceSteps(inputSteps);
-            const perStepTimeout = 'number' === typeof args['timeout_ms'] ? args['timeout_ms'] : 8000;
-            const stepResults = [];
-            let stalledAt;
-            // DIVERGENCE: live sends N individual ACT commands (for per-step timeout + progress);
-            // replay sends one batched ACT_SEQUENCE command (flows/replay.ts:294). A bug in either is
-            // invisible from the other — cover both when changing sequence semantics.
-            for (let i = 0; i < inputSteps.length; i++) {
-                const step = asRecord(inputSteps[i]);
-                try {
-                    // One retry when the ref went stale under a re-render — see act-sequence-retry.ts.
-                    // 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.
-                    const outcome = await runStepWithStaleRetry(async () => {
-                        const resolved = await resolveActTarget(session, step);
-                        if ('error' === resolved.kind)
-                            return { ok: false, error: resolved.message };
-                        return actCommand(deps, session, { ref: resolved.ref, action: step['action'], args: step['args'] ?? {} }, perStepTimeout);
-                    }, session, since, perStepTimeout);
-                    if (!outcome.ok) {
-                        stalledAt = i;
-                        stepResults.push({
-                            ref: step['ref'],
-                            action: step['action'],
-                            dispatched: false,
-                            error: outcome.error ?? 'step failed',
-                        });
-                        break;
-                    }
-                    stepResults.push(describeStepResult(step, asRecord(outcome.result)));
-                }
-                catch (err) {
-                    stalledAt = i;
-                    stepResults.push({
-                        ref: step['ref'],
-                        action: step['action'],
-                        dispatched: null,
-                        timedOut: true,
-                        error: err instanceof Error ? err.message : 'step timed out',
-                    });
-                    break;
-                }
-            }
-            const completed = stalledAt ?? inputSteps.length;
-            if (completed > 0) {
-                session.lastAct.markActed(since, undefined, undefined);
-            }
-            if (deps.recordings.active().length > 0 && stalledAt === undefined) {
-                deps.recordings.capture(compileSequenceStep(args, { count: inputSteps.length, steps: stepResults }));
-            }
-            return withControl(session, {
-                since,
-                dispatched: completed > 0,
-                completed,
-                ...(stalledAt !== undefined ? { stalled_at: stalledAt } : {}),
-                steps: stepResults,
-                ...healthEnvelope(session),
-            });
-        }
-        finally {
-            session.finishAction();
-        }
-    },
-};

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

@@ -1,18 +0,0 @@
-import type { Session } from '../session/session.js';
-import { type TargetResolution } from './resolve-target.js';
-/**
- * Resolve an action's element: an explicit `ref`, or a `target` query resolved in the SAME call.
- *
- * Requiring a ref meant every verification paid a `reticle_query` turn first just to learn one
- * string, and the advertised tool surface is re-sent on every turn — measured on the wire, a
- * two-turn verification spent 10,756 of 11,235 tokens on schema and 479 on the actual answers. The
- * lookup still happens; it just stops costing a round trip through the model.
- *
- * `ref` wins when both are given, because it is the more specific instruction and silently
- * preferring the query would act on something the caller did not name.
- *
- * A document-key press (Escape, Tab, a modifier shortcut) is the one action that is not aimed at
- * an element. It resolves to `{ kind: 'global' }` rather than refusing, so dismissing a dialog
- * does not cost a snapshot.
- */
-export declare function resolveActTarget(session: Session, args: Record<string, unknown>): Promise<TargetResolution>;