@e2edev/e2e 0.2.0

package/dist/agent/model/sdk.js

@@ -0,0 +1,258 @@
+/**
+ * AI SDK adapter (spec 05-config.md). One implementation serves every
+ * provider: a `provider/model-id` reference resolves through the AI Gateway,
+ * and a caller-supplied AI SDK model instance (`openai('gpt-4o')`, a local
+ * provider, a scripted test model) is used directly. Everything after model
+ * construction — bounded requests, closed-grammar validation, usage and error
+ * translation — is provider-independent.
+ */
+import { GATEWAY_API_KEY_ENV, } from '../../config/agent.js';
+import { aiSdk, loadAiSdk } from '../ai-sdk.js';
+import { packageVersion } from '../../internal/package-version.js';
+import { AgentError } from '../error.js';
+import { imageTokenUpperBound, ModelOutputInvalidError, tokenUpperBound, } from './adapter.js';
+/** Default AI Gateway base URL used when no endpoint override is configured. */
+const DEFAULT_GATEWAY_ENDPOINT = 'https://ai-gateway.vercel.sh/v4/ai';
+const PROVIDER_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * Provider transport retries; distinct from runner-owned model-call budget.
+ *
+ * Rate limits and 5xx bursts are the dominant cause of spurious agent-step
+ * failures, and the SDK only retries errors the provider marked retryable,
+ * honoring `retry-after` before its own exponential backoff. Raising the SDK
+ * default of 2 costs nothing on a healthy provider: `timeout` below is merged
+ * into the signal the retry loop waits on, so the step deadline — not the
+ * attempt count — bounds the whole chain.
+ */
+const TRANSPORT_RETRIES = 5;
+/** Creates the adapter for one resolved model, or fails with MODEL_UNAVAILABLE. */
+export function createModelAdapter(model) {
+    if (model === undefined) {
+        throw new AgentError('MODEL_UNAVAILABLE', 'the agent fixture requires model configuration: set agent.model or E2E_MODEL');
+    }
+    const { endpoint, flavor } = validateModel(model);
+    const adapterVersion = packageVersion(import.meta.url, '../../../package.json', '0.0.0');
+    // The AI SDK is an optional peer: the language model is constructed on the
+    // first call, after the loader has resolved (or clearly refused) it.
+    let languageModel;
+    return {
+        provenance: {
+            provider: model.provider,
+            model: model.id,
+            endpoint,
+            adapterVersion: `${flavor}/${adapterVersion}`,
+        },
+        async generate(call) {
+            const { generateText, jsonSchema, Output } = await loadAiSdk();
+            languageModel ??= instantiate(model).languageModel;
+            const images = call.images ?? [];
+            const inputBound = tokenUpperBound(call.system) +
+                tokenUpperBound(call.prompt) +
+                images.reduce((total, image) => total + imageTokenUpperBound(image), 0);
+            if (inputBound > call.maxInputTokens) {
+                throw new AgentError('STEP_BUDGET_EXHAUSTED', `model input upper bound ${inputBound} exceeds limits.maxModelTokensPerCall ${call.maxInputTokens}`);
+            }
+            let issue;
+            const schema = call.schema;
+            const settings = {
+                model: languageModel,
+                system: call.system,
+                // Text-only calls keep the plain prompt form; images require the
+                // multi-part message form, and both must carry the same instruction
+                // text in the same position relative to the system policy.
+                ...(images.length === 0
+                    ? { prompt: call.prompt }
+                    : { messages: [userMessage(call.prompt, images)] }),
+                maxOutputTokens: call.maxOutputTokens,
+                temperature: 0,
+                maxRetries: TRANSPORT_RETRIES,
+                abortSignal: call.signal,
+                timeout: call.timeoutMs,
+            };
+            try {
+                if (schema === undefined) {
+                    const result = await generateText(settings);
+                    const parsed = parseJsonObject(result.text);
+                    const validation = call.validate(parsed);
+                    if (!validation.ok) {
+                        throw new ModelOutputInvalidError(validation.issue, { rawText: result.text });
+                    }
+                    return { value: validation.value, usage: readUsage(result, inputBound) };
+                }
+                const result = await generateText({
+                    ...settings,
+                    output: Output.object({
+                        schema: jsonSchema(schema, {
+                            validate: (value) => {
+                                const validation = call.validate(value);
+                                if (validation.ok)
+                                    return { success: true, value: validation.value };
+                                issue = validation.issue;
+                                return { success: false, error: new Error(validation.issue) };
+                            },
+                        }),
+                        name: call.schemaName,
+                    }),
+                });
+                const output = result.output;
+                if (output === undefined) {
+                    throw new ModelOutputInvalidError('provider returned no structured output');
+                }
+                return { value: output, usage: readUsage(result, inputBound) };
+            }
+            catch (cause) {
+                throw translateModelError(cause, issue, call.signal);
+            }
+        },
+    };
+}
+/**
+ * Builds the one user message of a vision call: instruction text first, then
+ * the image parts it refers to, so the text framing the pixels as data is read
+ * before them.
+ */
+function userMessage(prompt, images) {
+    return {
+        role: 'user',
+        content: [
+            { type: 'text', text: prompt },
+            // A file part with an image media type, not the deprecated `image` part.
+            ...images.map((image) => ({
+                type: 'file',
+                data: image.data,
+                mediaType: image.mediaType,
+            })),
+        ],
+    };
+}
+/**
+ * Builds the bare AI SDK language model for one resolved model reference, for
+ * callers that drive the SDK directly (the default step executor) rather than
+ * through the adapter. Fails with MODEL_UNAVAILABLE exactly like the adapter.
+ * Gateway references require the AI SDK to be loaded (loadAiSdk) first; model
+ * instances never touch it.
+ */
+export function instantiateLanguageModel(model) {
+    return instantiate(model).languageModel;
+}
+/**
+ * Validates one resolved model and derives its report provenance without
+ * touching the AI SDK, so an adapter can be constructed — and refuse clearly —
+ * before the optional peer dependency is ever loaded.
+ */
+function validateModel(model) {
+    if (model.kind === 'instance') {
+        // The instance owns its transport; the report records that the endpoint is
+        // whatever the provider package defaults to.
+        return { endpoint: 'provider-default', flavor: 'ai-sdk' };
+    }
+    if (!PROVIDER_PATTERN.test(model.provider)) {
+        throw new AgentError('MODEL_UNAVAILABLE', `unknown model provider "${model.provider}"; expected a gateway provider ID or an AI SDK model instance`);
+    }
+    if (model.apiKey === undefined) {
+        throw new AgentError('MODEL_UNAVAILABLE', `no model credential: set ${model.apiKeyEnv} or ${GATEWAY_API_KEY_ENV}`);
+    }
+    return { endpoint: model.endpoint ?? DEFAULT_GATEWAY_ENDPOINT, flavor: 'ai-gateway' };
+}
+/** Builds the AI SDK language model for one validated resolved model. */
+function instantiate(model) {
+    if (model.kind === 'instance')
+        return { languageModel: model.model };
+    const { endpoint } = validateModel(model);
+    const gateway = aiSdk().createGateway({ apiKey: model.apiKey, baseURL: endpoint });
+    return { languageModel: gateway.languageModel(`${model.provider}/${model.id}`) };
+}
+function readUsage(result, inputBound) {
+    const inputTokens = result.usage?.inputTokens;
+    const outputTokens = result.usage?.outputTokens;
+    const estimatedCostUsd = readCost(result.providerMetadata);
+    if (typeof inputTokens === 'number' && typeof outputTokens === 'number') {
+        return { inputTokens, outputTokens, accounting: 'provider', estimatedCostUsd };
+    }
+    return {
+        inputTokens: inputBound,
+        outputTokens: tokenUpperBound(result.text ?? ''),
+        accounting: 'adapter-upper-bound',
+        estimatedCostUsd,
+    };
+}
+/**
+ * Parses exactly one JSON object from response text, tolerating a code fence.
+ * Model text is never evaluated as code.
+ */
+function parseJsonObject(text) {
+    const trimmed = text.trim();
+    const fenced = /^```(?:json)?\s*([\s\S]*?)```$/.exec(trimmed);
+    const body = (fenced?.[1] ?? trimmed).trim();
+    try {
+        return JSON.parse(body);
+    }
+    catch (cause) {
+        throw new ModelOutputInvalidError('response text is not a single JSON value', {
+            rawText: text,
+            cause,
+        });
+    }
+}
+/**
+ * The AI Gateway reports per-request cost in provider metadata when available;
+ * other providers simply lack the key. `cost` is what the gateway bills; BYOK
+ * routes bill the provider key directly and report `cost: "0"`, so fall back
+ * to `marketCost`, the list-price estimate of the same request.
+ */
+export function readCost(metadata) {
+    const billed = parseCost(metadata?.['gateway']?.['cost']);
+    if (billed !== undefined && billed > 0)
+        return billed;
+    return parseCost(metadata?.['gateway']?.['marketCost']) ?? billed;
+}
+function parseCost(raw) {
+    const cost = typeof raw === 'string' ? Number(raw) : raw;
+    return typeof cost === 'number' && Number.isFinite(cost) && cost >= 0 ? cost : undefined;
+}
+/**
+ * Maps adapter and provider failures onto the closed agent error set. Runs
+ * only after `generate` loaded the SDK, so the cached module is available for
+ * the error-class checks.
+ */
+function translateModelError(rawCause, issue, signal) {
+    const { APICallError, NoObjectGeneratedError } = aiSdk();
+    const cause = unwrapRetry(rawCause);
+    if (cause instanceof AgentError)
+        return cause;
+    // Only an aborted attempt is a cancellation. A request that exceeded the
+    // remaining step budget is a timeout, which is a test failure (06-cli.md).
+    if (signal.aborted) {
+        return new AgentError('CANCELLED', 'model call cancelled', { cause });
+    }
+    if (isAbort(cause)) {
+        return new AgentError('STEP_TIMEOUT', 'model call exceeded the remaining step timeout', { cause });
+    }
+    if (NoObjectGeneratedError.isInstance(cause)) {
+        return new ModelOutputInvalidError(issue ?? 'provider response did not match the closed response grammar', { ...(cause.text !== undefined ? { rawText: cause.text } : {}), cause });
+    }
+    if (APICallError.isInstance(cause)) {
+        return new AgentError('MODEL_PROVIDER_FAILED', `model provider failed: ${cause.message}`, {
+            cause,
+        });
+    }
+    return new AgentError('MODEL_PROVIDER_FAILED', `model provider failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+}
+/**
+ * Unwraps a spent transport retry chain to the attempt that actually failed,
+ * because the wrapper's message names the retry reason rather than the failure.
+ * A chain cut short by the deadline stays wrapped so it classifies as an abort.
+ */
+function unwrapRetry(cause) {
+    const { RetryError } = aiSdk();
+    if (!RetryError.isInstance(cause) || cause.reason === 'abort')
+        return cause;
+    return cause.lastError ?? cause;
+}
+function isAbort(cause) {
+    const { RetryError } = aiSdk();
+    if (RetryError.isInstance(cause) && cause.reason === 'abort')
+        return true;
+    return cause instanceof Error && (cause.name === 'AbortError' || cause.name === 'TimeoutError');
+}
+//# sourceMappingURL=sdk.js.map

package/dist/agent/model/sdk.js.map

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

package/dist/agent/observation.d.ts

@@ -0,0 +1,70 @@
+/** Observation capture, redaction, and model serialization (spec 09-drivers.md, 14-security.md). */
+import type { Observation, ObservationPixels, SemanticNode } from '../backend/surface.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 {
+    readonly revision: string;
+    /** Redacted, size-bounded serialization sent to the model. */
+    readonly text: string;
+    readonly bytes: number;
+    readonly nodes: ReadonlyMap<string, SemanticNode>;
+    readonly viewport: {
+        readonly width: number;
+        readonly height: number;
+        readonly scale: number;
+    };
+    readonly truncated: boolean;
+    /** Present only when the backend captured pixels and masking checks out. */
+    readonly pixels?: AgentPixels | undefined;
+    /** Set when captured pixels were dropped instead of being sent. */
+    readonly pixelsWithheld?: PixelsWithheld | undefined;
+}
+/**
+ * Turns one raw backend observation into redacted model input.
+ *
+ * Pixels whose masking the backend cannot prove (fewer masked regions than
+ * secure nodes) are withheld before they reach a model or disk; the semantic
+ * tree never carries secure values. Registered secret values are additionally
+ * replaced by their stable secret name.
+ */
+export declare function prepareObservation(observation: Observation, options: {
+    redact: (text: string) => string;
+    maxBytes: number;
+    testIdAttribute: string;
+}): AgentObservation;
+/**
+ * What the screen looks like, independent of which observation looked at it.
+ *
+ * Two things are dropped. Node ids, because they are minted per observation, so
+ * two looks at a screen that has not moved would never render identically. And
+ * the focus state, because focus moves on its own — the platform settling it
+ * after load, a script claiming it, a widget stealing it — without the screen
+ * having changed in any way a judgment could answer differently about. Leaving
+ * it in meant a genuinely static screen could still spend a second model call.
+ *
+ * Lives next to `formatNode` so the line grammar keeps one owner.
+ */
+export declare function observationShape(observation: AgentObservation): string;
+/** What a settle loop needs from its step: the remaining clock and cancellation. */
+interface SettleClock {
+    remainingMs(): number;
+    readonly signal: AbortSignal;
+}
+/**
+ * Captures until the screen shape holds still, bounded by a short ceiling and
+ * the step clock. An observation taken right after an action can be a
+ * snapshot the app is still reacting to — a fetch-backed mutation re-renders
+ * long after the action resolves — and acting or judging on it repeats
+ * actions and passes steps on pre-render state. The executor-facing observe
+ * (act.ts) settles through this loop, and replay's pre-action looks and the
+ * cache session's probes reach it through that same observe, so the pacing
+ * can never drift between them.
+ */
+export declare function settleObservation<T>(capture: () => Promise<T>, shapeOf: (value: T) => string, clock: SettleClock): Promise<T>;
+export {};
+//# sourceMappingURL=observation.d.ts.map

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

@@ -0,0 +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"}

package/dist/agent/observation.js

@@ -0,0 +1,174 @@
+/** Observation capture, redaction, and model serialization (spec 09-drivers.md, 14-security.md). */
+import { collapseText } from '../internal/text.js';
+import { sleep } from '../internal/time.js';
+/** Appended when the node walk stopped at the observation byte budget. */
+const TRUNCATION_MARKER = '[observation truncated at the resolved observation byte limit]';
+/**
+ * Turns one raw backend observation into redacted model input.
+ *
+ * Pixels whose masking the backend cannot prove (fewer masked regions than
+ * secure nodes) are withheld before they reach a model or disk; the semantic
+ * tree never carries secure values. Registered secret values are additionally
+ * replaced by their stable secret name.
+ */
+export function prepareObservation(observation, options) {
+    const nodes = new Map();
+    indexNodes(observation.tree, nodes);
+    const redact = options.redact;
+    const lines = [];
+    const encoder = new TextEncoder();
+    // The marker is reserved up front so a truncated observation still fits the
+    // budget; the budget is what keeps the request under the token ceiling.
+    const markerBytes = encoder.encode(`${TRUNCATION_MARKER}\n`).byteLength;
+    const budget = Math.max(0, options.maxBytes - markerBytes);
+    let bytes = 0;
+    let truncated = false;
+    const emit = (node, depth) => {
+        if (truncated)
+            return;
+        const line = formatNode(node, depth, redact, options.testIdAttribute);
+        const size = encoder.encode(`${line}\n`).byteLength;
+        if (lines.length > 0 && bytes + size > budget) {
+            truncated = true;
+            return;
+        }
+        bytes += size;
+        lines.push(line);
+        for (const child of node.children ?? [])
+            emit(child, depth + 1);
+    };
+    emit(observation.tree, 0);
+    if (truncated)
+        lines.push(TRUNCATION_MARKER);
+    const text = lines.join('\n');
+    // Every emitted line was measured with its newline; the join has one fewer
+    // and the marker was measured up front, so the size is known without a
+    // second pass over the whole tree text.
+    const textBytes = Math.max(0, bytes + (truncated ? markerBytes : 0) - 1);
+    const pixels = clearPixels(observation);
+    return {
+        revision: observation.revision,
+        text,
+        bytes: textBytes,
+        nodes,
+        viewport: observation.viewport,
+        truncated,
+        ...(pixels.cleared === undefined ? {} : { pixels: pixels.cleared }),
+        ...(pixels.withheld === undefined ? {} : { pixelsWithheld: pixels.withheld }),
+    };
+}
+/**
+ * Clears captured pixels for model input, or withholds them.
+ *
+ * Every secure node the backend observed must be covered by a masked region.
+ * When it is not, the backend masked less than it saw and the image cannot be
+ * proven redacted, so it is dropped exactly like an incompletely redacted
+ * artifact (14-security.md) — the semantic tree still goes out.
+ */
+function clearPixels(observation) {
+    const pixels = observation.pixels;
+    if (pixels === undefined)
+        return {};
+    const { secureNodeCount, maskedRegionCount } = observation.redaction;
+    if (maskedRegionCount < secureNodeCount)
+        return { withheld: 'MASKING_UNPROVEN' };
+    return { cleared: { ...pixels, maskedRegionCount, bytes: pixels.data.byteLength } };
+}
+/** Depth beyond this renders flat; deep chrome must not buy tokens with spaces. */
+const MAX_INDENT_DEPTH = 10;
+/**
+ * Renders one node as `#id role "name" text="..." [states]`. Role-less text
+ * holders omit the role token entirely: on a large screen they are half the
+ * lines, and the model needs their text, not a filler word.
+ */
+function formatNode(node, depth, redact, testIdAttribute) {
+    const parts = [`#${node.ref.id}`];
+    if (node.role !== undefined && node.role !== '')
+        parts.push(node.role);
+    if (node.name !== undefined && node.name !== '')
+        parts.push(JSON.stringify(redact(node.name)));
+    const text = node.text === undefined ? '' : collapseText(node.text);
+    if (text !== '' && text !== node.name)
+        parts.push(`text=${JSON.stringify(redact(text))}`);
+    // Disambiguators the model needs when role and name repeat. The backend has
+    // already reduced href to origin and path.
+    const testId = node.attributes?.[testIdAttribute];
+    if (testId !== undefined && testId !== '')
+        parts.push(`testid=${JSON.stringify(testId)}`);
+    const href = node.attributes?.['href'];
+    if (href !== undefined && href !== '')
+        parts.push(`href=${JSON.stringify(redact(href))}`);
+    const placeholder = node.attributes?.['placeholder'];
+    if (placeholder !== undefined && placeholder !== '' && (node.name ?? '') === '') {
+        parts.push(`placeholder=${JSON.stringify(redact(placeholder))}`);
+    }
+    if (node.states?.secure === true) {
+        parts.push('value=<secure>');
+    }
+    else if (node.value !== undefined && node.value !== '') {
+        parts.push(`value=${JSON.stringify(redact(node.value))}`);
+    }
+    if (node.inputPurpose !== undefined && node.inputPurpose !== 'none') {
+        parts.push(`purpose=${node.inputPurpose}`);
+    }
+    const states = Object.entries(node.states ?? {})
+        .filter(([, value]) => value === true)
+        .map(([key]) => key);
+    if (states.length > 0)
+        parts.push(`[${states.join(' ')}]`);
+    return `${' '.repeat(Math.min(depth, MAX_INDENT_DEPTH))}${parts.join(' ')}`;
+}
+/**
+ * What the screen looks like, independent of which observation looked at it.
+ *
+ * Two things are dropped. Node ids, because they are minted per observation, so
+ * two looks at a screen that has not moved would never render identically. And
+ * the focus state, because focus moves on its own — the platform settling it
+ * after load, a script claiming it, a widget stealing it — without the screen
+ * having changed in any way a judgment could answer differently about. Leaving
+ * it in meant a genuinely static screen could still spend a second model call.
+ *
+ * Lives next to `formatNode` so the line grammar keeps one owner.
+ */
+export function observationShape(observation) {
+    return observation.text
+        .replaceAll(/(^|\n)(\s*)#\S+/g, '$1$2')
+        .replaceAll(/ \[([^\]]*)\]/g, (_match, states) => {
+        const stable = states.split(' ').filter((state) => state !== 'focused');
+        return stable.length === 0 ? '' : ` [${stable.join(' ')}]`;
+    });
+}
+/** Poll interval and ceiling for shape-stability settling. */
+const SETTLE_POLL_MS = 75;
+const SETTLE_TIMEOUT_MS = 1_000;
+/**
+ * Captures until the screen shape holds still, bounded by a short ceiling and
+ * the step clock. An observation taken right after an action can be a
+ * snapshot the app is still reacting to — a fetch-backed mutation re-renders
+ * long after the action resolves — and acting or judging on it repeats
+ * actions and passes steps on pre-render state. The executor-facing observe
+ * (act.ts) settles through this loop, and replay's pre-action looks and the
+ * cache session's probes reach it through that same observe, so the pacing
+ * can never drift between them.
+ */
+export async function settleObservation(capture, shapeOf, clock) {
+    let value = await capture();
+    let shape = shapeOf(value);
+    const deadlineMs = Date.now() + SETTLE_TIMEOUT_MS;
+    while (Date.now() < deadlineMs && clock.remainingMs() > SETTLE_POLL_MS) {
+        await sleep(SETTLE_POLL_MS, clock.signal);
+        value = await capture();
+        const next = shapeOf(value);
+        const stable = next === shape;
+        shape = next;
+        if (stable)
+            break;
+    }
+    return value;
+}
+function indexNodes(node, into) {
+    into.set(node.ref.id, node);
+    for (const child of node.children ?? [])
+        indexNodes(child, into);
+}
+//# sourceMappingURL=observation.js.map

package/dist/agent/observation.js.map

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

package/dist/agent/phases.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared per-phase machinery for agent step execution. `Invocation` (the
+ * locate/judgment tier) and `ActDispatch` (the executor socket) both compose
+ * these, so event recording, `--debug` buckets, tracing, deadline semantics,
+ * and observation race-hardening cannot drift between the two paths.
+ */
+import { type Observation, type OperationContext } from '../backend/surface.ts';
+import type { DebugTrace } from '../internal/debug.ts';
+import { type Deadline } from '../internal/time.ts';
+import type { LocatorEngine } from '../locator/engine.ts';
+import type { StepEvent, StepRecorder } from '../run/steps.ts';
+/**
+ * One backend operation's budget: `actionTimeout`, capped by the step clock.
+ * Bounding each call independently is what keeps a single screen that never
+ * settles from consuming the whole step: the hang costs one action timeout and
+ * a clearly attributed failure, not the test budget.
+ */
+export declare function boundedOperation(engine: LocatorEngine, actionTimeout: number, deadline: Deadline): OperationContext;
+/** Records one policy decision as a child event of the current step. */
+export declare function recordPolicyEvent(steps: StepRecorder, name: string, decision: 'allowed' | 'denied', code?: string): void;
+/** The step recorder and optional debug trace a phase reports into. */
+export interface PhaseHost {
+    readonly steps: StepRecorder;
+    readonly debug?: DebugTrace | undefined;
+}
+/** One instrumented phase: the event kind it records and the debug bucket it feeds. */
+export interface PhaseSpec {
+    /** Public API name of the enclosing step, e.g. `agent.assert`. */
+    readonly api: string;
+    readonly kind: StepEvent['kind'];
+    readonly phase: 'agent.observe' | 'agent.model' | 'agent.action' | 'agent.cache';
+    readonly name?: string;
+}
+/**
+ * Runs one phase with uniform accounting: a child event on success and
+ * failure, one debug bucket, and translation onto the closed agent error set.
+ * Every observe/model/action phase of every agent step goes through here so
+ * the records cannot drift apart.
+ */
+export declare function instrumentPhase<Value>(host: PhaseHost, spec: PhaseSpec, body: () => Promise<Value>, detail?: (value: Value) => Partial<StepEvent>): Promise<Value>;
+/**
+ * Fails when the step clock has run out.
+ *
+ * `cause` carries the failure that was being handled when the clock was found
+ * to be out, so a step that timed out mid-operation still says what the
+ * operation reported.
+ */
+export declare function checkStepClock(options: {
+    readonly signal: AbortSignal;
+    readonly deadline: Deadline;
+    readonly api: string;
+    readonly timeoutMs: number;
+    readonly cause?: unknown;
+}): void;
+/**
+ * Captures one raw observation, re-capturing while the backend reports a
+ * retryable failure and the step clock allows. A screen that navigates as it is
+ * read (a redirect, a hydration swap, a form submit still committing) makes
+ * the capture lose its document; that is a race, not a broken app, so it is
+ * re-read rather than surfaced as a failed call. `guard` is the caller's
+ * clock check, so a capture that outlives the deadline reports the step's own
+ * timeout rather than whichever transport error the truncated budget produced.
+ */
+export declare function retryingObserve(options: {
+    readonly observe: (operation: OperationContext) => Promise<Observation>;
+    readonly operation: () => OperationContext;
+    readonly guard: (cause?: unknown) => void;
+    readonly signal: AbortSignal;
+    readonly api: string;
+}): Promise<Observation>;
+//# sourceMappingURL=phases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"phases.d.ts","sourceRoot":"","sources":["../../src/agent/phases.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,QAAQ,GACjB,gBAAgB,CAElB;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,SAAS,GAAG,QAAQ,EAC9B,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAUN;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACzC;AAED,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,aAAa,GAAG,cAAc,GAAG,aAAa,CAAC;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,KAAK,EACzC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,EAC1B,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,SAAS,CAAC,GAC5C,OAAO,CAAC,KAAK,CAAC,CAyChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,IAAI,CAYP;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAC7C,QAAQ,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,gBAAgB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,gBAAgB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,WAAW,CAAC,CAevB"}