@e2edev/e2e 0.2.0

package/dist/agent/step-cache.js

@@ -0,0 +1,301 @@
+/**
+ * One step's trace-cache session (RFC0001 layer 3, cache-in decision): key
+ * derivation, the replay attempt, live recording, and the stage-or-evict
+ * decision once the step has settled — everything cache-shaped about one
+ * dispatched act step, kept beside the dispatch rather than threaded through
+ * it. The dispatch owns budgets, the grammar, and the verdict; this class owns
+ * nothing but the cache.
+ *
+ * Cost: in read-write mode the session takes two settled looks at the screen
+ * the executor never asked for — one before any action, one after the passing
+ * verdict — because the trace's end anchors are the delta between them. A
+ * read-only run pays neither.
+ */
+import { describeAnchors } from '../cache/anchors.js';
+import { decideTraceReplay, opensWithNavigate, samePathname, } from '../cache/decide.js';
+import { TraceRecorder } from '../cache/recorder.js';
+import { readTraceEntry } from '../cache/trace.js';
+import { isRuntimeHardStop } from './executor.js';
+import { replayTrace, verifyAnchors, } from './replay.js';
+export class StepTraceSession {
+    host;
+    cache;
+    keyHash;
+    recorder;
+    options;
+    info;
+    prefix;
+    startPath;
+    /**
+     * The screen before any action, captured only when this step may write: the
+     * staged trace's end anchors are the delta between this and the passing
+     * observation, so a replay must reproduce the step's effect to pass alone.
+     * Undefined after `begin` when the surface could not be observed; the step
+     * still runs — an executor that never looks at the screen owes the cache
+     * nothing — but nothing is staged, because a trace without its baseline has
+     * no anchors and would replay on mechanics alone.
+     */
+    startNodes;
+    /**
+     * The trace a full replay reproduced, kept for the re-stage: its executor
+     * is the write's provenance, and its summary is the original verdict prose.
+     * The step's own summary after a replay is the synthesized "replayed N
+     * actions…" wrapper; storing that would nest the summary one level deeper
+     * on every replay until the bound truncated it.
+     */
+    replayed;
+    /** True once a cached entry's actions were run this step, fully or partly. */
+    consumedReplay = false;
+    /** Grammar actions recorded so far when an end-mismatch hand-off happened. */
+    actionsAtEndMismatch;
+    constructor(host, options) {
+        this.host = host;
+        this.options = options;
+        this.cache = options.cache;
+        this.keyHash = options.cache.claimKeyHash('act', options.instruction, options.params);
+        if (options.cache.mode === 'read-write') {
+            this.recorder = new TraceRecorder({
+                redact: options.redact,
+                testIdAttribute: options.testIdAttribute,
+                maxActions: options.maxActions,
+            });
+        }
+    }
+    /** How the cache participated, for the step's report detail. */
+    get cacheInfo() {
+        return this.info;
+    }
+    /** The mid-step hand-off, when a replay diverged after real progress. */
+    get replayedPrefix() {
+        return this.prefix;
+    }
+    /** Records one committed grammar action into the step trace. */
+    record(action) {
+        this.recorder?.record(action);
+    }
+    /** Records one mutating project-tool call as a replay-ending gap. */
+    recordGap(toolName) {
+        this.recorder?.recordGap(toolName);
+    }
+    /**
+     * Opens the step: captures the write-side preconditions — the start path
+     * and, when this step may write, the baseline screen — then attempts a
+     * zero-turn replay. Returns the self-finalized verdict on a full replay
+     * whose postcondition holds; undefined dispatches the executor — after a
+     * miss from the top, after a divergence mid-step with `replayedPrefix` set.
+     * Every failure to replay is a miss, never an error; only runtime hard stops
+     * propagate.
+     */
+    async begin() {
+        // Captured before any action for the write's start-path precondition, and
+        // doubling as the replay decision's current path.
+        this.startPath = await this.host.currentPath();
+        if (this.recorder !== undefined)
+            this.startNodes = await probeScreen(this.host);
+        if (!this.cache.replayEligible)
+            return undefined;
+        const read = await this.readEntry();
+        if (read.status === 'miss') {
+            this.info = this.missed(read.reason, 0);
+            return undefined;
+        }
+        const trace = read.entry.payload;
+        const decision = decideTraceReplay(read.entry, this.startPath);
+        if (decision.action === 'miss') {
+            this.info = this.missed(decision.reason, trace.actions.length);
+            return undefined;
+        }
+        const outcome = await replayTrace(this.host, trace);
+        this.consumedReplay = true;
+        // Actions that all ran prove the clicks happened; only the postcondition
+        // proves the save took. A flow whose destination changed, or whose effect
+        // is not on screen again, hands off like any other divergence.
+        const stopReason = outcome.completed
+            ? (await this.endStateMatches(trace))
+                ? undefined
+                : 'end-mismatch'
+            : (outcome.stopReason ?? 'action-failed');
+        if (stopReason === undefined)
+            return this.selfFinalize(trace, outcome);
+        if (outcome.executed === 0) {
+            // A prefix that performed nothing is a miss with a name, not a hand-off:
+            // the executor starts from the top and owes the notice nothing.
+            this.info = this.missed(stopReason, outcome.total);
+            return undefined;
+        }
+        this.handOff(outcome, stopReason);
+        return undefined;
+    }
+    /**
+     * Closes the session once the step has settled. The whole write-side
+     * decision lives here, in read-write mode only:
+     *
+     * - passed, after an end-mismatch the executor had to act to repair: evict.
+     *   Every recorded action ran and the effect was still missing, so the
+     *   recorded flow is proven not to produce it. Re-staging would freeze the
+     *   failed flow plus its repair — a typo, its deletion, the retype — as the
+     *   thing to replay forever; the next pass records a clean flow instead. A
+     *   hand-off the executor settled without acting is different: the flow was
+     *   fine and only the anchors were stale, so it heals by re-staging.
+     * - passed otherwise: stage the recorded trace for attempt-end settlement.
+     * - failed after consuming a replay: evict. Without this, a diverged replay
+     *   whose step then fails stages nothing — and the poisoned entry would
+     *   replay its bad prefix on every future first attempt.
+     * - cancelled: nothing, exactly like an interrupted attempt.
+     */
+    async conclude(outcome, verdictSummary) {
+        const recorder = this.recorder;
+        if (recorder === undefined)
+            return;
+        switch (outcome) {
+            case 'cancelled':
+                return;
+            case 'failed':
+                if (this.consumedReplay)
+                    await this.evict();
+                return;
+            case 'passed':
+                if (this.repairedAfterEndMismatch(recorder))
+                    await this.evict();
+                else
+                    await this.stage(recorder, verdictSummary);
+                return;
+        }
+    }
+    /**
+     * One store read, revalidated through the trace-1 framing whichever store
+     * produced it: a custom store's entry can never be trusted more loosely
+     * than a file entry, however the store author built their read path. A
+     * store outage is a slower run, never a failed test — every failure to read
+     * degrades to a miss.
+     */
+    async readEntry() {
+        let read;
+        try {
+            read = await this.cache.store.read(this.keyHash);
+        }
+        catch {
+            return { status: 'miss', reason: 'invalid-entry' };
+        }
+        if (read.status === 'miss')
+            return { status: 'miss', reason: 'no-entry' };
+        if (read.status === 'invalid')
+            return { status: 'miss', reason: 'invalid-entry' };
+        const entry = readTraceEntry(read.entry);
+        return entry === undefined ? { status: 'miss', reason: 'invalid-entry' } : { status: 'hit', entry };
+    }
+    /**
+     * The trace's postcondition against the live screen: the recorded end path
+     * (pathname only, when the live location is known) and every recorded end
+     * anchor present again.
+     */
+    async endStateMatches(trace) {
+        if (trace.endPath !== undefined) {
+            const current = await this.host.currentPath();
+            if (current !== undefined && !samePathname(current, trace.endPath))
+                return false;
+        }
+        return verifyAnchors(this.host, trace.endAnchors ?? []);
+    }
+    selfFinalize(trace, outcome) {
+        this.replayed = trace;
+        this.info = {
+            mode: 'self-finalized',
+            replayedActions: outcome.executed,
+            totalActions: outcome.total,
+        };
+        return {
+            status: 'passed',
+            summary: `replayed ${outcome.executed} recorded action(s) zero-turn from the trace cache; recorded verdict: ${trace.summary}`,
+        };
+    }
+    handOff(outcome, stopReason) {
+        if (stopReason === 'end-mismatch')
+            this.actionsAtEndMismatch = this.recorder?.recordedCount ?? 0;
+        this.prefix = {
+            replayedActions: outcome.summaries,
+            totalActions: outcome.total,
+            stopReason,
+            ...(outcome.uncertainAction === undefined ? {} : { uncertainAction: outcome.uncertainAction }),
+        };
+        this.info = {
+            mode: 'agent-concluded',
+            reason: stopReason,
+            replayedActions: outcome.executed,
+            totalActions: outcome.total,
+        };
+    }
+    /**
+     * Stages the recorded trace for attempt-end settlement. The write is
+     * deferred, not immediate: the trace is confirmed or evicted at attempt end
+     * (`flushStagedTraces`), because the verification step after this one — not
+     * the verdict alone — is what proves the flow reached the right state. A
+     * replayed step re-stages its own entry with fresh descriptors, which is
+     * how staleness self-heals.
+     *
+     * The end path and a fresh settled observation are the trace's
+     * postcondition — the state the step passed in. The delta between the
+     * baseline and the passing observation becomes the end anchors. When the
+     * step moved to another pathname the whole screen is the delta and the path
+     * is the postcondition, so anchors are recorded only for a step that ended
+     * where it began (or on a surface without a location at all, where they are
+     * the only check). A postcondition that cannot be captured stages nothing:
+     * a trace without its check would replay on mechanics alone.
+     */
+    async stage(recorder, verdictSummary) {
+        if (this.startNodes === undefined)
+            return;
+        const endNodes = await probeScreen(this.host);
+        if (endNodes === undefined)
+            return;
+        const endPath = await this.host.currentPath();
+        const moved = this.startPath !== undefined && endPath !== undefined && !samePathname(this.startPath, endPath);
+        const endAnchors = moved ? undefined : describeAnchors(this.startNodes, endNodes, this.options);
+        const trace = recorder.finalize({
+            executor: this.replayed?.executor ?? this.options.executor,
+            summary: this.replayed?.summary ?? verdictSummary ?? 'step passed',
+            ...(this.startPath === undefined ? {} : { startPath: this.startPath }),
+            ...(endPath === undefined ? {} : { endPath }),
+            ...(endAnchors === undefined ? {} : { endAnchors }),
+        });
+        if (trace === undefined)
+            return;
+        // A trace with no start anchor — no recorded path (a surface without a URL)
+        // and no opening navigate — could never replay: `wrong-context` forever.
+        // Writing it would be pure store traffic, so it is not written at all.
+        if (trace.startPath === undefined && !opensWithNavigate(trace))
+            return;
+        this.cache.staged.push({ keyHash: this.keyHash, trace, stepIndex: this.options.stepIndex });
+    }
+    /**
+     * Awaited so the step does not close — and a later read cannot be served
+     * the stale flow — before the eviction has settled. The cache is
+     * disposable; a failed eviction is a slower next run only.
+     */
+    async evict() {
+        await this.cache.store.delete?.(this.keyHash).catch(() => undefined);
+    }
+    repairedAfterEndMismatch(recorder) {
+        return this.actionsAtEndMismatch !== undefined && recorder.recordedCount > this.actionsAtEndMismatch;
+    }
+    missed(reason, totalActions) {
+        return { mode: 'missed', reason, replayedActions: 0, totalActions };
+    }
+}
+/**
+ * One settled look at the screen, or undefined when the surface cannot be
+ * observed right now — the executor's business, not the cache's. Runtime hard
+ * stops (timeout, cancellation) are the step's truth even when they land
+ * during cache bookkeeping, and propagate.
+ */
+async function probeScreen(host) {
+    try {
+        return await host.observeSettled();
+    }
+    catch (cause) {
+        if (isRuntimeHardStop(cause))
+            throw cause;
+        return undefined;
+    }
+}
+//# sourceMappingURL=step-cache.js.map

package/dist/agent/step-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-cache.js","sourceRoot":"","sources":["../../src/agent/step-cache.ts"],"names":[],"mappings":"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"}

package/dist/agent/tool-loop.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The tool-loop chassis (RFC0001, layer 4): everything an AI SDK step
+ * executor needs except its tool vocabulary. `createAgent` is this chassis
+ * plus the grammar toolset; a device or API executor brings different
+ * tools and inherits the whole discipline unchanged:
+ *
+ * - the `complete_step` verdict tool and the closed blocked-code policy;
+ * - hard-stop handling (budget/timeout/cancel end the loop, never the model);
+ * - loop guards (repeated calls and short cycles warn, then force a verdict);
+ * - the wind-down notice and forced conclusion on the final turns;
+ * - model-call accounting and a step transcript for `--debug`.
+ */
+import type { ModelMessage, ToolSet } from 'ai';
+import { type SdkLanguageModel } from '../config/agent.ts';
+import { AgentError } from './error.ts';
+import { type StepExecutor, type StepExecutorContext } from './executor.ts';
+/** Loop services the executor's tool bodies run under. */
+export interface ToolLoopHelpers {
+    /**
+     * Runs one string-returning tool body under loop policy: nothing executes
+     * once the step is concluding, a runtime hard stop ends the loop, and every
+     * other failure goes back to the model as text it can react to.
+     */
+    guard(body: () => Promise<string>): Promise<string>;
+    /** True once a verdict or hard stop landed; late tool calls should no-op. */
+    concluding(): boolean;
+    /** Records a runtime hard stop (budget/timeout/cancel) that ends the loop. */
+    reportHardStop(error: AgentError): void;
+}
+export interface ToolLoopExecutorOptions {
+    readonly name: string;
+    readonly version?: string;
+    /** AI SDK language model; defaults to the config-resolved `agent.model`. */
+    readonly model?: SdkLanguageModel;
+    /**
+     * Executor-specific system guidance (what the tools are, how to address
+     * targets). The chassis appends the project context and the verdict rules.
+     */
+    readonly system?: string;
+    /** Builds the step's tool vocabulary; `complete_step` is added by the chassis. */
+    readonly tools: (context: StepExecutorContext, helpers: ToolLoopHelpers) => ToolSet;
+    /** Builds the first user message of the step. */
+    readonly buildPrompt: (context: StepExecutorContext) => string | Promise<string>;
+    /** Upper bound on model turns; capped at the harness model-call budget. */
+    readonly maxTurns?: number;
+    /** Between-turn history compaction; identity when omitted. */
+    readonly compactMessages?: (messages: ModelMessage[]) => ModelMessage[];
+}
+/** Builds a step executor from a tool vocabulary and the shared loop chassis. */
+export declare function createToolLoopExecutor(options: ToolLoopExecutorOptions): StepExecutor;
+//# sourceMappingURL=tool-loop.d.ts.map

package/dist/agent/tool-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loop.d.ts","sourceRoot":"","sources":["../../src/agent/tool-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAiB,YAAY,EAAc,OAAO,EAAE,MAAM,IAAI,CAAC;AAE3E,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG/E,OAAO,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAC;AACtD,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAEzB,MAAM,eAAe,CAAC;AA4CvB,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,6EAA6E;IAC7E,UAAU,IAAI,OAAO,CAAC;IACtB,8EAA8E;IAC9E,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC;IACpF,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjF,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,CAAC;CACzE;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,YAAY,CAuBrF"}