@e2edev/e2e 0.2.0

package/dist/collect/select.js

@@ -0,0 +1,230 @@
+/** Option resolution and test-target selection (spec 11-lifecycle.md). */
+import { ConfigurationError, CollectionError } from '../internal/errors.js';
+import { groupChain } from './registry.js';
+/** Resolves effective options: test > nearest group > outer groups > config > default. */
+export function resolveOptions(test, config) {
+    const chain = groupChain(test.group);
+    const layers = [...chain.map((group) => group.options), test.options];
+    let timeout = config.timeout;
+    let retries = config.retries;
+    let platforms;
+    let requires = [];
+    let session;
+    let skipReason;
+    const tags = new Set();
+    const agentContextParts = [];
+    for (const layer of layers) {
+        if (layer.timeout !== undefined)
+            timeout = layer.timeout;
+        if (layer.retries !== undefined)
+            retries = layer.retries;
+        if (layer.platforms !== undefined)
+            platforms = layer.platforms;
+        if (layer.requires !== undefined)
+            requires = layer.requires;
+        if (layer.session !== undefined)
+            session = layer.session;
+        if (layer.tags !== undefined)
+            for (const tag of layer.tags)
+                tags.add(tag);
+        if (layer.agentContext !== undefined)
+            agentContextParts.push(layer.agentContext);
+        if (layer.skip !== undefined && layer.skip !== false) {
+            skipReason = typeof layer.skip === 'string' ? layer.skip : 'skipped';
+        }
+    }
+    const serialRoot = test.serialRoot;
+    if (serialRoot !== undefined) {
+        let serialRetries = config.retries;
+        for (const group of chain) {
+            if (group.options.retries !== undefined)
+                serialRetries = group.options.retries;
+            if (group === serialRoot)
+                break;
+        }
+        retries = serialRetries;
+    }
+    return {
+        timeout,
+        retries,
+        tags: [...tags],
+        platforms,
+        requires,
+        session,
+        agentContext: agentContextParts.length === 0 ? undefined : agentContextParts.join('\n'),
+        skipReason,
+        serial: serialRoot !== undefined,
+    };
+}
+function matchesTags(options, tags, tagMode) {
+    if (tags === undefined || tags.length === 0)
+        return true;
+    if (tagMode === 'all')
+        return tags.every((tag) => options.tags.includes(tag));
+    return tags.some((tag) => options.tags.includes(tag));
+}
+/**
+ * Expands the collection into test-target pairs and applies focus, tag,
+ * platform, capability, session, and serial-closure rules.
+ */
+export function select(collection, config, filters = {}, flags = {}) {
+    const tagMode = filters.tagMode ?? 'any';
+    const targets = filters.targetIds === undefined || filters.targetIds.length === 0
+        ? config.targets
+        : config.targets.filter((target) => filters.targetIds.includes(target.name));
+    if (filters.targetIds !== undefined) {
+        for (const id of filters.targetIds) {
+            if (!config.targets.some((target) => target.name === id)) {
+                throw new ConfigurationError('UNKNOWN_TARGET', `unknown target ID "${id}"`);
+            }
+        }
+    }
+    const focused = collection.tests.filter((test) => test.mode === 'only');
+    if (focused.length > 0 && config.ci) {
+        throw new ConfigurationError('ONLY_IN_CI', `.only is rejected in CI: ${focused.map((test) => test.id).join(', ')}`);
+    }
+    const optionsByTest = new Map();
+    for (const test of collection.tests) {
+        optionsByTest.set(test.id, resolveOptions(test, config));
+    }
+    const sessionProducers = collectSessionProducers(collection.tests);
+    const pairs = [];
+    for (const target of targets) {
+        for (const test of collection.tests) {
+            const options = optionsByTest.get(test.id);
+            pairs.push(classifyPair(test, target, options, focused, filters, tagMode));
+        }
+    }
+    const withClosure = applySerialClosure(pairs);
+    const withSessions = applySessionSelection(withClosure, sessionProducers);
+    const runnableOrdinary = withSessions.filter((pair) => pair.disposition === 'run' && pair.test.kind === 'test');
+    if (runnableOrdinary.length === 0 && flags.passWithNoTests !== true) {
+        throw new ConfigurationError('NO_TESTS', 'zero runnable ordinary test-target pairs; pass --pass-with-no-tests to allow this');
+    }
+    return {
+        pairs: withSessions,
+        perTarget: targets.map((target) => ({
+            target,
+            pairs: withSessions.filter((pair) => pair.target.name === target.name),
+        })),
+    };
+}
+/** Maps each session name to its unique producer setup test. */
+function collectSessionProducers(tests) {
+    const producers = new Map();
+    for (const test of tests) {
+        if (test.kind !== 'setup')
+            continue;
+        for (const session of test.sessions) {
+            const existing = producers.get(session);
+            if (existing !== undefined) {
+                throw new CollectionError(`session "${session}" has duplicate producers: ${existing.id} and ${test.id}`);
+            }
+            producers.set(session, test);
+        }
+    }
+    return producers;
+}
+function classifyPair(test, target, options, focused, filters, tagMode) {
+    const base = { test, target, options };
+    if (test.kind === 'test') {
+        if (focused.length > 0 && test.mode !== 'only') {
+            return {
+                ...base,
+                disposition: 'filtered',
+                skip: { cause: 'filtered', reason: 'not focused by .only' },
+            };
+        }
+        if (!matchesTags(options, filters.tags, tagMode)) {
+            return {
+                ...base,
+                disposition: 'filtered',
+                skip: { cause: 'filtered', reason: 'tag filter did not match' },
+            };
+        }
+    }
+    if (options.platforms !== undefined && !options.platforms.includes(target.platform)) {
+        return {
+            ...base,
+            disposition: 'filtered',
+            skip: {
+                cause: 'platform-unavailable',
+                reason: `test declares platforms [${options.platforms.join(', ')}]`,
+            },
+        };
+    }
+    // Targets are graded from the backend's declared capability set: harness
+    // tiers plus one name per contributed fixture. Selection runs at config
+    // load, before any backend boots, which is why the manifest is synchronous.
+    const capabilities = target.backend?.capabilities;
+    const missing = options.requires.filter((capability) => capabilities?.has(capability) !== true);
+    if (missing.length > 0) {
+        return {
+            ...base,
+            disposition: 'skip',
+            skip: {
+                cause: 'capability-unavailable',
+                reason: `backend lacks required capabilities: ${missing.join(', ')}`,
+            },
+        };
+    }
+    if (options.skipReason !== undefined) {
+        return {
+            ...base,
+            disposition: 'skip',
+            skip: { cause: 'explicit', reason: options.skipReason },
+        };
+    }
+    if (test.kind === 'setup') {
+        return { ...base, disposition: 'filtered', skip: { cause: 'filtered', reason: 'setup test not required by selection' } };
+    }
+    return { ...base, disposition: 'run', skip: undefined };
+}
+function applySerialClosure(pairs) {
+    const selectedSerialUnits = new Set();
+    for (const pair of pairs) {
+        if (pair.disposition === 'run' && pair.test.serialId !== undefined) {
+            selectedSerialUnits.add(`${pair.target.name}::${pair.test.serialId}`);
+        }
+    }
+    return pairs.map((pair) => {
+        if (pair.test.serialId === undefined)
+            return pair;
+        const key = `${pair.target.name}::${pair.test.serialId}`;
+        if (!selectedSerialUnits.has(key))
+            return pair;
+        if (pair.disposition === 'run')
+            return pair;
+        if (pair.disposition === 'filtered' && pair.skip?.cause === 'filtered') {
+            return { ...pair, disposition: 'run', skip: undefined };
+        }
+        return pair;
+    });
+}
+function applySessionSelection(pairs, sessionProducers) {
+    const neededSetups = new Set();
+    for (const pair of pairs) {
+        if (pair.disposition !== 'run' || pair.options.session === undefined)
+            continue;
+        const producer = sessionProducers.get(pair.options.session);
+        if (producer === undefined) {
+            throw new CollectionError(`test ${pair.test.id} consumes session "${pair.options.session}" but no setup test produces it`);
+        }
+        neededSetups.add(`${pair.target.name}::${producer.id}`);
+    }
+    return pairs.map((pair) => {
+        if (pair.test.kind !== 'setup')
+            return pair;
+        const key = `${pair.target.name}::${pair.test.id}`;
+        if (!neededSetups.has(key))
+            return pair;
+        // A producer the target cannot run - skipped for a missing capability or
+        // filtered out by its own platform list - cannot be promoted; a consumer
+        // that needs it is a configuration error, not a silent run elsewhere.
+        if (pair.disposition === 'skip' || pair.skip?.cause === 'platform-unavailable') {
+            throw new CollectionError(`setup test ${pair.test.id} is required by a session consumer but cannot run on target "${pair.target.name}": ${pair.skip?.reason ?? ''}`);
+        }
+        return { ...pair, disposition: 'run', skip: undefined };
+    });
+}
+//# sourceMappingURL=select.js.map

package/dist/collect/select.js.map

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

package/dist/config/agent.d.ts

@@ -0,0 +1,91 @@
+/** Agent, model, and resource-limit resolution (spec 05-config.md, 14-security.md). */
+import type { LanguageModel } from 'ai';
+import { type StepExecutor } from '../agent/executor.ts';
+import type { E2EConfig, ModelInstance, VisionMode } from '../types.ts';
+/** Gateway-native credential variable, used when apiKeyEnv holds no value. */
+export declare const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
+/** A live AI SDK language model, as accepted by `generateText`. */
+export type SdkLanguageModel = Exclude<LanguageModel, string>;
+/**
+ * Resolved model identity. Two shapes cover every provider:
+ *
+ * - `gateway`: a `provider/model-id` reference routed through the AI Gateway.
+ *   The credential is resolved from the environment here so nothing downstream
+ *   needs the process environment; it never enters digests, logs, or reports.
+ * - `instance`: a caller-supplied AI SDK provider model (`openai('gpt-4o')`,
+ *   `anthropic(...)`, any `LanguageModelV2+`). The instance owns its own
+ *   transport and credentials. Instances never cross a process boundary:
+ *   workers re-resolve the config module and construct their own.
+ */
+export type ResolvedModel = {
+    readonly kind: 'gateway';
+    readonly provider: string;
+    readonly id: string;
+    /** Absolute endpoint override, or undefined for the gateway default. */
+    readonly endpoint: string | undefined;
+    readonly apiKeyEnv: string;
+    /** Resolved credential; absence fails at the first model call, not here. */
+    readonly apiKey: string | undefined;
+} | {
+    readonly kind: 'instance';
+    readonly provider: string;
+    readonly id: string;
+    readonly model: SdkLanguageModel;
+};
+export interface ResolvedAgentConfig {
+    /**
+     * The step executor `agent.act()` dispatches to, configured as the `agent`
+     * value itself (`agent: createAgent(...)` or any StepExecutor); undefined
+     * selects the default AI SDK executor at fixture time. Like model
+     * instances, an executor never crosses a process boundary: workers
+     * re-resolve the config module.
+     */
+    readonly executor: StepExecutor | undefined;
+    /** Undefined until a model is configured; acquiring `agent` then fails. */
+    readonly model: ResolvedModel | undefined;
+    /**
+     * Model used by calls with `vision`. Visual grounding is a much higher bar
+     * than accepting an image, so the tier that needs it can be pinned
+     * separately. Undefined falls back to `model`.
+     */
+    readonly visionModel: ResolvedModel | undefined;
+    readonly maxSteps: number;
+    readonly maxModelCalls: number;
+    readonly maxObservationBytes: number;
+    readonly context: string | undefined;
+    /** Default for the per-call `vision` option; a per-call value always wins. */
+    readonly vision: VisionMode;
+}
+export interface ResolvedLimits {
+    readonly maxAgentContextBytes: number;
+    readonly maxLedgerBytes: number;
+    readonly maxObservationBytes: number;
+    readonly maxEventsPerStep: number;
+    readonly maxModelTokensPerCall: number;
+}
+/** `ResolvedLimits` before the agent-owned observation budget is attached. */
+export type ResolvedBaseLimits = Omit<ResolvedLimits, 'maxObservationBytes'>;
+/** Default observation byte budget, shared with the report's pre-config fallback limits. */
+export declare const DEFAULT_OBSERVATION_BYTES = 1048576;
+/**
+ * Resolves `config.agent` plus model environment fallbacks. `limits` must be
+ * resolved first: the context budget is a limits key, and the dependency runs
+ * in exactly one direction.
+ */
+export declare function resolveAgentConfig(raw: E2EConfig, env: NodeJS.ProcessEnv, ci: boolean, limits: ResolvedBaseLimits): ResolvedAgentConfig;
+/** Resolves the `limits` block. The observation budget is attached by the caller. */
+export declare function resolveLimits(raw: E2EConfig): ResolvedBaseLimits;
+/** True for the closed `vision` value set, wherever it is supplied. */
+export declare function isVisionMode(value: unknown): value is VisionMode;
+/**
+ * Narrows a structurally verified model instance to the SDK model type. The
+ * one place this cast lives; everything downstream takes the checked type.
+ */
+export declare function asSdkLanguageModel(instance: ModelInstance): SdkLanguageModel;
+/**
+ * True when a config value is a live AI SDK language model instance. The check
+ * is structural, exactly like the AI SDK's own model handling, so instances
+ * from any realm or provider package are accepted.
+ */
+export declare function isModelInstance(value: unknown): value is ModelInstance;
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/config/agent.ts"],"names":[],"mappings":"AAAA,uFAAuF;AAEvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAIzE,OAAO,KAAK,EAAe,SAAS,EAAe,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKlG,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,uBAAuB,CAAC;AAExD,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;CAClC,CAAC;AAEN,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,aAAa,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAAC;AAe7E,4FAA4F;AAC5F,eAAO,MAAM,yBAAyB,UAAY,CAAC;AAcnD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,kBAAkB,GACzB,mBAAmB,CAyDrB;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,kBAAkB,CAoBhE;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,gBAAgB,CAQ5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAStE"}

package/dist/config/agent.js

@@ -0,0 +1,232 @@
+/** Agent, model, and resource-limit resolution (spec 05-config.md, 14-security.md). */
+import { isStepExecutor } from '../agent/executor.js';
+import { boundedInt } from './validate.js';
+import { ConfigurationError } from '../internal/errors.js';
+import { isLoopbackHost } from '../internal/urls.js';
+/** Default environment variable holding the provider credential. */
+const DEFAULT_API_KEY_ENV = 'E2E_MODEL_API_KEY';
+/** Gateway-native credential variable, used when apiKeyEnv holds no value. */
+export const GATEWAY_API_KEY_ENV = 'AI_GATEWAY_API_KEY';
+const AGENT_KEYS = new Set([
+    'executor',
+    'model',
+    'visionModel',
+    'maxSteps',
+    'maxModelCalls',
+    'maxObservationBytes',
+    'context',
+    'vision',
+]);
+const MODEL_KEYS = new Set(['provider', 'id', 'endpoint', 'apiKeyEnv']);
+/** Default observation byte budget, shared with the report's pre-config fallback limits. */
+export const DEFAULT_OBSERVATION_BYTES = 1_048_576;
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Hard ceilings mirroring spec/schema/report-v1.schema.json `limits`. */
+const LIMIT_BOUNDS = {
+    maxAgentContextBytes: [1_024, 65_536, 16_384],
+    maxLedgerBytes: [1_024, 65_536, 8_192],
+    maxEventsPerStep: [1, 10_000, 1_000],
+    maxModelTokensPerCall: [1, 1_000_000, 64_000],
+};
+/**
+ * Resolves `config.agent` plus model environment fallbacks. `limits` must be
+ * resolved first: the context budget is a limits key, and the dependency runs
+ * in exactly one direction.
+ */
+export function resolveAgentConfig(raw, env, ci, limits) {
+    const value = raw.agent;
+    // Three accepted shapes (RFC0002): the agent itself, an options object, or
+    // an options object carrying `executor` — a custom brain no longer forfeits
+    // the model, budgets, or context.
+    const bare = value !== undefined && isStepExecutor(value) ? value : undefined;
+    const agent = bare === undefined ? value : undefined;
+    let executor = bare;
+    if (agent !== undefined) {
+        if (typeof agent !== 'object' || agent === null || Array.isArray(agent)) {
+            throw new ConfigurationError('INVALID_CONFIG', 'agent must be an options object or the agent itself: createAgent(...) or any { name, runStep(context) }');
+        }
+        for (const key of Object.keys(agent)) {
+            if (!AGENT_KEYS.has(key)) {
+                throw new ConfigurationError('INVALID_CONFIG', `unknown agent config key "${key}"`);
+            }
+        }
+        if (agent.executor !== undefined) {
+            if (!isStepExecutor(agent.executor)) {
+                throw new ConfigurationError('INVALID_CONFIG', 'agent.executor must be a StepExecutor: createAgent(...) or any { name, runStep(context) }');
+            }
+            executor = agent.executor;
+        }
+    }
+    const maxSteps = boundedInt(agent?.maxSteps, 'agent.maxSteps', 1, 100) ?? 25;
+    const maxModelCalls = boundedInt(agent?.maxModelCalls, 'agent.maxModelCalls', 1, 100) ?? 25;
+    const maxObservationBytes = boundedInt(agent?.maxObservationBytes, 'agent.maxObservationBytes', 1_024, 16_777_216) ??
+        DEFAULT_OBSERVATION_BYTES;
+    const context = resolveContext(agent?.context, limits.maxAgentContextBytes);
+    const vision = agent?.vision ?? false;
+    if (!isVisionMode(vision)) {
+        throw new ConfigurationError('INVALID_CONFIG', "agent.vision must be true, false, 'fallback', or 'only'");
+    }
+    return {
+        executor,
+        model: resolveModel(agent?.model, env),
+        visionModel: resolveModel(agent?.visionModel, env, 'agent.visionModel', 'E2E_VISION_MODEL'),
+        maxSteps,
+        maxModelCalls,
+        maxObservationBytes,
+        context,
+        vision,
+    };
+}
+/** Resolves the `limits` block. The observation budget is attached by the caller. */
+export function resolveLimits(raw) {
+    const limits = raw.limits;
+    if (limits !== undefined) {
+        if (typeof limits !== 'object' || limits === null || Array.isArray(limits)) {
+            throw new ConfigurationError('INVALID_CONFIG', 'limits must be an object');
+        }
+        for (const key of Object.keys(limits)) {
+            if (!(key in LIMIT_BOUNDS)) {
+                throw new ConfigurationError('INVALID_CONFIG', `unknown limits key "${key}"`);
+            }
+        }
+    }
+    const resolved = {};
+    for (const key of Object.keys(LIMIT_BOUNDS)) {
+        const [min, max, fallback] = LIMIT_BOUNDS[key];
+        resolved[key] = boundedInt(limits?.[key], `limits.${key}`, min, max) ?? fallback;
+    }
+    return resolved;
+}
+/** True for the closed `vision` value set, wherever it is supplied. */
+export function isVisionMode(value) {
+    return typeof value === 'boolean' || value === 'fallback' || value === 'only';
+}
+/**
+ * Narrows a structurally verified model instance to the SDK model type. The
+ * one place this cast lives; everything downstream takes the checked type.
+ */
+export function asSdkLanguageModel(instance) {
+    if (!isModelInstance(instance)) {
+        throw new ConfigurationError('INVALID_CONFIG', 'value is not an AI SDK language model instance');
+    }
+    return instance;
+}
+/**
+ * True when a config value is a live AI SDK language model instance. The check
+ * is structural, exactly like the AI SDK's own model handling, so instances
+ * from any realm or provider package are accepted.
+ */
+export function isModelInstance(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate['specificationVersion'] === 'string' &&
+        typeof candidate['provider'] === 'string' &&
+        typeof candidate['modelId'] === 'string' &&
+        typeof candidate['doGenerate'] === 'function');
+}
+/**
+ * Resolves one model reference from config or its environment override.
+ *
+ * `label` and `envName` are parameters because the same grammar serves
+ * `agent.model` and `agent.visionModel`; every diagnostic then names the key the
+ * author actually wrote. There is no implicit default model; an unconfigured
+ * model fails at its first model call, so a custom-executor run needs none.
+ */
+function resolveModel(model, env, label = 'agent.model', envName = 'E2E_MODEL') {
+    if (model === undefined) {
+        const fromEnv = env[envName];
+        if (fromEnv === undefined || fromEnv.trim() === '')
+            return undefined;
+        return parseModelReference(fromEnv.trim(), envName, env);
+    }
+    if (typeof model === 'string') {
+        return parseModelReference(model, label, env);
+    }
+    if (typeof model !== 'object' || model === null || Array.isArray(model)) {
+        throw new ConfigurationError('INVALID_CONFIG', `${label} must be "provider/model-id", a model object, or an AI SDK model instance`);
+    }
+    if (isModelInstance(model)) {
+        return {
+            kind: 'instance',
+            provider: model.provider,
+            id: model.modelId,
+            // Structurally verified above; the AI SDK duck-types models the same way.
+            model: model,
+        };
+    }
+    for (const key of Object.keys(model)) {
+        if (!MODEL_KEYS.has(key)) {
+            throw new ConfigurationError('INVALID_CONFIG', `unknown ${label} key "${key}"`);
+        }
+    }
+    const provider = requireNonEmpty(model.provider, `${label}.provider`);
+    const id = requireNonEmpty(model.id, `${label}.id`);
+    return gatewayModel(provider, id, model.endpoint, model.apiKeyEnv, env, label);
+}
+/** Splits `provider/model-id` at the first slash. */
+function parseModelReference(reference, label, env) {
+    const separator = reference.indexOf('/');
+    if (separator <= 0 || separator === reference.length - 1) {
+        throw new ConfigurationError('INVALID_CONFIG', `${label} must be "provider/model-id", got ${JSON.stringify(reference)}`);
+    }
+    return gatewayModel(reference.slice(0, separator), reference.slice(separator + 1), undefined, undefined, env, label);
+}
+function gatewayModel(provider, id, endpoint, apiKeyEnv, env, label) {
+    const keyEnv = validateApiKeyEnv(apiKeyEnv, label);
+    const apiKey = firstNonEmpty(env[keyEnv], env[GATEWAY_API_KEY_ENV]);
+    return {
+        kind: 'gateway',
+        provider,
+        id,
+        endpoint: validateEndpoint(endpoint, label),
+        apiKeyEnv: keyEnv,
+        apiKey,
+    };
+}
+function firstNonEmpty(...values) {
+    return values.find((value) => value !== undefined && value.trim() !== '');
+}
+function validateEndpoint(endpoint, label) {
+    if (endpoint === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(endpoint);
+    }
+    catch {
+        throw new ConfigurationError('INVALID_CONFIG', `invalid ${label}.endpoint "${endpoint}"`);
+    }
+    if (parsed.protocol === 'https:')
+        return parsed.href;
+    if (parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname))
+        return parsed.href;
+    throw new ConfigurationError('INVALID_CONFIG', `${label}.endpoint must use HTTPS unless it is a loopback host: ${endpoint}`);
+}
+function validateApiKeyEnv(apiKeyEnv, label) {
+    if (apiKeyEnv === undefined)
+        return DEFAULT_API_KEY_ENV;
+    if (!ENV_NAME_PATTERN.test(apiKeyEnv)) {
+        throw new ConfigurationError('INVALID_CONFIG', `${label}.apiKeyEnv must be a valid environment variable name, got "${apiKeyEnv}"`);
+    }
+    return apiKeyEnv;
+}
+function resolveContext(context, maxBytes) {
+    if (context === undefined)
+        return undefined;
+    if (typeof context !== 'string') {
+        throw new ConfigurationError('INVALID_CONFIG', 'agent.context must be a string');
+    }
+    const bytes = new TextEncoder().encode(context).byteLength;
+    if (bytes > maxBytes) {
+        throw new ConfigurationError('INVALID_CONFIG', `agent.context is ${bytes} bytes; the resolved maximum is ${maxBytes}`);
+    }
+    return context;
+}
+function requireNonEmpty(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new ConfigurationError('INVALID_CONFIG', `${label} is required`);
+    }
+    return value;
+}
+//# sourceMappingURL=agent.js.map

package/dist/config/agent.js.map

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

package/dist/config/load.d.ts

@@ -0,0 +1,23 @@
+/** Config discovery and ESM/TypeScript loading (spec 05-config.md). */
+import type { E2EConfig } from '../types.ts';
+export interface DiscoveredConfig {
+    readonly configPath: string | undefined;
+    readonly projectRoot: string;
+}
+/**
+ * Discovers the config file. With `--config` the explicit path wins. Otherwise
+ * the search starts at cwd and inspects each parent, stopping after the
+ * repository root. The selected file's directory is the project root.
+ */
+export declare function discoverConfig(cwd: string, explicitPath?: string): DiscoveredConfig;
+/**
+ * Imports a TypeScript/ESM module with erasable-syntax support. Every call
+ * evaluates the module afresh: the query carries the caller's key (what the
+ * instance is for) plus a process-unique sequence, so a realm never receives
+ * another realm's module instance and a second `run()` in one process sees
+ * the config file as it is now.
+ */
+export declare function importModule(absolutePath: string, cacheKey?: string): Promise<unknown>;
+/** Loads and returns the raw default export of a config module. */
+export declare function loadConfigModule(configPath: string): Promise<E2EConfig>;
+//# sourceMappingURL=load.d.ts.map

package/dist/config/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAOvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,gBAAgB,CA2BnF;AAWD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,SAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAK9F;AAED,mEAAmE;AACnE,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAmB7E"}