@e2edev/e2e 0.2.0 → 0.4.0

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

@@ -20,6 +20,19 @@ export type LoopGuardVerdict = {
     readonly kind: 'warn' | 'stop';
     readonly reason: string;
 };
+/**
+ * Guard thresholds. Identical-call (period 1) counts are consecutive
+ * repetitions of one call; cycle (period 2..4) counts are whole repetitions
+ * of the sequence. Each warns first, then forces the conclusion.
+ */
+export interface LoopGuardThresholds {
+    readonly repeatWarn: number;
+    readonly repeatStop: number;
+    readonly cycleWarn: number;
+    readonly cycleStop: number;
+}
+/** The thresholds the built-in agent ships with. */
+export declare const DEFAULT_LOOP_GUARD_THRESHOLDS: LoopGuardThresholds;
 /**
  * Extracts the tool-call identity sequence from a model transcript,
  * excluding the conclusion tool: concluding attempts are never "loops".
@@ -31,5 +44,5 @@ export declare function extractGuardCalls(messages: readonly ModelMessage[], con
  * on different targets never count as a repeat — only literally re-issuing
  * the same work does.
  */
-export declare function checkLoopGuards(calls: readonly GuardToolCall[]): LoopGuardVerdict;
+export declare function checkLoopGuards(calls: readonly GuardToolCall[], thresholds?: LoopGuardThresholds): LoopGuardVerdict;
 //# sourceMappingURL=loop-guards.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"loop-guards.d.ts","sourceRoot":"","sources":["../../src/agent/loop-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAEvC,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAahE;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,gBAAgB,EAAE,MAAM,GACvB,aAAa,EAAE,CAUjB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,gBAAgB,CAajF"}
+{"version":3,"file":"loop-guards.d.ts","sourceRoot":"","sources":["../../src/agent/loop-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAEvC,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAKhE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,oDAAoD;AACpD,eAAO,MAAM,6BAA6B,EAAE,mBAK3C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,gBAAgB,EAAE,MAAM,GACvB,aAAa,EAAE,CAUjB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,UAAU,GAAE,mBAAmD,GAC9D,gBAAgB,CAgBlB"}

package/dist/agent/loop-guards.js

@@ -10,12 +10,13 @@
  */
 /** Longest cycle period the detector considers. */
 const MAX_CYCLE_PERIOD = 4;
-/** Identical-call (period 1) thresholds: warn, then force the conclusion. */
-const REPEAT_WARN = 3;
-const REPEAT_STOP = 5;
-/** Cycle (period 2..4) thresholds, counted in whole repetitions. */
-const CYCLE_WARN = 2;
-const CYCLE_STOP = 3;
+/** The thresholds the built-in agent ships with. */
+export const DEFAULT_LOOP_GUARD_THRESHOLDS = {
+    repeatWarn: 3,
+    repeatStop: 5,
+    cycleWarn: 2,
+    cycleStop: 3,
+};
 /**
  * Extracts the tool-call identity sequence from a model transcript,
  * excluding the conclusion tool: concluding attempts are never "loops".
@@ -39,11 +40,13 @@ export function extractGuardCalls(messages, concludeToolName) {
  * on different targets never count as a repeat — only literally re-issuing
  * the same work does.
  */
-export function checkLoopGuards(calls) {
+export function checkLoopGuards(calls, thresholds = DEFAULT_LOOP_GUARD_THRESHOLDS) {
     let warning;
     for (let period = 1; period <= MAX_CYCLE_PERIOD; period += 1) {
         const repeats = trailingRepeats(calls, period);
-        const [warnAt, stopAt] = period === 1 ? [REPEAT_WARN, REPEAT_STOP] : [CYCLE_WARN, CYCLE_STOP];
+        const [warnAt, stopAt] = period === 1
+            ? [thresholds.repeatWarn, thresholds.repeatStop]
+            : [thresholds.cycleWarn, thresholds.cycleStop];
         if (repeats >= stopAt) {
             return { kind: 'stop', reason: describe(calls, period, repeats) };
         }

package/dist/agent/loop-guards.js.map

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

package/dist/agent/observation.d.ts

@@ -1,18 +1,21 @@
 /** Observation capture, redaction, and model serialization (spec 09-drivers.md, 14-security.md). */
-import type { Observation, ObservationPixels, SemanticNode } from '../backend/surface.ts';
+import type { Observation, SemanticNode } from '../backend/surface.ts';
+import type { VisionDegradation } from '../run/steps.ts';
+import type { ExecutorNode, ExecutorPixels } from './executor.ts';
 /** Why pixels the caller asked for are not part of this observation. */
 type PixelsWithheld = 'MASKING_UNPROVEN';
-/** Masked pixel evidence cleared for model input. */
-export interface AgentPixels extends ObservationPixels {
-    readonly maskedRegionCount: number;
-    readonly bytes: number;
-}
 export interface AgentObservation {
+    /** Location captured with this tree, when the backend can provide it. */
+    readonly url?: string;
     readonly revision: string;
     /** Redacted, size-bounded serialization sent to the model. */
     readonly text: string;
     readonly bytes: number;
     readonly nodes: ReadonlyMap<string, SemanticNode>;
+    /** Parent id of every non-root node, for the container a target sits in. */
+    readonly parents: ReadonlyMap<string, string>;
+    /** The raw tree as the backend reported it; redacted only on the way out. */
+    readonly tree: SemanticNode;
     readonly viewport: {
         readonly width: number;
         readonly height: number;
@@ -20,7 +23,7 @@ export interface AgentObservation {
     };
     readonly truncated: boolean;
     /** Present only when the backend captured pixels and masking checks out. */
-    readonly pixels?: AgentPixels | undefined;
+    readonly pixels?: ExecutorPixels | undefined;
     /** Set when captured pixels were dropped instead of being sent. */
     readonly pixelsWithheld?: PixelsWithheld | undefined;
 }
@@ -37,6 +40,24 @@ export declare function prepareObservation(observation: Observation, options: {
     maxBytes: number;
     testIdAttribute: string;
 }): AgentObservation;
+/**
+ * Whether requested pixels become model input, decided once per observation
+ * for every tier that asks: a tainted viewport (a secret filled this attempt)
+ * is denied first, since the secret may be anywhere on screen; then the
+ * capture's own reasons; then the pixels themselves.
+ */
+export declare function pixelsForModel(observation: AgentObservation, tainted: boolean): {
+    readonly pixels: ExecutorPixels;
+} | {
+    readonly withheld: VisionDegradation;
+};
+/**
+ * Projects the raw tree onto the executor-facing node shape: the same
+ * redaction the text serialization applies, field by field, and no value at
+ * all for a secure node. Selectors stay behind — they are relocation
+ * material for the trace cache, not something a brain reasons about.
+ */
+export declare function projectTree(node: SemanticNode, redact: (text: string) => string): ExecutorNode;
 /**
  * What the screen looks like, independent of which observation looked at it.
  *

package/dist/agent/observation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../../src/agent/observation.ts"],"names":[],"mappings":"AAAA,oGAAoG;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAO1F,wEAAwE;AACxE,KAAK,cAAc,GAAG,kBAAkB,CAAC;AAEzC,qDAAqD;AACrD,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE;IACP,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB,GACA,gBAAgB,CA6ClB;AAiED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM,CAOtE;AAMD,oFAAoF;AACpF,UAAU,WAAW;IACnB,WAAW,IAAI,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,EAC7B,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,CAAC,CAAC,CAaZ"}
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../../src/agent/observation.ts"],"names":[],"mappings":"AAAA,oGAAoG;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAKlE,wEAAwE;AACxE,KAAK,cAAc,GAAG,kBAAkB,CAAC;AAEzC,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAClD,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC7C,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE;IACP,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB,GACA,gBAAgB,CAiDlB;AAqBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,gBAAgB,EAC7B,OAAO,EAAE,OAAO,GACf;IAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,CAMhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,YAAY,CAqB9F;AA8CD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM,CAOtE;AAMD,oFAAoF;AACpF,UAAU,WAAW;IACnB,WAAW,IAAI,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,EAC7B,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,CAAC,CAAC,CAaZ"}

package/dist/agent/observation.js

@@ -13,7 +13,8 @@ const TRUNCATION_MARKER = '[observation truncated at the resolved observation by
  */
 export function prepareObservation(observation, options) {
     const nodes = new Map();
-    indexNodes(observation.tree, nodes);
+    const parents = new Map();
+    indexNodes(observation.tree, nodes, parents);
     const redact = options.redact;
     const lines = [];
     const encoder = new TextEncoder();
@@ -48,9 +49,12 @@ export function prepareObservation(observation, options) {
     const pixels = clearPixels(observation);
     return {
         revision: observation.revision,
+        ...(observation.url === undefined ? {} : { url: options.redact(observation.url) }),
         text,
         bytes: textBytes,
         nodes,
+        parents,
+        tree: observation.tree,
         viewport: observation.viewport,
         truncated,
         ...(pixels.cleared === undefined ? {} : { pixels: pixels.cleared }),
@@ -72,7 +76,48 @@ function clearPixels(observation) {
     const { secureNodeCount, maskedRegionCount } = observation.redaction;
     if (maskedRegionCount < secureNodeCount)
         return { withheld: 'MASKING_UNPROVEN' };
-    return { cleared: { ...pixels, maskedRegionCount, bytes: pixels.data.byteLength } };
+    return { cleared: { ...pixels, maskedRegionCount } };
+}
+/**
+ * Whether requested pixels become model input, decided once per observation
+ * for every tier that asks: a tainted viewport (a secret filled this attempt)
+ * is denied first, since the secret may be anywhere on screen; then the
+ * capture's own reasons; then the pixels themselves.
+ */
+export function pixelsForModel(observation, tainted) {
+    if (tainted)
+        return { withheld: 'PIXEL_TAINTED' };
+    if (observation.pixels === undefined) {
+        return { withheld: observation.pixelsWithheld ?? 'UNSUPPORTED_CAPABILITY' };
+    }
+    return { pixels: observation.pixels };
+}
+/**
+ * Projects the raw tree onto the executor-facing node shape: the same
+ * redaction the text serialization applies, field by field, and no value at
+ * all for a secure node. Selectors stay behind — they are relocation
+ * material for the trace cache, not something a brain reasons about.
+ */
+export function projectTree(node, redact) {
+    const secure = node.states?.secure === true;
+    const attributes = node.attributes === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(node.attributes).map(([key, value]) => [key, redact(value)]));
+    return {
+        id: node.ref.id,
+        ...(node.role === undefined ? {} : { role: node.role }),
+        ...(node.name === undefined ? {} : { name: redact(node.name) }),
+        ...(node.text === undefined ? {} : { text: redact(node.text) }),
+        ...(node.value === undefined || secure ? {} : { value: redact(node.value) }),
+        ...(node.inputPurpose === undefined ? {} : { inputPurpose: node.inputPurpose }),
+        ...(node.states === undefined ? {} : { states: node.states }),
+        ...(attributes === undefined ? {} : { attributes }),
+        ...(node.rect === undefined ? {} : { rect: node.rect }),
+        ...(node.framePath === undefined ? {} : { framePath: node.framePath }),
+        ...(node.children === undefined
+            ? {}
+            : { children: node.children.map((child) => projectTree(child, redact)) }),
+    };
 }
 /** Depth beyond this renders flat; deep chrome must not buy tokens with spaces. */
 const MAX_INDENT_DEPTH = 10;
@@ -166,9 +211,11 @@ export async function settleObservation(capture, shapeOf, clock) {
     }
     return value;
 }
-function indexNodes(node, into) {
+function indexNodes(node, into, parents) {
     into.set(node.ref.id, node);
-    for (const child of node.children ?? [])
-        indexNodes(child, into);
+    for (const child of node.children ?? []) {
+        parents.set(child.ref.id, node.ref.id);
+        indexNodes(child, into, parents);
+    }
 }
 //# sourceMappingURL=observation.js.map

package/dist/agent/observation.js.map

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

package/dist/agent/primitives.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The primitives under the built-in agent (RFC0001, layer 4). Each is one
+ * piece of the discipline the chassis and `createAgent` are assembled from,
+ * usable on its own with a raw AI SDK `ToolLoopAgent` or `generateText` —
+ * the way the AI SDK itself is a small opinionated agent over primitives you
+ * can also call directly:
+ *
+ * - `createGrammarTools` — AI SDK tools over the harness action grammar;
+ * - `createVerdictTool` — the `complete_step` tool and the closed blocked-code policy;
+ * - `trackModelCalls` — step handlers that report usage to the harness budgets;
+ * - `conversationMemory` — a message history kept across the steps of an attempt.
+ *
+ * Nothing here loads the `ai` package: an AI SDK tool is a plain object, so
+ * the module is safe to import from a config that never calls a model.
+ */
+import type { ModelMessage, StepResult, Tool, ToolSet } from 'ai';
+import { type StepExecutorContext, type StepVerdict } from './executor.ts';
+/** The verdict rules the built-in agent appends to its instructions. */
+export declare const VERDICT_RULES = "Verdict rules:\n- When the step's goal is achieved, or you are certain it cannot be, call complete_step exactly once.\n- Verify outcomes with your tools before concluding; never guess success.\n- \"passed\" means the application behaved as the step required. \"failed\" means it did not. \"blocked\" means credentials, the environment, or test setup prevented a product verdict \u2014 blocked says nothing about the product and requires an errorCode.";
+/** The conclusion tool and the verdict it collected. */
+export interface VerdictTool {
+    /** The `complete_step` tool; add it to the toolset under that name. */
+    readonly tool: Tool;
+    /** The verdict once the model called the tool with an accepted one. */
+    verdict(): StepVerdict | undefined;
+    /** True once a verdict landed; a `stopWhen` condition for a raw loop. */
+    concluded(): boolean;
+}
+/**
+ * The `complete_step` verdict tool. A blocked verdict without a blockable
+ * code is rejected back to the model, a passed verdict never carries a code,
+ * and the first accepted verdict is final.
+ */
+export declare function createVerdictTool(): VerdictTool;
+/** What a tool body runs under; the chassis supplies its loop policy here. */
+export interface GrammarToolOptions {
+    /**
+     * Wraps every tool body. The default runs it as is, so a harness hard stop
+     * (budget, timeout, cancel) propagates out of the tool; the chassis's guard
+     * instead turns it into text and ends the loop.
+     */
+    readonly guard?: (body: () => Promise<string>) => Promise<string>;
+}
+/**
+ * AI SDK tools over the harness action grammar, limited to the verbs the
+ * target's backend declared. A verb the surface cannot honor is not offered
+ * at all, so the model never learns vocabulary it can only be rejected on.
+ * Every mutating tool returns the updated screen.
+ */
+export declare function createGrammarTools(context: StepExecutorContext, options?: GrammarToolOptions): ToolSet;
+/** Step handlers that report every model round trip to the harness budgets. */
+export interface ModelCallTracker {
+    /** Pass as `onStepStart`; marks the turn's start for its duration. */
+    onStepStart(): void;
+    /**
+     * Pass as `onStepEnd` (or `onStepFinish`); records the turn's usage, cost,
+     * and provenance. Throws `STEP_BUDGET_EXHAUSTED` past the model-call budget,
+     * which ends a raw loop the same way it ends the chassis.
+     */
+    onStepEnd(step: Pick<StepResult<ToolSet>, 'usage' | 'providerMetadata'>): void;
+}
+/**
+ * Model-call accounting for a loop the executor runs itself. `model` names
+ * the provider and model id in the report; pass the AI SDK model instance.
+ */
+export declare function trackModelCalls(context: StepExecutorContext, model?: {
+    readonly provider?: string;
+    readonly modelId?: string;
+}): ModelCallTracker;
+/** A conversation kept in the attempt memory across the steps of one test. */
+export interface ConversationMemory {
+    /** Messages remembered by earlier steps of this attempt; empty on the first. */
+    readonly messages: readonly ModelMessage[];
+    /** Index of the last step that remembered, or -1. */
+    readonly lastStepIndex: number;
+    /** Stores the history for the next step of the attempt. */
+    remember(messages: readonly ModelMessage[]): void;
+}
+/**
+ * The executor's own conversation across an attempt, kept in
+ * `context.attempt.memory` under `key`. Open a step with
+ * `[...memory.messages, { role: 'user', content }]` and `remember` the full
+ * transcript when it ends; the harness drops it with the attempt.
+ */
+export declare function conversationMemory(context: StepExecutorContext, key?: string): ConversationMemory;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/agent/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/agent/primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAGlE,OAAO,EAAmB,KAAK,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAsB5F,wEAAwE;AACxE,eAAO,MAAM,aAAa,ucAG4N,CAAC;AAcvP,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,uEAAuE;IACvE,OAAO,IAAI,WAAW,GAAG,SAAS,CAAC;IACnC,yEAAyE;IACzE,SAAS,IAAI,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CA0C/C;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAsHT;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,WAAW,IAAI,IAAI,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAC,GAAG,IAAI,CAAC;CAChF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,mBAAmB,EAC5B,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,gBAAgB,CAkBlB;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAAC;CACnD;AAOD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,SAAqB,GACvB,kBAAkB,CAapB"}

package/dist/agent/primitives.js

@@ -0,0 +1,255 @@
+/**
+ * The primitives under the built-in agent (RFC0001, layer 4). Each is one
+ * piece of the discipline the chassis and `createAgent` are assembled from,
+ * usable on its own with a raw AI SDK `ToolLoopAgent` or `generateText` —
+ * the way the AI SDK itself is a small opinionated agent over primitives you
+ * can also call directly:
+ *
+ * - `createGrammarTools` — AI SDK tools over the harness action grammar;
+ * - `createVerdictTool` — the `complete_step` tool and the closed blocked-code policy;
+ * - `trackModelCalls` — step handlers that report usage to the harness budgets;
+ * - `conversationMemory` — a message history kept across the steps of an attempt.
+ *
+ * Nothing here loads the `ai` package: an AI SDK tool is a plain object, so
+ * the module is safe to import from a config that never calls a model.
+ */
+import { z } from 'zod';
+import { BLOCKABLE_CODES } from './executor.js';
+import { readCost } from './model/sdk.js';
+/** Codes the model may pick when concluding; runtime codes are runtime-assigned. */
+const MODEL_ERROR_CODES = [
+    'ACTION_FAILED',
+    'AUTOMATION_UNSUPPORTED',
+    'ASSERTION_FAILED',
+    'AUTHENTICATION_FAILED',
+    'AUTH_CREDENTIAL_UNAVAILABLE',
+    'AUTH_CREDENTIAL_INVALID',
+    'ENVIRONMENT_UNAVAILABLE',
+    'SEED_DATA_MISSING',
+    'TEST_SETUP_FAILED',
+    'APP_UNREACHABLE',
+    'APP_NOT_OPEN',
+    'POLICY_DENIED',
+];
+/** The model-pickable codes a blocked verdict accepts; derived, never restated. */
+const MODEL_BLOCKABLE_CODES = MODEL_ERROR_CODES.filter((code) => BLOCKABLE_CODES.has(code));
+/** The verdict rules the built-in agent appends to its instructions. */
+export const VERDICT_RULES = `Verdict rules:
+- When the step's goal is achieved, or you are certain it cannot be, call complete_step exactly once.
+- Verify outcomes with your tools before concluding; never guess success.
+- "passed" means the application behaved as the step required. "failed" means it did not. "blocked" means credentials, the environment, or test setup prevented a product verdict — blocked says nothing about the product and requires an errorCode.`;
+/**
+ * A plain AI SDK function tool with its input typed from the schema — what
+ * `tool()` from `ai` does, without loading `ai` to do it.
+ */
+function schemaTool(definition) {
+    return definition;
+}
+/**
+ * The `complete_step` verdict tool. A blocked verdict without a blockable
+ * code is rejected back to the model, a passed verdict never carries a code,
+ * and the first accepted verdict is final.
+ */
+export function createVerdictTool() {
+    let verdict;
+    const tool = schemaTool({
+        description: 'Conclude the step with the final verdict. passed = the application behaved as required and you verified it. failed = the application did not behave as required. blocked = credentials, environment, or test setup prevented a product verdict; blocked requires errorCode.',
+        inputSchema: z.object({
+            status: z.enum(['passed', 'failed', 'blocked']),
+            summary: z
+                .string()
+                .min(1)
+                .max(500)
+                .describe('What you did and what you saw, in plain language'),
+            errorCode: z.enum(MODEL_ERROR_CODES).optional(),
+        }),
+        execute: async (input) => {
+            if (verdict !== undefined)
+                return 'The step already concluded.';
+            if (input.status === 'blocked' &&
+                (input.errorCode === undefined ||
+                    !MODEL_BLOCKABLE_CODES.includes(input.errorCode))) {
+                return ('Rejected: a blocked verdict requires errorCode naming what blocked you ' +
+                    `(one of ${MODEL_BLOCKABLE_CODES.join(', ')}). ` +
+                    'If the application itself misbehaved, use status "failed" instead.');
+            }
+            verdict = {
+                status: input.status,
+                summary: input.summary,
+                ...(input.errorCode === undefined || input.status === 'passed'
+                    ? {}
+                    : { errorCode: input.errorCode }),
+            };
+            return 'Step concluded.';
+        },
+    });
+    return {
+        tool,
+        verdict: () => verdict,
+        concluded: () => verdict !== undefined,
+    };
+}
+/**
+ * AI SDK tools over the harness action grammar, limited to the verbs the
+ * target's backend declared. A verb the surface cannot honor is not offered
+ * at all, so the model never learns vocabulary it can only be rejected on.
+ * Every mutating tool returns the updated screen.
+ */
+export function createGrammarTools(context, options = {}) {
+    const guard = options.guard ?? ((body) => body());
+    const { verbs } = context.target;
+    /** Re-observes after a mutating action so the model always sees the result. */
+    const acted = async (description) => {
+        const observation = await context.observe();
+        return `${description}\n\nUpdated screen (revision ${observation.revision}):\n${observation.text}`;
+    };
+    const target = z.string().min(1).describe('Node id from the newest observation, e.g. "n42"');
+    const tools = {
+        observe: schemaTool({
+            description: 'Capture a fresh observation of the current screen without acting.',
+            inputSchema: z.object({}),
+            execute: () => guard(async () => {
+                const observation = await context.observe();
+                return `Current screen (revision ${observation.revision}):\n${observation.text}`;
+            }),
+        }),
+    };
+    if (verbs.has('tap')) {
+        tools['tap'] = schemaTool({
+            description: 'Tap or click one node.',
+            inputSchema: z.object({ target }),
+            execute: ({ target: id }) => guard(async () => {
+                await context.actions.tap({ id });
+                return acted(`Tapped #${id}.`);
+            }),
+        });
+    }
+    if (verbs.has('type')) {
+        tools['type'] = schemaTool({
+            description: 'Type a plain-text value into one input node. Replaces the current value.',
+            inputSchema: z.object({ target, value: z.string() }),
+            execute: ({ target: id, value }) => guard(async () => {
+                await context.actions.type({ id }, value);
+                return acted(`Typed into #${id}.`);
+            }),
+        });
+    }
+    if (verbs.has('press')) {
+        tools['press'] = schemaTool({
+            description: 'Send one key (e.g. "Enter", "Escape", "Tab") to one node.',
+            inputSchema: z.object({ target, key: z.string().min(1).max(64) }),
+            execute: ({ target: id, key }) => guard(async () => {
+                await context.actions.press({ id }, key);
+                return acted(`Pressed ${key} on #${id}.`);
+            }),
+        });
+    }
+    if (verbs.has('select')) {
+        tools['select'] = schemaTool({
+            description: 'Pick one option from a select-like control by its visible label.',
+            inputSchema: z.object({ target, value: z.string().min(1) }),
+            execute: ({ target: id, value }) => guard(async () => {
+                await context.actions.select({ id }, value);
+                return acted(`Selected "${value}" in #${id}.`);
+            }),
+        });
+    }
+    if (verbs.has('scroll')) {
+        const direction = z.enum(['up', 'down', 'left', 'right']);
+        // Node-targeted scrolling rides `perform`; without it only the viewport scrolls.
+        tools['scroll'] = verbs.has('tap')
+            ? schemaTool({
+                description: 'Scroll the viewport, or one scrollable node when target is given.',
+                inputSchema: z.object({ direction, target: target.optional() }),
+                execute: ({ direction: way, target: id }) => guard(async () => {
+                    await context.actions.scroll(way, id === undefined ? undefined : { id });
+                    return acted(`Scrolled ${way}.`);
+                }),
+            })
+            : schemaTool({
+                description: 'Scroll the viewport.',
+                inputSchema: z.object({ direction }),
+                execute: ({ direction: way }) => guard(async () => {
+                    await context.actions.scroll(way);
+                    return acted(`Scrolled ${way}.`);
+                }),
+            });
+    }
+    if (verbs.has('navigate')) {
+        tools['navigate'] = schemaTool({
+            description: 'Navigate to a URL or app-relative path within the allowed origins.',
+            inputSchema: z.object({ url: z.string().min(1) }),
+            execute: ({ url }) => guard(async () => {
+                await context.actions.navigate(url);
+                return acted(`Navigated to ${url}.`);
+            }),
+        });
+    }
+    // Offered only when the step declared secrets and the surface can fill: an
+    // empty vocabulary is better than a tool the model can only be rejected on.
+    if (verbs.has('typeSecret') && context.step.secrets.length > 0) {
+        tools['type_secret'] = schemaTool({
+            description: 'Fill one declared secret credential into a secure input field; the plaintext never passes through you. Available: ' +
+                context.step.secrets.map((secret) => `"${secret.name}" (${secret.purpose})`).join(', ') +
+                '.',
+            inputSchema: z.object({ target, name: z.string().min(1) }),
+            execute: ({ target: id, name }) => guard(async () => {
+                await context.actions.typeSecret({ id }, name);
+                return acted(`Filled secret "${name}" into #${id}.`);
+            }),
+        });
+    }
+    return tools;
+}
+/**
+ * Model-call accounting for a loop the executor runs itself. `model` names
+ * the provider and model id in the report; pass the AI SDK model instance.
+ */
+export function trackModelCalls(context, model) {
+    let turnStartedMs = Date.now();
+    return {
+        onStepStart: () => {
+            turnStartedMs = Date.now();
+        },
+        onStepEnd: (step) => {
+            const estimatedCostUsd = readCost(step.providerMetadata);
+            context.budgets.recordModelCall({
+                ...(step.usage.inputTokens === undefined ? {} : { inputTokens: step.usage.inputTokens }),
+                ...(step.usage.outputTokens === undefined ? {} : { outputTokens: step.usage.outputTokens }),
+                durationMs: Date.now() - turnStartedMs,
+                ...(typeof model?.provider === 'string' ? { provider: model.provider } : {}),
+                ...(typeof model?.modelId === 'string' ? { modelId: model.modelId } : {}),
+                ...(estimatedCostUsd === undefined ? {} : { estimatedCostUsd }),
+            });
+        },
+    };
+}
+/**
+ * The executor's own conversation across an attempt, kept in
+ * `context.attempt.memory` under `key`. Open a step with
+ * `[...memory.messages, { role: 'user', content }]` and `remember` the full
+ * transcript when it ends; the harness drops it with the attempt.
+ */
+export function conversationMemory(context, key = 'e2e/conversation') {
+    const stored = context.attempt.memory.get(key);
+    const current = isStoredConversation(stored)
+        ? stored
+        : { messages: [], lastStepIndex: -1 };
+    return {
+        messages: current.messages,
+        lastStepIndex: current.lastStepIndex,
+        remember: (messages) => {
+            const kept = { messages: [...messages], lastStepIndex: context.step.index };
+            context.attempt.memory.set(key, kept);
+        },
+    };
+}
+function isStoredConversation(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'messages' in value &&
+        Array.isArray(value.messages) &&
+        'lastStepIndex' in value &&
+        typeof value.lastStepIndex === 'number');
+}
+//# sourceMappingURL=primitives.js.map