@e2edev/e2e 0.10.0 → 0.12.0

package/dist/explore/index.js

@@ -0,0 +1,185 @@
+/**
+ * `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 ? {} : { agents: [options.agent] } });
+    const target = pickTarget(resolved.targets, options.target, notice);
+    const accounts = credentialAccounts(resolved.credentials);
+    // An exploration runs as exactly one agent: the one named, else `default`.
+    const agentName = resolved.agentNames[0];
+    if (agentName !== 'default')
+        notice(`exploring with agent "${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, [agentName]: exploreAgentConfig(rawConfig.agents?.[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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"}

package/dist/explore/plan.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The planner: between exploration steps, one structured model call decides
+ * the next charter or finishes the run. It runs as an `agent.extract` step,
+ * so it reads the current screen and the ledger of prior steps the same way
+ * every judgment does, under the same budgets and repair loop.
+ */
+import { z } from 'zod';
+import type { Agent } from '../types.ts';
+import { type ExploreState } from './state.ts';
+/**
+ * A flat object with every field required rather than a union: OpenAI's
+ * strict structured output rejects a schema whose `required` omits a
+ * property, and every provider renders a flat object. Fields the decision
+ * does not use are empty strings. The shape is lenient on purpose: a model
+ * that puts the whole charter into `title` and leaves `instruction` empty
+ * (seen live) has still planned a step, and `repairPlan` derives the missing
+ * field rather than spending the repair round on it.
+ */
+export declare const PLAN_SCHEMA: z.ZodObject<{
+    decision: z.ZodEnum<{
+        finish: "finish";
+        step: "step";
+    }>;
+    title: z.ZodString;
+    instruction: z.ZodString;
+    summary: z.ZodString;
+}, z.core.$strip>;
+type PlanAnswer = z.output<typeof PLAN_SCHEMA>;
+export type PlanDecision = {
+    readonly kind: 'step';
+    readonly title: string;
+    readonly instruction: string;
+} | {
+    readonly kind: 'finish';
+    readonly summary: string;
+};
+/** One configured credential the explorer can sign in with, by name; the password stays out of every prompt. */
+export interface PlanAccount {
+    readonly name: string;
+    readonly username: string;
+}
+export interface PlanRequest {
+    /** The run must end now; the planner is asked for the closing assessment only. */
+    readonly mustFinish: boolean;
+    /** The accounts the explorer can sign in with. */
+    readonly accounts?: readonly PlanAccount[] | undefined;
+    /** Why it must end, in the planner's prompt. */
+    readonly reason?: string | undefined;
+    readonly remainingMs: number;
+    readonly timeoutMs: number;
+}
+/** Asks the model for the next charter or the closing assessment. */
+export declare function planNext(agent: Agent, state: ExploreState, request: PlanRequest): Promise<PlanDecision>;
+/**
+ * The decision, after the repairs live providers' answers have needed. Every
+ * repair the planner makes is here:
+ *
+ * - Digit runs a provider pads a field with (seen live: a title followed by
+ *   hundreds of `1234567890`) are removed; they carry no meaning and would
+ *   otherwise become the charter's tail. The threshold sits past any number a
+ *   charter can mean: phone numbers, order ids, card numbers, and amounts all
+ *   stop short of twenty digits.
+ * - A step with only one of `title` and `instruction` filled has the other
+ *   derived: a charter with no title takes its first clause, a title with no
+ *   charter is the charter.
+ *
+ * Length is not repaired here: the grammar accepts long fields, and the state
+ * clips them to the report's ceilings when the step opens.
+ */
+export declare function repairPlan(answer: PlanAnswer): PlanDecision;
+/** The planner's instruction: the goal, the record so far, the budget, and how to decide. */
+export declare function planInstruction(state: ExploreState, request: PlanRequest): string;
+export {};
+//# sourceMappingURL=plan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/explore/plan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAahE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;;;;;iBAepB,CAAC;AAEL,KAAK,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAE/C,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,gHAAgH;AAChH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC;IACvD,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qEAAqE;AACrE,wBAAsB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAE7G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CAS3D;AAmBD,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CA2DjF"}

package/dist/explore/plan.js

@@ -0,0 +1,149 @@
+/**
+ * The planner: between exploration steps, one structured model call decides
+ * the next charter or finishes the run. It runs as an `agent.extract` step,
+ * so it reads the current screen and the ledger of prior steps the same way
+ * every judgment does, under the same budgets and repair loop.
+ */
+import { z } from 'zod';
+import { MAX_TITLE_CHARS } from './state.js';
+const MIN_SUMMARY_CHARS = 10;
+/** A title derived from an instruction stops at the first clause or here. */
+const DERIVED_TITLE_CHARS = 80;
+/**
+ * The most the grammar accepts in one field. Well above the report's ceilings,
+ * which the state clips to when the step opens: a model that pours a whole
+ * charter into one field (seen live, past 2000 characters) has still planned
+ * a step, and a rejection would cost a repair round for nothing.
+ */
+const MAX_FIELD_CHARS = 8_000;
+/**
+ * A flat object with every field required rather than a union: OpenAI's
+ * strict structured output rejects a schema whose `required` omits a
+ * property, and every provider renders a flat object. Fields the decision
+ * does not use are empty strings. The shape is lenient on purpose: a model
+ * that puts the whole charter into `title` and leaves `instruction` empty
+ * (seen live) has still planned a step, and `repairPlan` derives the missing
+ * field rather than spending the repair round on it.
+ */
+export const PLAN_SCHEMA = z
+    .object({
+    decision: z.enum(['step', 'finish']),
+    title: z.string().max(MAX_FIELD_CHARS).describe('For a step: the area or flow in a few words. Empty for finish.'),
+    instruction: z.string().max(MAX_FIELD_CHARS).describe('For a step: the concrete charter. Empty for finish.'),
+    summary: z.string().max(MAX_FIELD_CHARS).describe('For finish: the overall assessment. Empty for a step.'),
+})
+    .superRefine((value, context) => {
+    if (value.decision === 'step') {
+        if (`${value.title}${value.instruction}`.trim() === '') {
+            context.addIssue({ code: 'custom', path: ['instruction'], message: 'a step needs a concrete instruction' });
+        }
+    }
+    else if (value.summary.trim().length < MIN_SUMMARY_CHARS) {
+        context.addIssue({ code: 'custom', path: ['summary'], message: 'finishing needs an overall assessment' });
+    }
+});
+/** Asks the model for the next charter or the closing assessment. */
+export async function planNext(agent, state, request) {
+    return repairPlan(await agent.extract(planInstruction(state, request), { schema: PLAN_SCHEMA, timeout: request.timeoutMs }));
+}
+/**
+ * The decision, after the repairs live providers' answers have needed. Every
+ * repair the planner makes is here:
+ *
+ * - Digit runs a provider pads a field with (seen live: a title followed by
+ *   hundreds of `1234567890`) are removed; they carry no meaning and would
+ *   otherwise become the charter's tail. The threshold sits past any number a
+ *   charter can mean: phone numbers, order ids, card numbers, and amounts all
+ *   stop short of twenty digits.
+ * - A step with only one of `title` and `instruction` filled has the other
+ *   derived: a charter with no title takes its first clause, a title with no
+ *   charter is the charter.
+ *
+ * Length is not repaired here: the grammar accepts long fields, and the state
+ * clips them to the report's ceilings when the step opens.
+ */
+export function repairPlan(answer) {
+    if (answer.decision === 'finish')
+        return { kind: 'finish', summary: unpad(answer.summary) };
+    const title = unpad(answer.title);
+    const instruction = unpad(answer.instruction);
+    const charter = instruction === '' ? title : instruction;
+    // A title that stood in for the charter is a heading only while it is short.
+    const longest = instruction === '' ? DERIVED_TITLE_CHARS : MAX_TITLE_CHARS;
+    const heading = title !== '' && title.length <= longest ? title : deriveTitle(charter);
+    return { kind: 'step', title: heading, instruction: charter };
+}
+function unpad(text) {
+    return text.replace(/\s*\d{20,}\s*/g, ' ').trim();
+}
+function deriveTitle(charter) {
+    const clause = charter.split(/[.:;\n]/, 1)[0].trim();
+    const short = clause === '' ? charter : clause;
+    return short.length <= DERIVED_TITLE_CHARS ? short : `${short.slice(0, DERIVED_TITLE_CHARS - 1)}…`;
+}
+const STATUS_MARKS = {
+    passed: 'passed',
+    failed: 'FAILED',
+    blocked: 'blocked',
+    exhausted: 'ended at its limit',
+};
+/** The planner's instruction: the goal, the record so far, the budget, and how to decide. */
+export function planInstruction(state, request) {
+    const used = state.steps.length;
+    const minutesLeft = Math.max(0, Math.round(request.remainingMs / 60_000));
+    const steps = used === 0
+        ? '(none yet: this is the first step)'
+        : state.steps
+            .map((step) => `${step.index}. [${STATUS_MARKS[step.status]}] ${step.title}${step.summary === undefined ? '' : ` — ${step.summary}`}`)
+            .join('\n');
+    const findings = state.findings.length === 0
+        ? '(none yet)'
+        : state.findings.map((finding) => `- [${finding.kind}, severity ${finding.severity}] ${finding.title}`).join('\n');
+    const header = [
+        request.mustFinish
+            ? 'Finish an exploratory test run with your overall assessment.'
+            : 'Plan the next step of an exploratory test run, or finish it.',
+        '',
+        `Goal: ${state.goal}`,
+        `Budget: ${used} of ${state.budgets.maxSteps} steps used, about ${minutesLeft} minute(s) left.`,
+        '',
+        'Steps so far:',
+        steps,
+        '',
+        'Findings so far:',
+        findings,
+        ...(request.accounts === undefined || request.accounts.length === 0
+            ? []
+            : [
+                '',
+                'Accounts the agent can sign in with (it fills the password itself, by name):',
+                ...request.accounts.map((account) => `- ${account.name} (username: ${account.username})`),
+            ]),
+        '',
+    ];
+    if (request.mustFinish) {
+        return [
+            ...header,
+            `The run must end now: ${request.reason ?? 'its budget is spent'}.`,
+            'Respond with {"decision": "finish", "title": "", "instruction": "", "summary": "..."}: the overall assessment in two to five sentences,',
+            'what was explored, the key findings, and your verdict on the goal. Ground it in the steps and findings above.',
+        ].join('\n');
+    }
+    return [
+        ...header,
+        'Decide from the goal, the steps so far, and the current screen:',
+        '- "step": the next exploration charter. "title" names the area or flow in a few words. "instruction" is a concrete,',
+        '  self-contained charter for an agent that sees only the screen and that text: which flow to exercise, what inputs',
+        '  to try, what to check. One flow or screen per step, sized for five to fifteen actions; split anything bigger.',
+        '  Ask the agent to interact, not only to look: submit forms with made-up test data, save and revisit, sign in with',
+        '  the accounts listed above (or made-up credentials when none are configured), act on a non-first item of a list. Prefer breadth: touch the main',
+        '  flows the goal names before drilling deeper into one. Do not re-test an area a passed step already covered, and',
+        '  never plan a step to re-confirm a finding already recorded above. When a step ended at its limit, continue where',
+        '  it stopped or move on. When a step summary mentions something odd that is not among the findings, spend the next',
+        '  step confirming it.',
+        '- "finish": the goal is covered, or nothing new is reachable. "summary" is the overall assessment in two to',
+        '  five sentences: what was explored, the key findings, and your verdict on the goal.',
+        'Respond with every field present: {"decision": "step", "title": "...", "instruction": "...", "summary": ""} or {"decision": "finish", "title": "", "instruction": "", "summary": "..."}.',
+    ].join('\n');
+}
+//# sourceMappingURL=plan.js.map

package/dist/explore/plan.js.map

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

package/dist/explore/reporter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The exploration summary under the run summary: a `Reporter` whose
+ * `onRunFinished` rows the list reporter prints, so the findings appear where
+ * a reporter's own rows do, and the JSON reporter is left to the report.
+ */
+import type { Reporter, ReporterSummary } from '../types.ts';
+import type { ExploreState } from './state.ts';
+export declare function exploreReporter(state: ExploreState): Reporter;
+/** The rows: what was explored, what was found, one row per finding, and the assessment. */
+export declare function summaryRows(state: ExploreState): ReporterSummary;
+//# sourceMappingURL=reporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../src/explore/reporter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,QAAQ,CAK7D;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAgChE"}

package/dist/explore/reporter.js

@@ -0,0 +1,54 @@
+/**
+ * The exploration summary under the run summary: a `Reporter` whose
+ * `onRunFinished` rows the list reporter prints, so the findings appear where
+ * a reporter's own rows do, and the JSON reporter is left to the report.
+ */
+export function exploreReporter(state) {
+    return {
+        name: 'explore',
+        onRunFinished: async () => summaryRows(state),
+    };
+}
+/** The rows: what was explored, what was found, one row per finding, and the assessment. */
+export function summaryRows(state) {
+    const counts = { passed: 0, failed: 0, blocked: 0, exhausted: 0 };
+    for (const step of state.steps)
+        counts[step.status] += 1;
+    const parts = [
+        `${counts.passed} passed`,
+        ...(counts.failed > 0 ? [`${counts.failed} failed`] : []),
+        ...(counts.exhausted > 0 ? [`${counts.exhausted} ended at their limit`] : []),
+        ...(counts.blocked > 0 ? [`${counts.blocked} blocked`] : []),
+    ];
+    const issues = state.issues.length;
+    const warnings = state.findings.length - issues;
+    const rows = [
+        {
+            label: 'Explored',
+            text: `${state.steps.length} step${state.steps.length === 1 ? '' : 's'} (${parts.join(', ')}); ended: ${ENDED_TEXT[state.ended]}`,
+        },
+        {
+            label: 'Findings',
+            text: state.findings.length === 0
+                ? 'none'
+                : `${issues} issue${issues === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}`,
+        },
+    ];
+    for (const finding of [...state.findings].toSorted((a, b) => b.severity - a.severity || a.index - b.index)) {
+        rows.push({
+            label: `  S${finding.severity} ${finding.kind}`,
+            text: `${finding.title}${finding.path === undefined ? '' : ` (${finding.path})`}`,
+        });
+    }
+    if (state.summary !== undefined)
+        rows.push({ label: 'Assessment', text: state.summary });
+    return rows;
+}
+const ENDED_TEXT = {
+    finished: 'the agent covered the goal',
+    'step-limit': 'the step limit was reached',
+    time: 'the time budget ran out',
+    stuck: 'steps kept failing',
+    aborted: 'the run was cut short',
+};
+//# sourceMappingURL=reporter.js.map

package/dist/explore/reporter.js.map

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

package/dist/explore/state.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The record of one exploration: the goal, its budgets, the steps the agent
+ * planned and ran, and the findings it reported. One instance is shared by
+ * the planner, the explorer's finding tool, the exploration body, and the
+ * summary reporter, and its snapshot becomes `run.explore` in the report.
+ * The state is the report boundary: every free text is bounded to the
+ * schema's ceilings here, and nowhere else.
+ */
+import type { ReportExplore, ReportExploreFinding, ReportExploreStep } from '../report/build.ts';
+export interface ExploreBudgets {
+    readonly maxSteps: number;
+    readonly timeoutMs: number;
+}
+/** A finding as the tool reports it; the state assigns identity, position, and time. */
+export type FindingInput = Omit<ReportExploreFinding, 'id' | 'index' | 'step' | 'reportedAt' | 'artifactId'>;
+/** A step as opened: title and charter bounded to the report's ceilings, which is what the step runs with. */
+export type OpenedStep = Pick<ReportExploreStep, 'index' | 'title' | 'instruction'>;
+/** Ceilings mirroring `schema/report-v1.schema.json` `explore`. */
+export declare const MAX_TITLE_CHARS = 200;
+export declare class ExploreState {
+    #private;
+    readonly goal: string;
+    readonly budgets: ExploreBudgets;
+    private readonly now;
+    readonly steps: ReportExploreStep[];
+    readonly findings: ReportExploreFinding[];
+    constructor(goal: string, budgets: ExploreBudgets, now?: () => number);
+    /** Why exploration stopped; `aborted` until `end` says otherwise. */
+    get ended(): ReportExplore['ended'];
+    /** The agent's closing assessment, once it gave one. */
+    get summary(): string | undefined;
+    /** Opens the next step; the index is one-based. */
+    beginStep(title: string, instruction: string): OpenedStep;
+    /** Closes the open step with its outcome. */
+    endStep(status: ReportExploreStep['status'], summary?: string, errorCode?: string): ReportExploreStep;
+    /** Records one finding against the step in progress. */
+    addFinding(input: FindingInput): ReportExploreFinding;
+    /** Attaches the evidence screenshot kept for a finding, by its artifact id. */
+    attachEvidence(id: string, artifactId: string): void;
+    /** Closes the record: why exploration stopped and, when the agent gave one, its closing assessment. */
+    end(ended: ReportExplore['ended'], summary?: string): void;
+    get issues(): readonly ReportExploreFinding[];
+    /**
+     * How many steps in a row made no progress, newest first: failed or blocked
+     * without recording a finding. A failed step that reported a defect did its
+     * job, and a step that ended at its budget is a time-boxed charter, not a
+     * failure; neither breaks the streak nor adds to it.
+     */
+    consecutiveFailures(): number;
+    snapshot(): ReportExplore;
+}
+/**
+ * Trims and bounds free text so the report stays inside the schema's
+ * ceilings. Counted in code points, as the schema counts, so a cut never
+ * splits a surrogate pair.
+ */
+export declare function clip(text: string, max: number): string;
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/explore/state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEjG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,oBAAoB,EAAE,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC;AAE7G,8GAA8G;AAC9G,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,OAAO,GAAG,aAAa,CAAC,CAAC;AAEpF,mEAAmE;AACnE,eAAO,MAAM,eAAe,MAAM,CAAC;AAanC,qBAAa,YAAY;;IAQrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,cAAc;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG;IATtB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAM;IACzC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,EAAE,CAAM;IAK/C,YACW,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACf,GAAG,GAAE,MAAM,MAAiB,EAC3C;IAEJ,qEAAqE;IACrE,IAAI,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,CAElC;IAED,wDAAwD;IACxD,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,mDAAmD;IACnD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAWxD;IAED,6CAA6C;IAC7C,OAAO,CAAC,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAgBpG;IAED,wDAAwD;IACxD,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,oBAAoB,CAiBpD;IAED,+EAA+E;IAC/E,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAInD;IAED,uGAAuG;IACvG,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAGzD;IAED,IAAI,MAAM,IAAI,SAAS,oBAAoB,EAAE,CAE5C;IAED;;;;;OAKG;IACH,mBAAmB,IAAI,MAAM,CAU5B;IAED,QAAQ,IAAI,aAAa,CASxB;CACF;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAItD"}