@e2edev/e2e 0.2.0

package/dist/agent/tool-loop.js

@@ -0,0 +1,331 @@
+/**
+ * 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 { z } from 'zod';
+import { asSdkLanguageModel } from '../config/agent.js';
+import { loadAiSdk } from './ai-sdk.js';
+import { readCost } from './model/sdk.js';
+import { AgentError, isAgentError } from './error.js';
+import { BLOCKABLE_CODES, RUNTIME_CODES, } from './executor.js';
+import { checkLoopGuards, extractGuardCalls } from './loop-guards.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));
+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.`;
+/** Turns remaining when the loop warns the model to wrap up. */
+const WIND_DOWN_TURNS = 5;
+/**
+ * Ceiling on the remaining step time under which the loop takes the verdict it
+ * can get. A slow provider turn runs tens of seconds; concluding with the
+ * model's own summary beats a verdict-less STEP_TIMEOUT every time. The
+ * effective window is a quarter of the step's budget, capped here, so a short
+ * step keeps most of its clock for work instead of losing half of it to the
+ * wind-down.
+ */
+const CLOCK_WIND_DOWN_MS = 60_000;
+const CLOCK_WIND_DOWN_FRACTION = 4;
+/** Transcript ceiling per step; enough for every turn without unbounded logs. */
+const MAX_TRANSCRIPT_CHARS = 262_144;
+/** Builds a step executor from a tool vocabulary and the shared loop chassis. */
+export function createToolLoopExecutor(options) {
+    return {
+        name: options.name,
+        ...(options.version === undefined ? {} : { version: options.version }),
+        async runStep(context) {
+            // The AI SDK is an optional peer; load it before anything touches it —
+            // including the context's gateway-model getter below.
+            const ai = await loadAiSdk();
+            // The context's model getter resolves the configured model on read, so
+            // an executor that brought its own never touches (or fails on) it.
+            const model = options.model ??
+                (context.model === undefined ? undefined : asSdkLanguageModel(context.model));
+            if (model === undefined) {
+                throw new AgentError('MODEL_UNAVAILABLE', `the "${options.name}" executor requires a model: set agent.model, E2E_MODEL, or pass one to the executor`);
+            }
+            const loop = new LoopRun(ai, options, context, model);
+            return loop.run();
+        },
+    };
+}
+/** One step's loop state and wiring; constructed fresh per runStep. */
+class LoopRun {
+    ai;
+    options;
+    context;
+    model;
+    verdict;
+    hardStop;
+    guardStop;
+    noticedGuardReason;
+    noticedLowClock = false;
+    transcript = [];
+    maxTurns;
+    windDownMs;
+    constructor(ai, options, context, model) {
+        this.ai = ai;
+        this.options = options;
+        this.context = context;
+        this.model = model;
+        // Capped, never raised: the harness budget is the ceiling for any turns
+        // setting, so the loop cannot spend past what the step was given.
+        this.maxTurns = Math.min(options.maxTurns ?? context.budgets.maxModelCalls, context.budgets.maxModelCalls);
+        this.windDownMs = Math.min(CLOCK_WIND_DOWN_MS, Math.floor(context.budgets.remainingMs() / CLOCK_WIND_DOWN_FRACTION));
+    }
+    async run() {
+        const helpers = this.helpers();
+        const tools = {
+            ...this.options.tools(this.context, helpers),
+            complete_step: this.concludeTool(),
+        };
+        const loop = new this.ai.ToolLoopAgent({
+            model: this.model,
+            instructions: this.instructions(),
+            tools,
+            toolChoice: 'required',
+            stopWhen: [
+                () => this.verdict !== undefined || this.hardStop !== undefined,
+                this.ai.stepCountIs(this.maxTurns),
+            ],
+            prepareStep: ({ messages, stepNumber }) => this.prepareTurn(messages, stepNumber),
+        });
+        const identity = this.model;
+        const prompt = await this.options.buildPrompt(this.context);
+        let turnStartedMs = Date.now();
+        try {
+            await loop.generate({
+                prompt,
+                abortSignal: this.context.signal,
+                onStepStart: () => {
+                    turnStartedMs = Date.now();
+                },
+                onStepEnd: (step) => {
+                    this.recordTurn(step);
+                    const estimatedCostUsd = readCost(step.providerMetadata);
+                    this.context.budgets.recordModelCall({
+                        ...(step.usage.inputTokens === undefined
+                            ? {}
+                            : { inputTokens: step.usage.inputTokens }),
+                        ...(step.usage.outputTokens === undefined
+                            ? {}
+                            : { outputTokens: step.usage.outputTokens }),
+                        durationMs: Date.now() - turnStartedMs,
+                        ...(typeof identity.provider === 'string' ? { provider: identity.provider } : {}),
+                        ...(typeof identity.modelId === 'string' ? { modelId: identity.modelId } : {}),
+                        ...(estimatedCostUsd === undefined ? {} : { estimatedCostUsd }),
+                    });
+                },
+            });
+        }
+        catch (cause) {
+            this.attachTranscript();
+            if (this.context.signal.aborted) {
+                throw new AgentError('CANCELLED', 'the step was cancelled', { cause });
+            }
+            if (this.hardStop !== undefined)
+                throw this.hardStop;
+            if (isAgentError(cause))
+                throw cause;
+            throw new AgentError('MODEL_PROVIDER_FAILED', `the model provider failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        }
+        this.attachTranscript();
+        if (this.verdict !== undefined)
+            return this.verdict;
+        if (this.hardStop !== undefined) {
+            if (this.hardStop.code === 'CANCELLED')
+                throw this.hardStop;
+            return { status: 'blocked', summary: this.hardStop.message, errorCode: this.hardStop.code };
+        }
+        return {
+            status: 'failed',
+            summary: `the agent used ${this.maxTurns} turn(s) without calling complete_step`,
+            errorCode: 'STEP_NO_CONCLUSION',
+        };
+    }
+    helpers() {
+        return {
+            concluding: () => this.verdict !== undefined || this.hardStop !== undefined,
+            reportHardStop: (error) => {
+                this.hardStop ??= error;
+            },
+            guard: async (body) => {
+                if (this.verdict !== undefined || this.hardStop !== undefined) {
+                    return 'The step is already concluding; no further actions run.';
+                }
+                try {
+                    return await body();
+                }
+                catch (cause) {
+                    if (isAgentError(cause) && RUNTIME_CODES.has(cause.code)) {
+                        this.hardStop ??= cause;
+                        return `HARD STOP (${cause.code}): ${cause.message}`;
+                    }
+                    const message = cause instanceof Error ? cause.message : String(cause);
+                    return `Action failed: ${message}`;
+                }
+            },
+        };
+    }
+    /**
+     * Per-turn policy, in order: compact history, evaluate the loop guards,
+     * inject the wind-down notice, and — near the budget or after a guard stop —
+     * offer only the conclusion tool. Two forced turns, not one, so a rejected
+     * verdict (blocked without a code) can be repaired.
+     */
+    prepareTurn(messages, stepNumber) {
+        let prepared = this.options.compactMessages?.(messages) ?? messages;
+        const turnsLeft = this.maxTurns - stepNumber;
+        // Never on the very first turn: a deliberately short step timeout still
+        // deserves one working turn before the clock takes the verdict.
+        const lowClock = stepNumber > 0 && this.context.budgets.remainingMs() < this.windDownMs;
+        if (lowClock && this.noticedLowClock !== true) {
+            this.noticedLowClock = true;
+            prepared = appendNotice(prepared, '[SYSTEM] The step is nearly out of time. Call complete_step now with your best ' +
+                'verdict: passed only if you verified the goal, failed if the application ' +
+                'misbehaved, blocked (with errorCode) if something outside the application ' +
+                'stopped you.');
+        }
+        if (this.guardStop === undefined) {
+            const guard = checkLoopGuards(extractGuardCalls(prepared, 'complete_step'));
+            if (guard.kind === 'stop') {
+                this.guardStop = guard.reason;
+            }
+            else if (guard.kind === 'warn' && guard.reason !== this.noticedGuardReason) {
+                this.noticedGuardReason = guard.reason;
+                prepared = appendNotice(prepared, `[SYSTEM NOTICE] You appear to be going in circles: ${guard.reason}. ` +
+                    'Change approach, or call complete_step with your best verdict.');
+            }
+        }
+        if (this.guardStop !== undefined && this.guardStop !== this.noticedGuardReason) {
+            this.noticedGuardReason = this.guardStop;
+            prepared = appendNotice(prepared, `[SYSTEM] Loop guard: ${this.guardStop}. Repeating it further will not make progress. ` +
+                'Call complete_step now with your best verdict: failed if the application misbehaved, ' +
+                'blocked (with errorCode) if something outside the application stopped you.');
+        }
+        if (turnsLeft === WIND_DOWN_TURNS && this.guardStop === undefined) {
+            prepared = appendNotice(prepared, `[SYSTEM NOTICE] Only ${turnsLeft} turns remain for this step. ` +
+                'Finish the remaining work now, or call complete_step with your best verdict: ' +
+                'failed if the application misbehaved, blocked (with errorCode) if something ' +
+                'outside the application stopped you.');
+        }
+        const forced = turnsLeft <= 2 || this.guardStop !== undefined || lowClock;
+        return {
+            ...(prepared === messages ? {} : { messages: prepared }),
+            ...(forced
+                ? {
+                    activeTools: ['complete_step'],
+                    toolChoice: { type: 'tool', toolName: 'complete_step' },
+                }
+                : {}),
+        };
+    }
+    concludeTool() {
+        const { tool } = this.ai;
+        return tool({
+            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 (this.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.');
+                }
+                this.verdict = {
+                    status: input.status,
+                    summary: input.summary,
+                    // A passed verdict never carries a code; a redundant one from the
+                    // model is dropped rather than failing the step.
+                    ...(input.errorCode === undefined || input.status === 'passed'
+                        ? {}
+                        : { errorCode: input.errorCode }),
+                };
+                return 'Step concluded.';
+            },
+        });
+    }
+    instructions() {
+        const parts = [];
+        if (this.options.system !== undefined && this.options.system.trim() !== '') {
+            parts.push(this.options.system);
+        }
+        const project = this.context.agentContext;
+        if (project !== undefined && project.trim() !== '') {
+            parts.push(`Project context:\n${project}`);
+        }
+        parts.push(VERDICT_RULES);
+        return parts.join('\n\n');
+    }
+    /** Serializes one turn into the step transcript. */
+    recordTurn(step) {
+        const turn = this.transcript.length + 1;
+        const lines = [`--- turn ${turn} ---`];
+        if (step.text.trim() !== '')
+            lines.push(`assistant: ${truncate(step.text, 1_000)}`);
+        for (const call of step.toolCalls) {
+            lines.push(`tool call: ${call.toolName}(${truncate(safeJson(call.input), 400)})`);
+        }
+        for (const result of step.toolResults) {
+            lines.push(`tool result [${result.toolName}]: ${truncate(safeJson(result.output), 600)}`);
+        }
+        this.transcript.push(lines.join('\n'));
+    }
+    attachTranscript() {
+        if (this.transcript.length === 0)
+            return;
+        this.context.attachTranscript(truncate(this.transcript.join('\n'), MAX_TRANSCRIPT_CHARS));
+    }
+}
+function appendNotice(messages, content) {
+    return [...messages, { role: 'user', content }];
+}
+function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…[truncated]`;
+}
+function safeJson(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=tool-loop.js.map

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

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

package/dist/agent/tool.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `defineTool` (RFC0001, layer 2): an AI SDK tool plus the required semantic
+ * annotation. The annotation is what lets the harness treat a project tool as
+ * a first-class capability — replay eligibility, mutation tracking, and secret
+ * gating are declared, never inferred. A tool without declared semantics is
+ * excluded from caching and untrusted by default, which in v0 (no cache)
+ * reduces to: the annotation is required and recorded.
+ */
+import type { Tool } from 'ai';
+import type { Platform } from '../types.ts';
+export interface ToolAnnotations {
+    /**
+     * `'deterministic'` — same input, same effect; a future cache may replay it.
+     * `'none'` — never replayed; always re-executed by a live executor.
+     */
+    readonly replay: 'deterministic' | 'none';
+    /** Whether executing the tool can change application state. */
+    readonly mutates: boolean;
+    /** Whether the tool handles secret material. */
+    readonly secrets: boolean;
+    /**
+     * Platforms this tool is offered on; absent means every platform. A suite
+     * that mixes targets of different platforms keeps a gesture tool off the
+     * platforms that cannot honor it by declaring this, not by splitting
+     * configs.
+     */
+    readonly platforms?: readonly Platform[];
+}
+export interface DefinedTool {
+    readonly tool: Tool;
+    readonly annotations: ToolAnnotations;
+}
+/** Attaches required semantics to an AI SDK tool. */
+export declare function defineTool(tool: Tool, annotations: ToolAnnotations): DefinedTool;
+/** True when a defined tool is offered on the given platform. */
+export declare function toolAppliesTo(defined: DefinedTool, platform: Platform): boolean;
+/** True when a value came through `defineTool`, from this or another realm. */
+export declare function isDefinedTool(value: unknown): value is DefinedTool;
+//# sourceMappingURL=tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/agent/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC;IAC1C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;CACvC;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,eAAe,GAAG,WAAW,CAmChF;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAE/E;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE"}

package/dist/agent/tool.js

@@ -0,0 +1,52 @@
+/**
+ * `defineTool` (RFC0001, layer 2): an AI SDK tool plus the required semantic
+ * annotation. The annotation is what lets the harness treat a project tool as
+ * a first-class capability — replay eligibility, mutation tracking, and secret
+ * gating are declared, never inferred. A tool without declared semantics is
+ * excluded from caching and untrusted by default, which in v0 (no cache)
+ * reduces to: the annotation is required and recorded.
+ */
+import { TestError } from '../internal/errors.js';
+/** Cross-realm identity marker for defined tools. */
+const DEFINED_TOOL_MARKER = Symbol.for('e2e.defined-tool.v1');
+/** Attaches required semantics to an AI SDK tool. */
+export function defineTool(tool, annotations) {
+    if (typeof tool !== 'object' || tool === null || typeof tool.execute !== 'function') {
+        throw new TestError('INVALID_ARGUMENT', 'defineTool requires an AI SDK tool with an execute function');
+    }
+    if (annotations === undefined || typeof annotations !== 'object') {
+        throw new TestError('INVALID_ARGUMENT', 'defineTool requires annotations: { replay, mutates, secrets }');
+    }
+    if (annotations.replay !== 'deterministic' && annotations.replay !== 'none') {
+        throw new TestError('INVALID_ARGUMENT', "annotations.replay must be 'deterministic' or 'none'");
+    }
+    if (typeof annotations.mutates !== 'boolean' || typeof annotations.secrets !== 'boolean') {
+        throw new TestError('INVALID_ARGUMENT', 'annotations.mutates and annotations.secrets must be booleans');
+    }
+    if (annotations.platforms !== undefined &&
+        (!Array.isArray(annotations.platforms) ||
+            annotations.platforms.length === 0 ||
+            annotations.platforms.some((platform) => typeof platform !== 'string' || platform === ''))) {
+        throw new TestError('INVALID_ARGUMENT', 'annotations.platforms must be a non-empty array of platform names when present');
+    }
+    const defined = {
+        tool,
+        annotations: {
+            replay: annotations.replay,
+            mutates: annotations.mutates,
+            secrets: annotations.secrets,
+            ...(annotations.platforms === undefined ? {} : { platforms: [...annotations.platforms] }),
+        },
+    };
+    Object.defineProperty(defined, DEFINED_TOOL_MARKER, { value: true });
+    return Object.freeze(defined);
+}
+/** True when a defined tool is offered on the given platform. */
+export function toolAppliesTo(defined, platform) {
+    return defined.annotations.platforms === undefined || defined.annotations.platforms.includes(platform);
+}
+/** True when a value came through `defineTool`, from this or another realm. */
+export function isDefinedTool(value) {
+    return typeof value === 'object' && value !== null && DEFINED_TOOL_MARKER in value;
+}
+//# sourceMappingURL=tool.js.map

package/dist/agent/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/agent/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,qDAAqD;AACrD,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;AA0B9D,qDAAqD;AACrD,MAAM,UAAU,UAAU,CAAC,IAAU,EAAE,WAA4B;IACjE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACpF,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,6DAA6D,CAAC,CAAC;IACzG,CAAC;IACD,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACjE,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,+DAA+D,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,KAAK,eAAe,IAAI,WAAW,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5E,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,sDAAsD,CAAC,CAAC;IAClG,CAAC;IACD,IAAI,OAAO,WAAW,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,WAAW,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACzF,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,8DAA8D,CAAC,CAAC;IAC1G,CAAC;IACD,IACE,WAAW,CAAC,SAAS,KAAK,SAAS;QACnC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC;YACpC,WAAW,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YAClC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,EAAE,CAAC,CAAC,EAC5F,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,kBAAkB,EAClB,gFAAgF,CACjF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAgB;QAC3B,IAAI;QACJ,WAAW,EAAE;YACX,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,OAAO,EAAE,WAAW,CAAC,OAAO;YAC5B,OAAO,EAAE,WAAW,CAAC,OAAO;YAC5B,GAAG,CAAC,WAAW,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;SAC1F;KACF,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,OAAoB,EAAE,QAAkB;IACpE,OAAO,OAAO,CAAC,WAAW,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACzG,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,mBAAmB,IAAI,KAAK,CAAC;AACrF,CAAC"}

package/dist/backend/contract.d.ts

@@ -0,0 +1,186 @@
+/**
+ * The backend contract vocabulary (RFC0002): the platform-neutral types every
+ * backend speaks and the harness consumes. A backend imports these from
+ * `@e2edev/e2e/backend`; core never imports anything from a backend.
+ *
+ * Everything here is capability vocabulary - semantic nodes, locator
+ * expressions, action kinds, the error contract - never a platform noun. A
+ * document platform, a simulator, and a desktop shell describe themselves with the same
+ * words, which is what lets `screen`, `expect`, and the agent work identically
+ * on all of them.
+ */
+import type { Momentum, ScrollDirection, SelectOption } from '../types.ts';
+/** The backend contract version this runner speaks. */
+export declare const BACKEND_SPI_VERSION = 1;
+export type BackendSpiVersion = typeof BACKEND_SPI_VERSION;
+export interface OperationContext {
+    readonly signal: AbortSignal;
+    /** Remaining operation budget when the call starts. */
+    readonly timeoutMs: number;
+    readonly runId: string;
+    readonly attemptId: string;
+}
+export type TextPattern = {
+    readonly kind: 'string';
+    readonly value: string;
+    readonly exact: boolean;
+} | {
+    readonly kind: 'regexp';
+    readonly source: string;
+    readonly flags: string;
+};
+export type QueryKind = 'role' | 'label' | 'placeholder' | 'text' | 'displayValue' | 'testId';
+export interface SemanticQuery {
+    readonly kind: QueryKind;
+    readonly value: TextPattern;
+    readonly name?: TextPattern;
+    readonly states?: Readonly<Partial<Record<'checked' | 'disabled' | 'selected' | 'expanded' | 'hidden', boolean>>>;
+}
+/**
+ * The location capability's query language. `selector` is a platform-native
+ * selector string (CSS or XPath on a document platform, a predicate on a
+ * device platform); `frame` scopes a query inside one nested document.
+ */
+export type LocatorExpression = {
+    readonly kind: 'query';
+    readonly query: SemanticQuery;
+    readonly scope?: LocatorExpression;
+} | {
+    readonly kind: 'filter';
+    readonly source: LocatorExpression;
+    readonly hasText?: TextPattern;
+    readonly has?: LocatorExpression;
+} | {
+    readonly kind: 'index';
+    readonly source: LocatorExpression;
+    readonly index: number | 'first' | 'last';
+} | {
+    readonly kind: 'selector';
+    readonly selector: string;
+} | {
+    readonly kind: 'frame';
+    readonly selector: string;
+    readonly source: LocatorExpression;
+};
+export interface NodeRef {
+    readonly id: string;
+    readonly revision: string;
+}
+/**
+ * Per-field bounds a backend applies to observation-tree nodes. A `name` or
+ * `text` whose length reaches its limit was cut at exactly that limit, so
+ * "length >= limit" is a precise truncation signal; every shorter value is
+ * complete. Single-node reads are unbounded and always carry the full value.
+ */
+export declare const OBSERVED_NAME_LIMIT = 256;
+export declare const OBSERVED_TEXT_LIMIT = 512;
+export interface SemanticNode {
+    readonly ref: NodeRef;
+    readonly role?: string;
+    readonly name?: string;
+    readonly text?: string;
+    readonly value?: string;
+    readonly inputPurpose?: 'username' | 'password' | 'one-time-code' | 'generic-secret' | 'none';
+    readonly states?: Readonly<Partial<Record<'checked' | 'disabled' | 'selected' | 'expanded' | 'focused' | 'hidden' | 'secure', boolean>>>;
+    readonly attributes?: Readonly<Record<string, string>>;
+    readonly rect?: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * Platform selector that addresses this node within its own document, when
+     * the platform has one. It is structural, not semantic: it survives the
+     * content changes that rename a node, and a runner may store it to re-find
+     * the node cheaply on a later run. It is never part of the node's identity,
+     * so whatever it resolves to is still checked before it is used.
+     *
+     * It SHOULD be anchored on an attribute naming the node or one of its
+     * ancestors, and SHOULD be absent rather than positional all the way to the
+     * document root: such a path is shifted by anything inserted above the node,
+     * so it does not survive to the later run it exists for (10-determinism.md).
+     */
+    readonly selector?: string;
+    /**
+     * Enclosing nested-document chain as selectors of each boundary node,
+     * outermost first. Absent for nodes in the main document.
+     */
+    readonly framePath?: readonly string[];
+    readonly children?: readonly SemanticNode[];
+}
+/**
+ * Viewport point in CSS pixels, origin at the top-left of the viewport.
+ * Reserved for coordinate-addressed actions; no runner surface consumes it yet.
+ */
+export interface ViewportPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Masked viewport pixels captured for one observation revision.
+ *
+ * `width` and `height` MUST be the true dimensions of `data`, because they are
+ * the space every coordinate read off the image refers to. `scale` relates that
+ * space to the CSS pixels of `SemanticNode.rect`, which is the space actions
+ * dispatch in: one image pixel is `1 / scale` CSS pixels.
+ */
+export interface ObservationPixels {
+    readonly data: Uint8Array;
+    readonly mediaType: 'image/png';
+    readonly width: number;
+    readonly height: number;
+    /** Image pixels per CSS pixel; 1 for a CSS-scale capture. */
+    readonly scale: number;
+}
+/** One deterministic action the location tier performs on a located node. */
+export type LocatorAction = {
+    readonly kind: 'tap' | 'doubleTap' | 'check' | 'uncheck' | 'clear' | 'focus' | 'hover' | 'scrollIntoView';
+} | {
+    readonly kind: 'longPress';
+    readonly durationMs?: number;
+} | {
+    readonly kind: 'fill';
+    readonly value: string;
+    readonly sensitive: boolean;
+} | {
+    readonly kind: 'press';
+    readonly key: string;
+} | {
+    readonly kind: 'selectOption';
+    readonly value: SelectOption;
+} | {
+    readonly kind: 'setInputFiles';
+    readonly paths: readonly string[];
+} | {
+    readonly kind: 'dragTo';
+    readonly target: NodeRef;
+} | {
+    readonly kind: 'swipe';
+    readonly direction: ScrollDirection;
+    readonly momentum?: Momentum;
+};
+/** The closed backend error code set; the type is derived from it, so the two cannot drift. */
+export declare const BACKEND_ERROR_CODES: readonly ['NODE_STALE', 'FRAME_NOT_FOUND', 'FRAME_AMBIGUOUS', 'NOT_ACTIONABLE', 'ACTION_MAY_HAVE_COMMITTED', 'OPERATION_TIMEOUT', 'CANCELLED', 'UNSUPPORTED_CAPABILITY', 'INVALID_STATE', 'BACKEND_FAILURE'];
+export type BackendErrorCode = (typeof BACKEND_ERROR_CODES)[number];
+/**
+ * The only codes that may be retryable: both describe a repeatable read. Any
+ * other retryable claim, from this module's class or a foreign copy of it, is
+ * coerced to a non-retryable `BACKEND_FAILURE`.
+ */
+export declare const RETRYABLE_BACKEND_ERROR_CODES: ReadonlySet<BackendErrorCode>;
+/**
+ * The error contract a backend throws across the seam. Retryability is closed
+ * to `RETRYABLE_BACKEND_ERROR_CODES`; any other retryable claim is coerced to
+ * a non-retryable `BACKEND_FAILURE` so a backend can never talk the harness
+ * into repeating an action that may have committed.
+ */
+export declare class BackendError extends Error {
+    readonly code: BackendErrorCode;
+    readonly retryable: boolean;
+    constructor(code: BackendErrorCode, message: string, options: {
+        retryable: boolean;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/backend/contract.d.ts.map

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