e2e 0.21.1 → 0.21.2

package/README.md

@@ -58,10 +58,12 @@ and Flutter, each a standalone project with a passing suite.
 | [`@e2e-dev/mobile`](https://www.npmjs.com/package/@e2e-dev/mobile) | iOS and Android engine: simulators and emulators through agent-device. |
 | [`@e2e-dev/github`](https://www.npmjs.com/package/@e2e-dev/github) | Reporter that posts results as a pull request comment. |
 | [`@e2e-dev/kernel`](https://www.npmjs.com/package/@e2e-dev/kernel) | Kernel hosted browsers for the web engine. |
+| [`@e2e-dev/lightpanda`](https://www.npmjs.com/package/@e2e-dev/lightpanda) | Lightpanda, the open-source headless browser, started per run for the web engine. |
 | [`@e2e-dev/limrun`](https://www.npmjs.com/package/@e2e-dev/limrun) | Limrun hosted iOS simulators and Android emulators for mobile tests. |
 | [`@e2e-dev/eas`](https://www.npmjs.com/package/@e2e-dev/eas) | EAS Simulators hosted iOS simulators and Android emulators for the mobile engine. |
 | [`@e2e-dev/smol`](https://www.npmjs.com/package/@e2e-dev/smol) | smol machines browsers for the web engine: by default, each attempt branches a warm Chromium microVM. |
 | [`@e2e-dev/decision`](https://e2e.tester.army/docs/decision-models) | Decision-model executors for bounded semantic actions and assertions. |
+| [`@e2e-dev/testmu`](https://www.npmjs.com/package/@e2e-dev/testmu) | TestMu AI (formerly LambdaTest) hosted Android emulators, iOS simulators, and real devices for the mobile engine. |
 
 ## Documentation
 

package/dist/.build.json

@@ -1 +1 @@
-{"version":"0.21.1"}
+{"version":"0.21.2"}

package/dist/agent/act-validation.js

@@ -85,6 +85,7 @@ export function validateParams(params) {
         throw new TestError('INVALID_ARGUMENT', `agent.act params are ${bytes} canonical bytes; the maximum is ${MAX_PARAMS_BYTES}`);
     }
     return {
+        // oxlint-disable-next-line e2e/no-unchecked-json -- canonical is this function's own JSON.stringify of a plain object validateJsonValue just checked
         projected: JSON.parse(canonical),
         secrets: found.secrets,
         templates: found.templates,

package/dist/agent/act.js

@@ -28,7 +28,7 @@ import { resolveBoundedBudget, resolveTimeout } from './call-options.js';
 import { RUNTIME_CODES } from './executor.js';
 import { projectPriorSteps, serializeLedger } from './ledger.js';
 import { tokenUpperBound } from './model/adapter.js';
-import { instantiateLanguageModel } from './model/sdk.js';
+import { instantiateLanguageModel, isUnservedModelError, unservedModelError } from './model/sdk.js';
 import { ObservationFeed } from './observation-feed.js';
 import { recordPolicyEvent } from './phases.js';
 import { appLocation } from '../cache/route.js';
@@ -111,7 +111,10 @@ agent = runtime.select(raw.agent)) {
                 verdict = await dispatch.run();
             }
             catch (cause) {
-                throw dispatch.settleThrown(toAgentError(cause));
+                const error = unservedModelError(cause) ?? toAgentError(cause);
+                if (isUnservedModelError(error))
+                    runtime.reportUnservedModel(error);
+                throw dispatch.settleThrown(error);
             }
             const evidence = await dispatch.captureEvidence();
             dispatch.settle(validateVerdict(verdict, agent.executor.name), evidence);
@@ -309,7 +312,8 @@ class ActDispatch {
     }
     /** Hands the settled outcome to the cache session, which stages, evicts, or does nothing. */
     async conclude(outcome) {
-        await this.stepCache?.conclude(outcome, this.explanation);
+        const model = this.agent.config.model;
+        await this.stepCache?.conclude(outcome, this.explanation, model === undefined ? undefined : { provider: model.provider, model: model.id });
     }
     /**
      * Keeps a redacted screenshot as an assert step's evidence once the

package/dist/agent/action-dispatcher.js

@@ -9,6 +9,7 @@
  * nothing else in the step changes. Project tools run through the same budget
  * and queue as `runTool`.
  */
+import { isKeyModifier, KEY_MODIFIERS } from '../engine/contract.js';
 import { asEngineError, TestError } from '../internal/errors.js';
 import { requireKey } from '../internal/keys.js';
 import { clampToViewport, requireFinitePoint, viewportShare } from '../internal/geometry.js';
@@ -16,6 +17,7 @@ import { resolveNavigationUrl } from '../internal/urls.js';
 import { PROJECT_TOOL_EVENT_PREFIX } from './action-names.js';
 import { containerKey, describeAction } from './actions.js';
 import { describePosition } from '../cache/relocate.js';
+import { isTapActionName } from '../cache/trace.js';
 import { derivedReason } from './derived.js';
 import { AgentError } from './error.js';
 import { resolveScrollTarget } from './scroll-target.js';
@@ -68,6 +70,23 @@ const NODE_ACTION_KINDS = {
     hover: 'hover',
     scrollTo: 'scrollIntoView',
 };
+/**
+ * The `modifiers` of a tap-family action, validated: distinct key modifiers,
+ * as the test API's `tap({ modifiers })` takes them. An empty list holds
+ * nothing and is dropped, so the recorded action stays clean.
+ */
+function requireClickModifiers(value, verb) {
+    if (!Array.isArray(value) || !value.every(isKeyModifier)) {
+        throw new TestError('INVALID_ARGUMENT', `${verb}() modifiers must be an array of ${KEY_MODIFIERS.join(', ')}`);
+    }
+    const modifiers = [];
+    for (const modifier of value) {
+        if (modifiers.includes(modifier))
+            throw new TestError('INVALID_ARGUMENT', `${verb}() names a modifier twice`);
+        modifiers.push(modifier);
+    }
+    return modifiers.length === 0 ? undefined : modifiers;
+}
 export class ActionDispatcher {
     runtime;
     accounting;
@@ -90,10 +109,10 @@ export class ActionDispatcher {
         this.queue = queue;
         this.options = options;
         this.actions = {
-            tap: (target) => this.nodeVerb('tap', target),
-            doubleTap: (target) => this.nodeVerb('doubleTap', target),
+            tap: (target, click) => this.nodeVerb('tap', target, click),
+            doubleTap: (target, click) => this.nodeVerb('doubleTap', target, click),
             longPress: (target) => this.nodeVerb('longPress', target),
-            secondaryTap: (target) => this.nodeVerb('secondaryTap', target),
+            secondaryTap: (target, click) => this.nodeVerb('secondaryTap', target, click),
             hover: (target) => this.nodeVerb('hover', target),
             type: (target, value) => this.type(target, value),
             typeSecret: (target, name) => this.typeSecret(target, name),
@@ -167,8 +186,9 @@ export class ActionDispatcher {
         });
     }
     /** One node verb that carries nothing but its target: a tap or one of its variants, a hover, a scroll into view. */
-    nodeVerb(name, target) {
-        return this.commitTargeted(NODE_ACTION_KINDS[name], target, (node) => this.performNode(name, node));
+    nodeVerb(name, target, options) {
+        const modifiers = options?.modifiers === undefined ? undefined : requireClickModifiers(options.modifiers, name);
+        return this.commitTargeted(NODE_ACTION_KINDS[name], target, (node) => this.performNode(name, node, modifiers));
     }
     /**
      * Taps or hovers one viewport point, routed onto the tree in queue order
@@ -239,9 +259,11 @@ export class ActionDispatcher {
     get verbs() {
         return this.runtime.target.verbs;
     }
-    async performNode(name, node) {
-        await this.session.perform(node.ref, { kind: NODE_ACTION_KINDS[name] }, this.accounting.actionOperation());
-        return { name, node };
+    async performNode(name, node, modifiers) {
+        const kind = NODE_ACTION_KINDS[name];
+        const action = modifiers !== undefined && isTapActionName(kind) ? { kind, modifiers } : { kind };
+        await this.session.perform(node.ref, action, this.accounting.actionOperation());
+        return { name, node, ...(modifiers === undefined ? {} : { modifiers }) };
     }
     /**
      * Sets a checkbox, switch, or radio to a state. The engine's `check` and

package/dist/agent/actions.d.ts

@@ -11,11 +11,13 @@
 import type { ViewportPoint, ViewportSize } from '../engine/surface.ts';
 import { type NodeRedaction, type RedactedNode } from './observation.ts';
 import { type NodeActionName, type PointActionName, type TraceTargetDescriptor, type TracePosition } from '../cache/trace.ts';
+import type { KeyModifier } from '../engine/contract.ts';
 import type { ScrollDirection } from '../types.ts';
 /** One committed grammar action, addressed by the node it actually ran against. */
 export type RecordableAction = ({
     readonly name: NodeActionName;
     readonly node: RedactedNode;
+    readonly modifiers?: readonly KeyModifier[];
 } & Placement) | ({
     readonly name: 'type';
     readonly node: RedactedNode;

package/dist/agent/actions.js

@@ -119,8 +119,11 @@ export function describeAction(action, redaction) {
     const where = describeForSummary(target);
     const safe = (value) => quote(redaction.redact(sanitizeText(value)));
     const prose = (() => {
-        if (isNodeAction(action))
-            return NODE_ACTION_PROSE[action.name](where);
+        if (isNodeAction(action)) {
+            const said = NODE_ACTION_PROSE[action.name](where);
+            const held = 'modifiers' in action ? action.modifiers : undefined;
+            return held === undefined || held.length === 0 ? said : `${said} with ${held.join('+')} held`;
+        }
         switch (action.name) {
             case 'type':
                 return `type ${safe(action.value)} into ${where}`;

package/dist/agent/error.js

@@ -114,6 +114,7 @@ export function toAgentError(cause) {
 export function isAgentError(value) {
     return (value instanceof Error &&
         AGENT_ERROR_MARKER in value &&
+        'code' in value &&
         typeof value.code === 'string' &&
         value.code in CATEGORY_BY_CODE);
 }

package/dist/agent/executor.d.ts

@@ -18,7 +18,7 @@
  */
 import type { ObservationPixels, SemanticNode, ViewportPoint, ViewportSize } from '../engine/surface.ts';
 import type { VisionDegradation, StepTurn } from '../run/steps.ts';
-import type { AgentErrorCode, JsonValue, ModelInstance, ProviderOptions, ScrollDirection, Secret, VisionMode } from '../types.ts';
+import type { AgentErrorCode, ClickOptions, JsonValue, ModelInstance, ProviderOptions, ScrollDirection, Secret, VisionMode } from '../types.ts';
 import { type AgentError } from './error.ts';
 /**
  * One step handed to an executor. `act` plans and executes a flow; `assert`
@@ -155,13 +155,18 @@ export interface ExecutorTarget {
  * fresh `observe()`.
  */
 export interface ExecutorActions {
-    tap(target: ExecutorTarget): Promise<void>;
-    /** Double-taps one node (`doubleTap` in `target.verbs`). */
-    doubleTap(target: ExecutorTarget): Promise<void>;
+    /**
+     * Taps one node. `options.modifiers` holds keys for the click, as a
+     * Shift-click extends a selection; needs `target.tapModifiers`,
+     * `UNSUPPORTED_CAPABILITY` otherwise.
+     */
+    tap(target: ExecutorTarget, options?: Pick<ClickOptions, 'modifiers'>): Promise<void>;
+    /** Double-taps one node (`doubleTap` in `target.verbs`). Takes the tap's `options.modifiers`. */
+    doubleTap(target: ExecutorTarget, options?: Pick<ClickOptions, 'modifiers'>): Promise<void>;
     /** Presses one node and holds for the engine's default duration (`longPress` in `target.verbs`). */
     longPress(target: ExecutorTarget): Promise<void>;
-    /** A right-click on a pointer surface (`secondaryTap` in `target.verbs`). */
-    secondaryTap(target: ExecutorTarget): Promise<void>;
+    /** A right-click on a pointer surface (`secondaryTap` in `target.verbs`). Takes the tap's `options.modifiers`. */
+    secondaryTap(target: ExecutorTarget, options?: Pick<ClickOptions, 'modifiers'>): Promise<void>;
     /** Moves the pointer over one node without pressing (`hover` in `target.verbs`). */
     hover(target: ExecutorTarget): Promise<void>;
     type(target: ExecutorTarget, value: string): Promise<void>;
@@ -370,11 +375,14 @@ export interface StepExecutorContext {
      * The target this step runs on. Tool packs scope themselves by its platform;
      * `verbs` is the subset of the action grammar the engine declared, so an
      * executor offers a model exactly the vocabulary the surface can honor.
+     * `tapModifiers` is true when `tap`, `doubleTap`, and `secondaryTap` accept
+     * `modifiers`.
      */
     readonly target: {
         readonly name: string;
         readonly platform: string;
         readonly verbs: ReadonlySet<ExecutorVerb>;
+        readonly tapModifiers: boolean;
     };
     /**
      * Present when a cached replay ran part of this step before handing it

package/dist/agent/index.js

@@ -14,6 +14,7 @@ import { rejectUnknownOptions } from '../internal/options.js';
 import { describeIssue, requireStandardSchema } from '../internal/standard-schema.js';
 import { sleep } from '../internal/time.js';
 import { AgentError, isAgentError, toAgentError } from './error.js';
+import { isUnservedModelError, unservedModelError } from './model/sdk.js';
 import { resolveBoundedBudget, resolveTimeout } from './call-options.js';
 import { runActStep, runAssertStep } from './act.js';
 import { observationShape } from './observation.js';
@@ -82,7 +83,10 @@ export function createAgentFixture(runtime) {
             return await body(invocation);
         }
         catch (cause) {
-            throw toAgentError(cause);
+            const error = unservedModelError(cause) ?? toAgentError(cause);
+            if (isUnservedModelError(error))
+                runtime.reportUnservedModel(error);
+            throw error;
         }
         finally {
             invocation.finish();

package/dist/agent/invocation.d.ts

@@ -19,6 +19,7 @@ import type { ArtifactSink } from '../run/fixtures.ts';
 import type { SecretExposure } from '../run/secrecy.ts';
 import type { StepRecord, StepRecorder } from '../run/steps.ts';
 import type { VisionMode } from '../types.ts';
+import { AgentError } from './error.ts';
 import type { ExecutorAttempt, StepExecutor } from './executor.ts';
 import { type ModelAdapter } from './model/adapter.ts';
 import { type AgentObservation } from './observation.ts';
@@ -66,6 +67,8 @@ export interface AgentContext {
      * the run's. An unknown name is `INVALID_ARGUMENT`.
      */
     readonly select: (name: string | undefined) => AgentSelection;
+    /** Reports a model the provider refused, met by a step's call; the run stops once over it. */
+    readonly reportUnservedModel: (error: AgentError) => void;
     readonly config: ResolvedConfig;
     /** The target this attempt runs on. */
     readonly target: StepExecutorContext['target'];

package/dist/agent/model/sdk.d.ts

@@ -8,6 +8,7 @@
  */
 import { type ResolvedModel } from '../../config/agent.ts';
 import { type SdkLanguageModel } from '../ai-sdk.ts';
+import { AgentError } from '../error.ts';
 import { type ModelAdapter } from './adapter.ts';
 /**
  * Provider transport retries; distinct from runner-owned model-call budget.
@@ -59,6 +60,10 @@ export declare function cacheTokenFields(usage: SdkUsage | undefined): {
  * the key.
  */
 export declare function readCost(metadata: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined): number | undefined;
+/** A marked failure (`internal/unserved-model.ts`) as the run-stopping `MODEL_UNAVAILABLE` the fixture reports once, or that error itself; undefined for any other failure. */
+export declare function unservedModelError(cause: unknown): AgentError | undefined;
+/** True for an error `unservedModelError` built, in this realm or another. */
+export declare function isUnservedModelError(value: unknown): value is AgentError;
 /**
  * The remedy a provider failure points at, when its shape names one: a
  * rejected credential, or a conversation the provider kept no state for.

package/dist/agent/model/sdk.js

@@ -7,11 +7,12 @@
  * provider-independent.
  */
 import { providerFailureMessage, withHint } from '../../internal/errors.js';
+import { markUnservedModel, unservedModelExplanation } from '../../internal/unserved-model.js';
 import { missingModelError } from '../../config/agent.js';
 import { aiSdk, asSdkLanguageModel, loadAiSdk } from '../ai-sdk.js';
 import { MODEL_REQUEST_HEADERS } from '../../internal/client-identity.js';
 import { packageVersion } from '../../internal/package-version.js';
-import { AgentError } from '../error.js';
+import { AgentError, isAgentError } from '../error.js';
 import { isContextOverflow } from './overflow.js';
 import { providerHints } from './provider-hints.js';
 import { withStallGuard } from './stall.js';
@@ -238,11 +239,27 @@ function translateModelError(rawCause, issue, signal) {
     if (isContextOverflow(cause)) {
         return new AgentError('CONTEXT_OVERFLOW', `the model request exceeded the context window: ${providerFailureMessage(cause)}`, { cause });
     }
+    const unserved = unservedModelError(cause);
+    if (unserved !== undefined)
+        return unserved;
     if (APICallError.isInstance(cause)) {
         return new AgentError('MODEL_PROVIDER_FAILED', withHint(`model provider failed: ${providerFailureMessage(cause)}`, failureHint(cause)), { cause });
     }
     return new AgentError('MODEL_PROVIDER_FAILED', `model provider failed: ${providerFailureMessage(cause)}`, { cause });
 }
+/** A marked failure (`internal/unserved-model.ts`) as the run-stopping `MODEL_UNAVAILABLE` the fixture reports once, or that error itself; undefined for any other failure. */
+export function unservedModelError(cause) {
+    if (isUnservedModelError(cause))
+        return cause;
+    const explanation = unservedModelExplanation(cause);
+    if (explanation === undefined)
+        return undefined;
+    return markUnservedModel(new AgentError('MODEL_UNAVAILABLE', explanation, { cause }), explanation);
+}
+/** True for an error `unservedModelError` built, in this realm or another. */
+export function isUnservedModelError(value) {
+    return isAgentError(value) && unservedModelExplanation(value) !== undefined;
+}
 /**
  * The remedy a provider failure points at, when its shape names one: a
  * rejected credential, or a conversation the provider kept no state for.

package/dist/agent/observation.js

@@ -145,6 +145,7 @@ export function redactNode(node, redaction) {
     }
     if (node.children !== undefined)
         redacted['children'] = node.children.map((child) => redactNode(child, redaction));
+    // oxlint-disable-next-line e2e/no-chained-type-assertions -- mints the phantom REDACTED brand once every field passed NODE_FIELDS
     return redacted;
 }
 /**

package/dist/agent/primitives.js

@@ -9,6 +9,8 @@
  * the module is safe to import from a config that never calls a model.
  */
 import { z } from 'zod';
+import { isTapActionName } from '../cache/trace.js';
+import { KEY_MODIFIERS } from '../engine/contract.js';
 import { codedMessage, hasCause, TestError } from '../internal/errors.js';
 import { isRuntimeHardStop, BLOCKABLE_CODES } from './executor.js';
 import { cacheTokenFields, readCost } from './model/sdk.js';
@@ -231,13 +233,22 @@ export function createGrammarTools(context, options = {}) {
             execute: () => inOrder(() => guard(() => present('Observed.', { expectChange: false, keyboardNote: false }))),
         }),
     };
+    const modifiers = z
+        .array(z.enum(KEY_MODIFIERS))
+        .optional()
+        .describe('Keys held while the pointer clicks: "Shift", "Control", "Alt", "Meta", or "ControlOrMeta". A Shift-click extends a selection, a Control-click (Meta on macOS) toggles one item.');
     for (const { verb, tool, lead, description, expectChange } of NODE_VERBS) {
         if (!verbs.has(verb))
             continue;
+        const holdable = context.target.tapModifiers && isTapActionName(verb);
         tools[tool] = screenTool({
-            description,
-            inputSchema: z.object({ target }),
-            execute: ({ target: id }) => acting({ done: `${lead} #${id}.`, attempt: `${tool} #${id}` }, () => context.actions[verb]({ id }), expectChange === undefined ? {} : { expectChange }),
+            description: holdable ? `${description} Pass modifiers to hold keys for the click.` : description,
+            inputSchema: holdable ? z.object({ target, modifiers }) : z.object({ target }),
+            execute: (input) => {
+                const { target: id, modifiers: held } = input;
+                const run = () => isTapActionName(verb) && held !== undefined ? context.actions[verb]({ id }, { modifiers: held }) : context.actions[verb]({ id });
+                return acting({ done: `${lead} #${id}.`, attempt: `${tool} #${id}` }, run, expectChange === undefined ? {} : { expectChange });
+            },
         });
     }
     // scroll_to reaches a node the screen lists (by id, through the engine's

package/dist/agent/replay.js

@@ -12,7 +12,7 @@
  * divergence.
  */
 import { isRelocatableDescriptor, MAIN_LIST_SHARE, relocateDescriptor } from '../cache/relocate.js';
-import { isNodeAction } from '../cache/trace.js';
+import { isNodeAction, isTapActionName } from '../cache/trace.js';
 import { hasCause } from '../internal/errors.js';
 import { containsPoint } from '../internal/geometry.js';
 import { sleep } from '../internal/time.js';
@@ -23,8 +23,14 @@ const RETRY_DELAYS_MS = [100, 300, 600, 1_000, 3_000];
 /** Ceiling on one poll's total wait, inside whatever the deadline allows. */
 const RETRY_TIMEOUT_MS = 15_000;
 function planCall(action, actions) {
-    if (isNodeAction(action))
-        return { kind: 'targeted', descriptor: action.target, invoke: (t) => actions[action.name](t) };
+    if (isNodeAction(action)) {
+        const { name, modifiers } = action;
+        return {
+            kind: 'targeted',
+            descriptor: action.target,
+            invoke: (t) => (isTapActionName(name) && modifiers !== undefined ? actions[name](t, { modifiers }) : actions[name](t)),
+        };
+    }
     switch (action.name) {
         case 'tool':
             return { kind: 'gap', ...(action.derived === undefined ? {} : { derived: action.derived }) };

package/dist/agent/step-cache.d.ts

@@ -14,7 +14,7 @@
 import type { AgentCacheContext } from '../cache/context.ts';
 import { type CacheAgentIdentity } from '../cache/identity.ts';
 import { type ParamTemplate } from '../cache/template.ts';
-import { type DerivedReason } from '../cache/trace.ts';
+import { type DerivedReason, type RecordedModel } from '../cache/trace.ts';
 import type { StepCacheInfo } from '../run/steps.ts';
 import type { JsonValue } from '../types.ts';
 import type { RecordableAction } from './actions.ts';
@@ -71,6 +71,7 @@ export declare class StepTraceSession {
     private readonly options;
     private readonly redaction;
     private info;
+    private recordedBy;
     private prefix;
     private startPath;
     private startedMs;
@@ -170,7 +171,7 @@ export declare class StepTraceSession {
      *   that diverged hands off again next run, where a model that answers
      *   re-records it.
      */
-    conclude(outcome: StepOutcome, verdictSummary: string | undefined): Promise<void>;
+    conclude(outcome: StepOutcome, verdictSummary: string | undefined, recordedBy?: RecordedModel): Promise<void>;
     /**
      * One store read, revalidated through the trace-1 framing whichever store
      * produced it: a custom store's entry can never be trusted more loosely

package/dist/agent/step-cache.js

@@ -69,6 +69,7 @@ export class StepTraceSession {
     options;
     redaction;
     info;
+    recordedBy;
     prefix;
     startPath;
     startedMs = Date.now();
@@ -117,7 +118,7 @@ export class StepTraceSession {
     }
     /** How the cache participated, for the step's report detail. */
     get cacheInfo() {
-        return this.info;
+        return this.info === undefined || this.recordedBy === undefined ? this.info : { ...this.info, recordedBy: this.recordedBy };
     }
     /** The mid-step hand-off, when a replay diverged after real progress. */
     get replayedPrefix() {
@@ -238,7 +239,7 @@ export class StepTraceSession {
      *   that diverged hands off again next run, where a model that answers
      *   re-records it.
      */
-    async conclude(outcome, verdictSummary) {
+    async conclude(outcome, verdictSummary, recordedBy) {
         const recorder = this.recorder;
         if (recorder === undefined)
             return;
@@ -263,7 +264,7 @@ export class StepTraceSession {
                     });
                 }
                 else {
-                    const staged = await this.stage(recorder, verdictSummary);
+                    const staged = await this.stage(recorder, verdictSummary, recordedBy);
                     if (staged !== 'staged' && this.readEntryHit)
                         await this.evict();
                     else if (staged === 'no-change')
@@ -326,6 +327,7 @@ export class StepTraceSession {
     async replayEntry(entry) {
         const start = await this.captureStart('replay-start');
         const trace = entry.payload;
+        this.recordedBy = trace.recordedBy;
         if (!this.host.traceEligible) {
             this.info = this.missed('truncated', trace.actions.length);
             return undefined;
@@ -506,7 +508,7 @@ export class StepTraceSession {
      * does a step that changed nothing a replay could check, no node and no
      * route: a trace without its check would replay on mechanics alone.
      */
-    async stage(recorder, verdictSummary) {
+    async stage(recorder, verdictSummary, recordedBy) {
         if (!this.host.traceEligible || this.startNodes === undefined || recorder.recordedCount === 0)
             return 'skipped';
         const observation = await probeScreen(this.host, 'held-still');
@@ -523,6 +525,7 @@ export class StepTraceSession {
         const trace = recorder.finalize({
             executor: this.options.executor,
             recordedFor: this.claim.step,
+            ...(recordedBy === undefined ? {} : { recordedBy }),
             summary: verdictSummary ?? 'step passed',
             ...(this.startPath === undefined ? {} : { startPath: this.startPath }),
             ...(endPath === undefined ? {} : { endPath }),

package/dist/agent/tool-loop.js

@@ -13,7 +13,7 @@
 import { asSdkLanguageModel, loadAiSdk } from './ai-sdk.js';
 import { MODEL_REQUEST_HEADERS } from '../internal/client-identity.js';
 import { ConfigurationError, providerFailureMessage, withHint } from '../internal/errors.js';
-import { failureHint, isAbort, TRANSPORT_RETRIES } from './model/sdk.js';
+import { failureHint, isAbort, TRANSPORT_RETRIES, unservedModelError } from './model/sdk.js';
 import { isContextOverflow } from './model/overflow.js';
 import { isForcedToolCallMismatched, isForcedToolCallSkipped, isForcedToolChoiceDowngraded, isForcedToolChoiceRejected, } from './model/tool-choice.js';
 import { withStallGuard } from './model/stall.js';
@@ -220,6 +220,9 @@ class LoopRun {
                 if (isContextOverflow(cause)) {
                     throw new AgentError('CONTEXT_OVERFLOW', `the model request exceeded the context window${this.overflowNote ?? ''}: ${message}`, { cause });
                 }
+                const unserved = unservedModelError(cause);
+                if (unserved !== undefined)
+                    throw unserved;
                 throw new AgentError('MODEL_PROVIDER_FAILED', withHint(`the model provider failed: ${message}`, failureHint(cause)), { cause });
             }
         }

package/dist/cache/context.js

@@ -30,7 +30,7 @@ async function holdsSameFlow(store, keyHash, trace) {
 }
 /** The part of a trace that decides what a replay does, as canonical JSON. */
 function flowOf(trace) {
-    const { summary: _summary, endWaitMs: _endWaitMs, keyedBy: _keyedBy, actions, ...flow } = trace;
+    const { summary: _summary, endWaitMs: _endWaitMs, keyedBy: _keyedBy, recordedBy: _recordedBy, actions, ...flow } = trace;
     return canonicalJson({
         ...flow,
         actions: actions.map((action) => {

package/dist/cache/recorder.d.ts

@@ -16,7 +16,7 @@
  * state. A poisoned trace still documents what happened; it never replays.
  */
 import { type RecordableAction } from '../agent/actions.ts';
-import { type ActionTrace, type DerivedReason, type TraceKeyContext, type TraceProvenance, type TraceTargetDescriptor } from './trace.ts';
+import { type ActionTrace, type DerivedReason, type RecordedModel, type TraceKeyContext, type TraceProvenance, type TraceTargetDescriptor } from './trace.ts';
 export interface TraceRecorderOptions {
     /** The run's secret redactor; applied to every recorded string. */
     readonly redact: (text: string) => string;
@@ -61,6 +61,7 @@ export declare class TraceRecorder {
         };
         /** Test, target, and instruction digest the trace was recorded for. */
         readonly recordedFor: TraceProvenance;
+        readonly recordedBy?: RecordedModel;
         readonly summary: string;
         readonly startPath?: string;
         readonly endPath?: string;

package/dist/cache/recorder.js

@@ -18,6 +18,7 @@
 import { describeAction } from '../agent/actions.js';
 import { isRelocatableDescriptor } from './relocate.js';
 import { DESCRIPTOR_FIELDS, MAX_TRACE_ACTIONS, MAX_TRACE_DESCRIPTOR_CHARS, MAX_TRACE_END_WAIT_MS, MAX_TRACE_INPUT_CHARS, MAX_TRACE_SUMMARY_CHARS, isNodeAction, } from './trace.js';
+import { readRecordedModel } from './trace-fields.js';
 import { bound } from '../internal/text.js';
 /** The summary a run-time value gap records; the prose a project-tool gap would carry for a tool of that name. */
 const DERIVED_GAP_SUMMARY = 'tool type (run-time value)';
@@ -71,6 +72,8 @@ export class TraceRecorder {
     finalize(conclusion) {
         if (this.actions.length === 0)
             return undefined;
+        const source = conclusion.recordedBy;
+        const recordedBy = source === undefined ? undefined : readRecordedModel({ provider: this.redact(source.provider), model: this.redact(source.model) }, MAX_TRACE_DESCRIPTOR_CHARS);
         const summary = bound(this.redact(conclusion.summary), MAX_TRACE_SUMMARY_CHARS);
         // Locations are replay preconditions, so they follow the input rule: a
         // path the redactor alters carried a secret (a token in a query string),
@@ -85,6 +88,7 @@ export class TraceRecorder {
                 ...(conclusion.executor.version === undefined ? {} : { version: conclusion.executor.version }),
             },
             recordedFor: recordedProvenance(conclusion.recordedFor, this.redact),
+            ...(recordedBy === undefined ? {} : { recordedBy }),
             summary: summary.trim() === '' ? 'step passed' : summary,
             ...(startPath === undefined ? {} : { startPath }),
             ...(endPath === undefined ? {} : { endPath }),
@@ -123,8 +127,13 @@ export class TraceRecorder {
             return descriptor ?? { role: 'unknown' };
         };
         const requireTarget = () => require(target);
-        if (isNodeAction(action))
-            return { name: action.name, summary, target: requireTarget() };
+        if (isNodeAction(action)) {
+            const recorded = { name: action.name, summary, target: requireTarget() };
+            // A tap with held keys replays with them, so the trace keeps them.
+            if ('modifiers' in action && action.modifiers !== undefined)
+                return { ...recorded, modifiers: [...action.modifiers] };
+            return recorded;
+        }
         switch (action.name) {
             case 'check':
                 return { name: 'check', summary, target: requireTarget(), checked: action.checked };

package/dist/cache/trace-fields.d.ts

@@ -0,0 +1,10 @@
+/** Scalar fields shared by trace readers and the recorder. */
+/** The configured model identity attached to a recording. */
+export interface RecordedModel {
+    readonly provider: string;
+    readonly model: string;
+}
+/** Nonblank text within the field's character budget, preserved verbatim. */
+export declare function readBoundedText(value: unknown, maxChars: number): string | undefined;
+/** Malformed optional model attribution never makes a recording unreadable. */
+export declare function readRecordedModel(value: unknown, maxChars: number): RecordedModel | undefined;

package/dist/cache/trace-fields.js

@@ -0,0 +1,17 @@
+/** Scalar fields shared by trace readers and the recorder. */
+/** Nonblank text within the field's character budget, preserved verbatim. */
+export function readBoundedText(value, maxChars) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > maxChars) {
+        return undefined;
+    }
+    return value;
+}
+/** Malformed optional model attribution never makes a recording unreadable. */
+export function readRecordedModel(value, maxChars) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const provider = readBoundedText(raw['provider'], maxChars);
+    const model = readBoundedText(raw['model'], maxChars);
+    return provider === undefined || model === undefined ? undefined : { provider, model };
+}