@e2edev/e2e 0.9.0 → 0.11.0

package/dist/explore/body.js

@@ -0,0 +1,168 @@
+/**
+ * The exploration body: the test `e2e explore` registers in memory. A loop
+ * of ordinary `agent.act` steps, one per charter the planner writes, under
+ * the exploration's own budgets. The outcome policy is the one TesterArmy's
+ * discovery runs settled on: a step that ends at its budget is a time-boxed
+ * charter and not a failure; a failed step is a finding and the run goes on;
+ * three failed or blocked steps in a row, the step cap, or the clock end the
+ * run with a closing assessment; findings of kind `issue` fail the run; a run
+ * that explored nothing and found nothing is blocked, never a pass.
+ */
+import { AgentError, isAgentError } from '../agent/error.js';
+import { credentials } from '../credentials.js';
+import { planNext } from './plan.js';
+/** Failed or blocked steps in a row, none with a finding, that end the run: the approach is not working. */
+export const CONSECUTIVE_FAILURE_LIMIT = 3;
+/** Time kept back for the closing assessment once no step can start. */
+const FINISH_RESERVE_MS = 60_000;
+/** The least time a step is worth starting with. */
+const MIN_STEP_MS = 45_000;
+/** The planner's deadline: one structured call plus a repair round, on a slow provider. */
+const PLAN_TIMEOUT_MS = 90_000;
+/** Below this, not even the closing assessment is asked for. */
+const MIN_PLAN_TIMEOUT_MS = 30_000;
+/** Builds the test body for one exploration. */
+export function createExploreBody(options) {
+    const { state } = options;
+    const now = options.now ?? Date.now;
+    const accounts = options.accounts ?? [];
+    return async ({ agent, app }) => {
+        const deadline = now() + state.budgets.timeoutMs;
+        if (options.openApp)
+            await app.open();
+        // Resolved here, once the runner has the credential registry up.
+        const secrets = accounts.length === 0
+            ? undefined
+            : Object.fromEntries(accounts.map((account) => [account.name, { username: account.username, password: credentials.user(account.name).password }]));
+        const ending = await runSteps({ agent, state, accounts, secrets, stepTimeoutMs: options.stepTimeoutMs, remaining: () => deadline - now() });
+        state.end(ending.ended, ending.summary);
+        conclude(state);
+    };
+}
+/**
+ * Plan, act, repeat, until something ends the run; returns why. A cancelled
+ * step or a failing provider throws out instead, and the record keeps its
+ * `aborted` default.
+ */
+async function runSteps(loop) {
+    const { agent, state, remaining } = loop;
+    /** Planner answers outside the grammar in a row; one is covered, two end the run. */
+    let plannerFailures = 0;
+    for (;;) {
+        const stop = mustFinish(state, remaining());
+        if (stop !== undefined && remaining() < MIN_PLAN_TIMEOUT_MS)
+            return { ended: stop.ended };
+        let plan;
+        try {
+            plan = await planNext(agent, state, {
+                mustFinish: stop !== undefined,
+                reason: stop?.reason,
+                accounts: loop.accounts,
+                remainingMs: remaining(),
+                timeoutMs: Math.max(MIN_PLAN_TIMEOUT_MS, Math.min(PLAN_TIMEOUT_MS, remaining())),
+            });
+            plannerFailures = 0;
+        }
+        catch (cause) {
+            // A model that cannot produce a plan in the grammar, even after the
+            // repair round, is a model shortcoming, not the end of the world: one
+            // failure is covered by a built-in charter (a survey first, a
+            // continuation later); two in a row end the exploration with the
+            // record so far; a failed closing assessment leaves the run to end for
+            // the reason it had to, without one. Anything else (the provider, the
+            // clock, a cancellation) is the run's error.
+            if (!isAgentError(cause) || cause.code !== 'MODEL_OUTPUT_INVALID')
+                throw cause;
+            if (stop !== undefined)
+                return { ended: stop.ended };
+            plannerFailures += 1;
+            if (plannerFailures > 1)
+                return { ended: 'aborted' };
+            plan = state.steps.length === 0 ? SURVEY_STEP : CONTINUE_STEP;
+        }
+        if (plan.kind === 'finish')
+            return { ended: stop?.ended ?? 'finished', summary: plan.summary };
+        // Asked to finish, the model planned a step anyway: the budget wins.
+        if (stop !== undefined)
+            return { ended: stop.ended };
+        // The plan call took its own time; a step still has to fit before the
+        // reserve, or the run is out of time whatever the check above said.
+        const room = remaining() - FINISH_RESERVE_MS;
+        if (room < MIN_STEP_MS)
+            return { ended: 'time' };
+        const step = state.beginStep(plan.title, plan.instruction);
+        const params = stepParams(state, loop.secrets);
+        try {
+            const result = await agent.act(step.instruction, {
+                timeout: Math.min(loop.stepTimeoutMs, room),
+                ...(params === undefined ? {} : { params }),
+            });
+            state.endStep('passed', result.summary);
+        }
+        catch (cause) {
+            if (!isAgentError(cause))
+                throw cause;
+            state.endStep(stepStatus(cause), cause.explanation, cause.code);
+            if (cause.code === 'CANCELLED')
+                throw cause;
+        }
+    }
+}
+/** Why the loop can no longer start a step, if it cannot. */
+function mustFinish(state, remainingMs) {
+    if (state.steps.length >= state.budgets.maxSteps) {
+        return { ended: 'step-limit', reason: `the step limit of ${state.budgets.maxSteps} is reached` };
+    }
+    const streak = state.consecutiveFailures();
+    if (streak >= CONSECUTIVE_FAILURE_LIMIT) {
+        return { ended: 'stuck', reason: `${streak} steps failed in a row without a finding; exploration is stuck` };
+    }
+    if (remainingMs < FINISH_RESERVE_MS + MIN_STEP_MS) {
+        return { ended: 'time', reason: 'the time budget is nearly spent' };
+    }
+    return undefined;
+}
+/**
+ * The step parameters a charter carries: the findings so far, so the agent
+ * neither reports one twice nor spends the step re-confirming it, and the
+ * configured accounts as secrets it can fill by name. Undefined when there
+ * is nothing to carry.
+ */
+function stepParams(state, secrets) {
+    const reported = state.findings.map((finding) => finding.title);
+    const params = {
+        ...(reported.length === 0 ? {} : { reportedFindings: reported }),
+        ...(secrets === undefined ? {} : { credentials: secrets }),
+    };
+    return Object.keys(params).length === 0 ? undefined : params;
+}
+/** How a step that threw ended: a charter that ran out of room ended, it did not fail. */
+function stepStatus(cause) {
+    if (cause.code === 'STEP_BUDGET_EXHAUSTED' || cause.code === 'STEP_TIMEOUT')
+        return 'exhausted';
+    return cause.code === 'CANCELLED' || cause.blocked ? 'blocked' : 'failed';
+}
+/** The first charter when the planner could not write one: look around. */
+const SURVEY_STEP = {
+    kind: 'step',
+    title: 'Survey the app',
+    instruction: 'Survey the app: visit each top-level page or screen the navigation offers once, note what each one is for and which controls it has, and try one obvious action on each. Report any defect you see on the way.',
+};
+/** A later charter when the planner could not write one: carry on with what the goal names and no step covered. */
+const CONTINUE_STEP = {
+    kind: 'step',
+    title: 'Continue exploring',
+    instruction: 'Continue the exploration: from the goal in the project context and the previously completed steps, pick the flow or screen the goal names that no step has covered yet, exercise it end to end with realistic inputs, and report any defect you see on the way.',
+};
+/** Turns the record into the run's verdict. */
+function conclude(state) {
+    if (state.steps.length === 0 && state.findings.length === 0) {
+        throw new AgentError('AUTOMATION_UNSUPPORTED', 'exploration concluded nothing: no step ran and no finding was recorded', { blocked: true });
+    }
+    const issues = state.issues;
+    if (issues.length > 0) {
+        const titles = issues.map((finding) => `[severity ${finding.severity}] ${finding.title}`).join('; ');
+        throw new AgentError('ASSERTION_FAILED', `exploration found ${issues.length} issue(s): ${titles}`);
+    }
+}
+//# sourceMappingURL=body.js.map

package/dist/explore/body.js.map

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

package/dist/explore/executor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The explorer: the built-in agent (`createAgent`) with exploration guidance
+ * appended to the project's and one tool added to the project's vocabulary,
+ * `report_finding`. Nothing else changes: budgets, loop guards, wind-down,
+ * secrets, origin policy, and the transcript are the harness's, and each
+ * exploration step runs as one ordinary `agent.act` step.
+ */
+import { type DefaultAgent } from '../agent/default-agent.ts';
+import type { StepExecutor } from '../agent/executor.ts';
+import type { ExploreState } from './state.ts';
+export declare const FINDING_TOOL_NAME = "report_finding";
+export interface ExplorerOptions {
+    readonly state: ExploreState;
+    /** The executor the agent the exploration runs as resolved to; undefined is the built-in agent. */
+    readonly from: StepExecutor | undefined;
+    /** Told when a hand-rolled executor is replaced. */
+    readonly notice: (message: string) => void;
+}
+/**
+ * Builds the explorer. An executor `createAgent` built lends its tools,
+ * guidance, model, and provider options; a hand-rolled one has no readable
+ * vocabulary and is replaced, with a notice, keeping the model it brought.
+ */
+export declare function createExplorer(options: ExplorerOptions): DefaultAgent;
+//# sourceMappingURL=executor.d.ts.map

package/dist/explore/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/explore/executor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AAYlD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,mGAAmG;IACnG,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,YAAY,CAgBrE"}

package/dist/explore/executor.js

@@ -0,0 +1,86 @@
+/**
+ * The explorer: the built-in agent (`createAgent`) with exploration guidance
+ * appended to the project's and one tool added to the project's vocabulary,
+ * `report_finding`. Nothing else changes: budgets, loop guards, wind-down,
+ * secrets, origin policy, and the transcript are the harness's, and each
+ * exploration step runs as one ordinary `agent.act` step.
+ */
+import { z } from 'zod';
+import { createAgent, isDefaultAgent } from '../agent/default-agent.js';
+import { defineTool, getToolContext } from '../agent/tool.js';
+import { asSdkLanguageModel } from '../config/agent.js';
+export const FINDING_TOOL_NAME = 'report_finding';
+/** Appended to the project's own guidance; the goal itself travels as agent context. */
+const EXPLORE_RULES = `Exploration mode: this run has no scripted test. Each step is an exploration charter the planner wrote toward the goal given in the project context.
+- Think like a curious first-time user hunting for bugs: exercise the flow the charter names end to end, with realistic inputs and edge cases. Interact, do not just look: fill forms with obviously made-up test data and submit them, save and come back to check what was kept, sign in with made-up credentials when none are configured, and when a list has several items act on one that is not the first and check that the right one changed.
+- On every screen, sanity-check beyond "it renders": totals equal the sum of their parts and quantities multiply; counts match the items listed; nothing is negative that cannot be; dates are plausible and in order, not an epoch default; copy has no template tokens, placeholders, or misspellings; every control does what its name says; what a screen claims happened (saved, added, removed) is true on the next screen; a password is never shown as you type it.
+- Report every defect with ${FINDING_TOOL_NAME} the moment the evidence is on screen, one call per distinct defect: what you expected, what the screen shows, and the actions that reach it. Do not save findings for the conclusion: a defect that appears only in a summary is lost, since the report reads the tool, not the prose. Findings listed under "reportedFindings" in the step parameters are already recorded: never report them again and spend no actions re-confirming them.
+- Accounts listed under "credentials" in the step parameters are yours to sign in with: type the username as text and fill the password with type_secret by the account's name. Never type a password as text, and never ask for one. If no type_secret tool is offered, this engine cannot fill a password securely: skip signing in, note it in the step summary, and explore what is reachable without it.
+- Report defects, not wishes. A defect is something the screen breaks or contradicts: a wrong value, a dead control, a navigation that lands wrong, a claim that turns out false, leaked template text, a misspelling. A missing feature, a design choice, a form the browser refuses to submit while a required field is empty, or something you merely expected is not a defect unless the screen or the goal promised it. A failed tool call, a refused action, or a limit of this harness is not a product defect either.
+- Stay inside the application under test. Do not destroy data that existed before this run (deleting accounts, wiping lists) unless the goal asks for it; creating and editing your own data is fine.
+- When the charter is covered, or nothing new is reachable within it, call complete_step. "passed" means you carried the charter out, however many defects you reported on the way: reported findings never make a step fail. "failed" is only for a charter the application would not let you carry out at all: a flow that cannot be completed, a page that cannot be reached. Keep to the charter: a step is one flow, not the whole app. The summary is read by the planner of the next step: say what was covered, what was found, and what looks worth exploring next.`;
+/**
+ * Builds the explorer. An executor `createAgent` built lends its tools,
+ * guidance, model, and provider options; a hand-rolled one has no readable
+ * vocabulary and is replaced, with a notice, keeping the model it brought.
+ */
+export function createExplorer(options) {
+    const { from } = options;
+    const base = isDefaultAgent(from) ? from.options : undefined;
+    if (from !== undefined && base === undefined) {
+        options.notice(`the configured agent "${from.name}" is a custom executor; explore runs the built-in agent instead` +
+            (from.model === undefined ? '' : ', with the model that executor brought'));
+    }
+    const carried = base === undefined && from?.model !== undefined ? { model: asSdkLanguageModel(from.model) } : {};
+    return createAgent({
+        ...base,
+        ...carried,
+        system: [base?.system, EXPLORE_RULES].filter((part) => part !== undefined && part.trim() !== '').join('\n\n'),
+        tools: { ...base?.tools, [FINDING_TOOL_NAME]: createFindingTool(options.state) },
+    });
+}
+const FINDING_SCHEMA = z.object({
+    title: z
+        .string()
+        .min(4)
+        .max(200)
+        .describe('A short, specific name for the defect, e.g. "Checkout total shows $0.00 with two items in the cart".'),
+    kind: z
+        .enum(['issue', 'warning'])
+        .describe('issue = a defect a user would hit: a broken flow, wrong data, a dead control, a navigation that lands wrong. warning = cosmetic or polish; blocks no task.'),
+    severity: z
+        .literal([1, 2, 3, 4, 5])
+        .describe('5: a core journey is impossible, data is lost, or money or security is wrong. 4: a core feature is broken but a workaround exists, or wrong money or quantity values are shown. 3: a secondary feature is broken, or wrong non-monetary content. 2: a cosmetic or layout defect that blocks nothing. 1: a trivial polish item (usually a warning).'),
+    expected: z.string().min(1).max(2000).describe('What a user would expect here.'),
+    actual: z.string().min(1).max(2000).describe('What the screen shows instead, quoted from the observation.'),
+    reproduction: z
+        .array(z.string().min(1).max(500))
+        .min(1)
+        .max(20)
+        .describe('The actions that reach the defect from the start of the app, one per entry.'),
+});
+/**
+ * The finding tool. Read-only: it observes the screen for the location and
+ * the evidence pixels, records the finding against the step in progress,
+ * keeps the pixels as a screenshot artifact of the step, and answers the
+ * model with the finding's number so it is not reported twice.
+ */
+function createFindingTool(state) {
+    return defineTool({
+        description: 'Report one product defect you have evidence of on the current screen: what you expected, what the screen shows, and how to reach it. Call it the moment the evidence is visible, once per distinct defect. Not for tool errors or refused actions.',
+        inputSchema: FINDING_SCHEMA,
+        execute: async (input, executionOptions) => {
+            const { observe, attachScreenshot } = getToolContext(executionOptions);
+            const observation = await observe({ pixels: true }).catch(() => undefined);
+            const finding = state.addFinding({ ...input, path: observation?.path, observationRevision: observation?.revision });
+            if (observation?.pixels !== undefined) {
+                // Evidence is worth keeping, never worth failing the finding for.
+                const artifactId = await attachScreenshot(observation.pixels, `finding-${finding.index + 1}`).catch(() => undefined);
+                if (artifactId !== undefined)
+                    state.attachEvidence(finding.id, artifactId);
+            }
+            return `Finding ${finding.index + 1} recorded (${finding.kind}, severity ${finding.severity}): ${finding.title}. Do not report it again; continue the charter or conclude the step.`;
+        },
+    }, { mutates: false });
+}
+//# sourceMappingURL=executor.js.map

package/dist/explore/executor.js.map

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

package/dist/explore/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `e2e explore`: a run whose one test is a goal. The project config is loaded
+ * as `run` loads it, the explorer replaces the executor of the agent the run
+ * uses, and the exploration body is registered in memory as the run's only
+ * test, so the reporters, `report.json`, artifacts, video, the AI trace, and
+ * the exit codes are the runner's own. The record of the exploration rides
+ * along as `run.explore`.
+ */
+import type { ReportExplore } from '../report/build.ts';
+import { type RunOutcome } from '../run/runner.ts';
+import type { BuiltinReporter, E2EConfig } from '../types.ts';
+/** Exploration steps per run: breadth first, and diminishing returns come fast. */
+export declare const STEP_BOUNDS: {
+    readonly min: 1;
+    readonly max: 12;
+    readonly default: 8;
+};
+/** The run's wall clock in milliseconds: three to fifteen minutes. */
+export declare const TIMEOUT_BOUNDS: {
+    readonly min: 180000;
+    readonly max: 900000;
+    readonly default: 600000;
+};
+export interface ExploreOptions {
+    readonly goal?: string | undefined;
+    readonly cwd?: string | undefined;
+    readonly configPath?: string | undefined;
+    /** The target to explore; with several configured and none named, the first is explored. */
+    readonly target?: string | undefined;
+    /** The configured agent (`agents.<name>`) the exploration runs as; default: `agents.default`. */
+    readonly agent?: string | undefined;
+    readonly maxSteps?: number | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly headed?: boolean | undefined;
+    readonly reporters?: readonly BuiltinReporter[] | undefined;
+    readonly artifactsDir?: string | undefined;
+    readonly debug?: boolean | undefined;
+    readonly aiTrace?: boolean | undefined;
+    readonly video?: boolean | undefined;
+    readonly interruptSignal?: AbortSignal | undefined;
+    readonly forceSignal?: AbortSignal | undefined;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /**
+     * A config value instead of a discovered file, for the test harness: it may
+     * hold a scripted model, which no config file could. `cwd` is the project
+     * root then.
+     */
+    readonly rawConfig?: E2EConfig | undefined;
+    /** Notices decided before the run starts: the target chosen, a replaced executor. */
+    readonly notice?: ((message: string) => void) | undefined;
+}
+export interface ExploreOutcome extends RunOutcome {
+    readonly explore: ReportExplore;
+}
+/**
+ * Runs one exploration and returns the run's outcome with the exploration
+ * record. The config is resolved once here, with the agent `--agent` named,
+ * so the target, the agent the explorer is built from, and the credential
+ * inventory are what the run resolves too; a config that does not resolve,
+ * an unknown agent, or an unknown target is an error before anything starts,
+ * as a bad flag is.
+ */
+export declare function explore(options?: ExploreOptions): Promise<ExploreOutcome>;
+//# sourceMappingURL=index.d.ts.map

package/dist/explore/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/explore/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAO,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAe,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAQ3E,mFAAmF;AACnF,eAAO,MAAM,WAAW;aAAK,GAAG,EAAE,CAAC;aAAE,GAAG,EAAE,EAAE;aAAE,OAAO,EAAE,CAAC;CAAW,CAAC;AACpE,sEAAsE;AACtE,eAAO,MAAM,cAAc;aAAK,GAAG,EAAE,MAAO;aAAE,GAAG,EAAE,MAAO;aAAE,OAAO,EAAE,MAAO;CAAW,CAAC;AAkBxF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,iGAAiG;IACjG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC3C,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC3D;AAED,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CA6CnF"}

package/dist/explore/index.js

@@ -0,0 +1,183 @@
+/**
+ * `e2e explore`: a run whose one test is a goal. The project config is loaded
+ * as `run` loads it, the explorer replaces the executor of the agent the run
+ * uses, and the exploration body is registered in memory as the run's only
+ * test, so the reporters, `report.json`, artifacts, video, the AI trace, and
+ * the exit codes are the runner's own. The record of the exploration rides
+ * along as `run.explore`.
+ */
+import { MAX_PARAMS_BYTES } from '../agent/act-validation.js';
+import { isStepExecutor } from '../agent/executor.js';
+import { selectTargets } from '../collect/select.js';
+import { discoverConfig, loadConfigModule, missingConfigError } from '../config/load.js';
+import { resolveConfig } from '../config/resolve.js';
+import { ConfigurationError } from '../internal/errors.js';
+import { run } from '../run/runner.js';
+import { createExploreBody } from './body.js';
+import { createExplorer } from './executor.js';
+import { exploreReporter } from './reporter.js';
+import { ExploreState } from './state.js';
+const DEFAULT_GOAL = 'Explore the app and find bugs';
+/** Exploration steps per run: breadth first, and diminishing returns come fast. */
+export const STEP_BOUNDS = { min: 1, max: 12, default: 8 };
+/** The run's wall clock in milliseconds: three to fifteen minutes. */
+export const TIMEOUT_BOUNDS = { min: 180_000, max: 900_000, default: 600_000 };
+const MAX_GOAL_CHARS = 2_000;
+/** Each step's action and model-call budget when the config sets none: a charter is longer than a scripted step. */
+const DEFAULT_STEP_BUDGET = 40;
+/** One charter's own deadline; the run's remaining time caps it. */
+const STEP_TIMEOUT_MS = 240_000;
+/** Added to the test timeout so the body's own clock ends the exploration before the attempt's does. */
+const TIMEOUT_GRACE_MS = 60_000;
+/** The virtual file the report and the reporters show for the exploration. */
+const EXPLORE_FILE = 'explore';
+/**
+ * Every charter carries every configured account as a step parameter, and
+ * step parameters have a size limit. The inventory takes at most a quarter of
+ * it, leaving room for the findings that ride along, so an oversized one is a
+ * configuration error before anything starts and not a failed first step.
+ */
+const MAX_CREDENTIAL_BYTES = MAX_PARAMS_BYTES / 4;
+/**
+ * Runs one exploration and returns the run's outcome with the exploration
+ * record. The config is resolved once here, with the agent `--agent` named,
+ * so the target, the agent the explorer is built from, and the credential
+ * inventory are what the run resolves too; a config that does not resolve,
+ * an unknown agent, or an unknown target is an error before anything starts,
+ * as a bad flag is.
+ */
+export async function explore(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const notice = options.notice ?? (() => undefined);
+    const goal = resolveGoal(options.goal);
+    const budgets = {
+        maxSteps: resolveBounded(options.maxSteps, STEP_BOUNDS, 'maxSteps'),
+        timeoutMs: resolveBounded(options.timeoutMs, TIMEOUT_BOUNDS, 'timeout'),
+    };
+    const { raw, projectRoot } = await loadRawConfig(options, cwd);
+    // Nothing replays an exploration, and a retry would explore twice.
+    const rawConfig = { ...raw, cache: 'off', retries: 0 };
+    const resolved = resolveConfig(rawConfig, { projectRoot, env, cli: options.agent === undefined ? {} : { agent: options.agent } });
+    const target = pickTarget(resolved.targets, options.target, notice);
+    const accounts = credentialAccounts(resolved.credentials);
+    if (resolved.agentName !== 'default')
+        notice(`exploring with agent "${resolved.agentName}"`);
+    const state = new ExploreState(goal, budgets);
+    const explorer = createExplorer({ state, from: resolved.agent.executor, notice });
+    const outcome = await run({
+        cwd: projectRoot,
+        rawConfig: {
+            ...rawConfig,
+            agents: { ...rawConfig.agents, [resolved.agentName]: exploreAgentConfig(rawConfig.agents?.[resolved.agentName], explorer) },
+            reporters: [...(rawConfig.reporters ?? ['list']), exploreReporter(state)],
+        },
+        agent: options.agent,
+        env,
+        tests: {
+            file: EXPLORE_FILE,
+            registration: exploreRegistration(state, target.app.base !== undefined, accounts),
+            explore: () => state.snapshot(),
+        },
+        targetIds: [target.name],
+        headed: options.headed,
+        reporters: options.reporters,
+        artifactsDir: options.artifactsDir,
+        debug: options.debug,
+        aiTrace: options.aiTrace,
+        video: options.video,
+        interruptSignal: options.interruptSignal,
+        forceSignal: options.forceSignal,
+    });
+    return { ...outcome, explore: state.snapshot() };
+}
+async function loadRawConfig(options, cwd) {
+    if (options.rawConfig !== undefined)
+        return { raw: options.rawConfig, projectRoot: cwd };
+    const discovered = discoverConfig(cwd, options.configPath);
+    if (discovered.configPath === undefined)
+        throw missingConfigError(cwd);
+    return { raw: await loadConfigModule(discovered.configPath), projectRoot: discovered.projectRoot };
+}
+function resolveGoal(goal) {
+    const trimmed = goal?.trim() ?? '';
+    if (trimmed === '')
+        return DEFAULT_GOAL;
+    if (trimmed.length > MAX_GOAL_CHARS) {
+        throw new ConfigurationError('INVALID_CONFIG', `the goal must be at most ${MAX_GOAL_CHARS} characters, got ${trimmed.length}`);
+    }
+    return trimmed;
+}
+function resolveBounded(value, bounds, label) {
+    if (value === undefined)
+        return bounds.default;
+    if (!Number.isSafeInteger(value) || value < bounds.min || value > bounds.max) {
+        throw new ConfigurationError('INVALID_CONFIG', `${label} must be an integer from ${bounds.min} through ${bounds.max}, got ${String(value)}`);
+    }
+    return value;
+}
+/**
+ * The target to explore: the one `--target` names (an unknown one is
+ * `UNKNOWN_TARGET`, as for `run`), else the first configured, with a notice
+ * when there are several.
+ */
+function pickTarget(targets, requested, notice) {
+    const chosen = selectTargets(targets, requested === undefined ? undefined : [requested])[0];
+    if (chosen === undefined)
+        throw new Error('unreachable: a resolved config declares at least one target');
+    if (requested === undefined && targets.length > 1) {
+        notice(`exploring target "${chosen.name}"; pass --target to explore another`);
+    }
+    return chosen;
+}
+/**
+ * The agent block the exploration runs as: the project's own options with the
+ * explorer as the executor, and per-step budgets that default higher than a
+ * scripted step's, a charter being longer. A bare executor has no options to
+ * keep; the explorer already lent from it what it could.
+ */
+function exploreAgentConfig(entry, explorer) {
+    const block = entry === undefined || isStepExecutor(entry) ? {} : entry;
+    return {
+        ...block,
+        executor: explorer,
+        maxSteps: block.maxSteps ?? DEFAULT_STEP_BUDGET,
+        maxModelCalls: block.maxModelCalls ?? DEFAULT_STEP_BUDGET,
+    };
+}
+/**
+ * The accounts every charter carries, bounded to what a step parameter holds.
+ * Measured as the step sees them: the usernames and the secret placeholders
+ * the passwords become there.
+ */
+function credentialAccounts(credentials) {
+    const accounts = [...credentials.values()].map((credential) => ({ name: credential.name, username: credential.username }));
+    const carried = Object.fromEntries(accounts.map((account) => [account.name, { username: account.username, password: { kind: 'secret', name: account.name, purpose: 'password' } }]));
+    const bytes = Buffer.byteLength(JSON.stringify({ credentials: carried }));
+    if (bytes > MAX_CREDENTIAL_BYTES) {
+        throw new ConfigurationError('INVALID_CONFIG', `explore carries every configured credential into each step: ${String(accounts.length)} account(s) serialize to ${String(bytes)} bytes, the maximum is ${String(MAX_CREDENTIAL_BYTES)}; explore with a config that declares fewer`);
+    }
+    return accounts;
+}
+/** The one-test registration: the goal is the title, the body is the exploration loop. */
+function exploreRegistration(state, openApp, accounts) {
+    const title = state.goal;
+    const test = {
+        kind: 'test',
+        title,
+        titlePath: [title],
+        declarationIndex: 0,
+        options: {
+            timeout: state.budgets.timeoutMs + TIMEOUT_GRACE_MS,
+            retries: 0,
+            agentContext: `Exploration goal: ${state.goal}`,
+        },
+        sessions: [],
+        fn: createExploreBody({ state, stepTimeoutMs: STEP_TIMEOUT_MS, openApp, accounts }),
+        group: undefined,
+        mode: 'normal',
+        source: undefined,
+    };
+    return { tests: [test], hooks: [] };
+}
+//# sourceMappingURL=index.js.map

package/dist/explore/index.js.map

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