explorbot 0.4.3 → 0.4.4

package/dist/src/config.js

@@ -27,6 +27,7 @@ export const PROVIDERS = {
 };
 export const MODEL_ROLES = ['model', 'visionModel', 'agenticModel'];
 let cachedOutputRoot = null;
+let runOutputDir = null;
 const config = {
     playwright: {
         browser: 'chromium',
@@ -49,6 +50,7 @@ export const EXPLORBOT_ENV_VARS = [
     { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
     { name: 'EXPLORBOT_SPEC', description: 'Docbot application spec directory or index.md, used as page knowledge' },
     { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
+    { name: 'EXPLORBOT_API_HEADERS', description: 'Headers sent with every API request, one "Name: value" per line', secret: true },
     { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
     { name: 'EXPLORBOT_MAX_DURATION', description: 'Wall-clock budget in minutes for an explore run; same as --max-duration' },
 ];
@@ -213,6 +215,7 @@ export class ConfigParser {
     // For testing purposes only
     static resetForTesting() {
         cachedOutputRoot = null;
+        runOutputDir = null;
         if (ConfigParser.instance) {
             ConfigParser.instance.config = null;
             ConfigParser.instance.configPath = null;
@@ -441,9 +444,20 @@ export class ConfigParser {
         }
     }
 }
+export function setOutputDir(dir) {
+    runOutputDir = dir;
+}
 export function outputPath(...segments) {
+    if (runOutputDir)
+        return path.join(runOutputDir, ...segments);
     return path.join(ConfigParser.getInstance().getOutputDir(), ...segments);
 }
+export function agentSettings(config, agent) {
+    const ai = (config.ai ??= { model: null });
+    const agents = (ai.agents ??= {});
+    agents[agent] ??= {};
+    return agents[agent];
+}
 export async function resolveModel(spec, role = 'model') {
     const separator = spec.indexOf('/');
     if (separator > 0) {

package/dist/src/state-manager.js

@@ -60,12 +60,16 @@ export class StateManager {
     updateState(actionResult, codeBlock, trigger = 'manual') {
         const previousState = this.currentState;
         const previousHash = previousState?.hash;
+        const hashChanged = actionResult.hash !== previousHash;
+        if (!hashChanged && previousState?.verifications) {
+            const stillTrue = Object.entries(previousState.verifications).filter(([, passed]) => passed);
+            actionResult.verifications = { ...Object.fromEntries(stillTrue), ...actionResult.verifications };
+        }
         const newState = actionResult;
         this.currentState = newState;
         this.currentState.id = this.nextStateId++;
         if (newState.url)
             this.allVisitedUrls.add(normalizeUrl(newState.url));
-        const hashChanged = actionResult.hash !== previousHash;
         const regionOpened = !hashChanged && this.regionOpened(previousState, newState);
         if (hashChanged || regionOpened) {
             const transition = {

package/docs/api-testing/basics.md

@@ -30,7 +30,7 @@ export default {
 
 - **`baseEndpoint`** (required) — the base URL prepended to every request. Test steps use relative paths like `/users`; Curler adds the base for you.
 - **`spec`** (required) — one or more OpenAPI specs, given as HTTP(S) URLs or local file paths, in YAML or JSON. Chief uses the spec to plan; Curler uses it to look up schemas. Both agents refuse to run without one.
-- **`headers`** — sent with every request. This is where API keys and auth tokens go.
+- **`headers`** — sent with every request. This is where API keys and auth tokens go. `-H "Name: value"` on the command line and `EXPLORBOT_API_HEADERS` add to them without a config file.
 
 See the [full configuration reference](../reference/configuration.md) for every option and [providers](../basics/providers.md) for choosing an AI model.
 
@@ -60,16 +60,24 @@ A matching `teardown` hook runs after all tests finish — use it to clean up da
 
 Chief and Curler need three things: where the API is, what its spec says, and how to authenticate. Pass all three on the command line and no config file is needed:
 
+```bash
+npx explorbot api explore https://api.example.com/v1 \
+  --spec ./openapi.yaml \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+`api explore` takes the base endpoint as its argument, so one line covers the whole run: it plans in every style, executes each plan, and reports the totals. The other commands take a path within the API and read the base from `--endpoint`:
+
 ```bash
 npx explorbot api plan /users \
   --endpoint https://api.example.com/v1 \
   --spec ./openapi.yaml \
-  --knowledge 'Send X-Api-Key: ${env.API_KEY} on every request'
+  -H "Authorization: Bearer $TOKEN"
 ```
 
-`--endpoint` and `--spec` each have an environment twin — `EXPLORBOT_URL` and `EXPLORBOT_API_SPEC` — and the flag wins when both are set. `--knowledge` adds to the facts `EXPLORBOT_KNOWLEDGE` and `EXPLORBOT_KNOWLEDGE_FILE` bring in rather than replacing them. Configure your models once with `npx explorbot init --global` and every run stores its plans and requests per host under `~/.explorbot/sites/<host>/`, so a later `api test` against the same API picks up where the last one left off. Knowledge given on the command line lasts for the run; `api know` is what writes it down.
+Each flag has an environment twin — `EXPLORBOT_URL`, `EXPLORBOT_API_SPEC` and `EXPLORBOT_API_HEADERS` — and the flag wins when both are set. `-H` is repeatable and takes one `Name: value` per use; the variable takes one per line. Headers land on every request, the startup health check included, and merge over any `headers` a config file sets. `--knowledge` adds to the facts `EXPLORBOT_KNOWLEDGE` and `EXPLORBOT_KNOWLEDGE_FILE` bring in rather than replacing them. Configure your models once with `npx explorbot init --global` and every run stores its plans and requests per host under `~/.explorbot/sites/<host>/`, so a later `api test` against the same API picks up where the last one left off. Knowledge given on the command line lasts for the run; `api know` is what writes it down.
 
-`--endpoint` keeps its path prefix: given `https://api.example.com/v1`, steps stay relative (`/users`) and Curler sends them to `https://api.example.com/v1/users`. `api test`, which takes a plan file rather than an endpoint, reads it from the flag or the variable.
+The base endpoint keeps its path prefix: given `https://api.example.com/v1`, steps stay relative (`/users`) and Curler sends them to `https://api.example.com/v1/users`. `api test`, which takes a plan file rather than an endpoint, reads the base from the flag or the variable.
 
 ### A dedicated API project
 

package/docs/reference/commands.md

@@ -118,6 +118,7 @@ EXPLORBOT_AI_PROVIDER=openrouter \
 | `EXPLORBOT_KNOWLEDGE_FILE` | Path to a knowledge markdown file |
 | `EXPLORBOT_SPEC` | Docbot application spec directory or index.md, used as page knowledge |
 | `EXPLORBOT_API_SPEC` | OpenAPI spec path for the API boat |
+| `EXPLORBOT_API_HEADERS` | Headers sent with every API request, one "Name: value" per line |
 | `EXPLORBOT_NO_BANNER` | Suppress the startup banner, for machine-readable output |
 | `EXPLORBOT_MAX_DURATION` | Wall-clock budget in minutes for an explore run; same as --max-duration |
 <!-- END env -->

package/docs/workflow/agentic-usage.md

@@ -58,6 +58,7 @@ No `init`, no config file, no project directory, no model IDs to look up. These
 | `EXPLORBOT_KNOWLEDGE_FILE` | no | Path to a knowledge markdown file |
 | `EXPLORBOT_SPEC` | no | Docbot application spec directory or index.md, used as page knowledge |
 | `EXPLORBOT_API_SPEC` | no | OpenAPI spec path for the API boat |
+| `EXPLORBOT_API_HEADERS` | no | Headers sent with every API request, one "Name: value" per line |
 | `EXPLORBOT_NO_BANNER` | no | Suppress the startup banner, for machine-readable output |
 | `EXPLORBOT_MAX_DURATION` | no | Wall-clock budget in minutes for an explore run; same as --max-duration |
 <!-- END env -->
@@ -231,11 +232,12 @@ The same variables drive API testing and doc collection.
 ```bash
 EXPLORBOT_URL=https://api.example.com \
 EXPLORBOT_API_SPEC=./openapi.yaml \
+EXPLORBOT_API_HEADERS="Authorization: Bearer $TOKEN" \
 EXPLORBOT_AI_PROVIDER=openrouter \
   npx explorbot api explore /users
 ```
 
-The API boat also takes those two as flags, so one line carries the whole run: `npx explorbot api explore /users --endpoint https://api.example.com --spec ./openapi.yaml`.
+The API boat also takes those three as flags, so one line carries the whole run: `npx explorbot api explore https://api.example.com --spec ./openapi.yaml -H "Authorization: Bearer $TOKEN"`. Given a full URL, `api explore` reads it as the base endpoint; a path like `/users` needs the base in `--endpoint` or `EXPLORBOT_URL`.
 
 ```bash
 EXPLORBOT_AI_PROVIDER=openrouter \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/src/action-result.ts

@@ -33,6 +33,7 @@ interface ActionResultData extends WebPageState {
   iframeSnapshots?: Array<{ src: string; html: string; id?: string }>;
   ariaSnapshot?: string | null;
   ariaSnapshotFile?: string;
+  regionAria?: string | null;
   focusedElement?: FocusedElement | null;
   iframeURL?: string;
   links?: Link[];
@@ -90,6 +91,7 @@ export class ActionResult implements ActionResultData {
   public links: Link[] = [];
   public verifications?: Record<string, boolean>;
   public overlay: Region = new Region();
+  public regionAria: string | null = null;
   private _diffCache: { previousId: number | undefined; diff: Diff } | null = null;
 
   constructor(data: ActionResultData) {
@@ -106,6 +108,7 @@ export class ActionResult implements ActionResultData {
     this.iframeURL = data.iframeURL;
     this.notes = data.notes ?? [];
     this.verifications = data.verifications;
+    this.regionAria = data.regionAria ?? null;
 
     // Set readonly properties
     if (data.screenshotFile !== undefined) {
@@ -304,6 +307,10 @@ export class ActionResult implements ActionResultData {
     return compactAriaSnapshot(this.ariaSnapshot, false);
   }
 
+  getRegionARIA(): string {
+    return compactAriaSnapshot(this.regionAria, false);
+  }
+
   getCompactARIA(): string {
     return compactAriaSnapshot(this.ariaSnapshot, true);
   }

package/src/action.ts

@@ -14,8 +14,8 @@ import { browserErrorMessage, isFatalBrowserError, isNavigationTransitionError }
 import { captureHtmlForSnapshot, htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
 import { Overlay, OverlayPage } from './utils/overlay.js';
-import type { Region } from './utils/region.js';
 import { sleep, waitForPageReadiness } from './utils/page-readiness.ts';
+import type { Region } from './utils/region.js';
 import { safeFilename } from './utils/strings.ts';
 import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from './utils/web-sandbox.ts';
 
@@ -182,7 +182,19 @@ class Action {
         focusedElement,
         iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
       });
-      if (!frame) await this.detectRegion(result).catch((err: Error) => debugLog('Region detection failed:', err.message));
+      if (!frame) {
+        await this.detectRegion(result).catch((err: Error) => debugLog('Region detection failed:', err.message));
+        const regionRoot = result.overlay.root;
+        if (result.overlay.isModal && regionRoot) {
+          result.regionAria = await this.playwrightHelper.page
+            .locator(regionRoot)
+            .ariaSnapshot()
+            .catch((err: Error) => {
+              debugLog('Region ARIA snapshot failed:', err.message);
+              return null;
+            });
+        }
+      }
       this.stateManager.updateState(result, codeBlock);
       return result;
     } catch (err) {

package/src/ai/researcher/deep-analysis.ts

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 import { ActionResult, type Diff } from '../../action-result.js';
-import type { ExplorbotConfig } from '../../config.ts';
+import { type ExplorbotConfig, agentSettings } from '../../config.ts';
 import { executionController } from '../../execution-controller.ts';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
@@ -31,7 +31,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       tag('info').log('Starting deep analysis of expandable elements');
       await (this as any).navigateTo(state.fullUrl || state.url);
 
-      const maxClicks = (this.config.ai?.agents?.researcher as any)?.maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
+      const maxClicks = agentSettings(this.config, 'researcher').maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
 
       const expandedSections: string[] = [];
       const navigationLinks: Array<{ code: string; url: string }> = [];
@@ -88,6 +88,8 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     }
 
     async researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null> {
+      if (!(this as any).isEnabled()) return null;
+
       const region = current.overlay;
       if (!region.isOpen || !region.name) return null;
 

package/src/ai/researcher/sections.ts

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../../action-result.js';
-import type { ExplorbotConfig } from '../../config.ts';
+import { type ExplorbotConfig, agentSettings } from '../../config.ts';
 import { executionController } from '../../execution-controller.ts';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
@@ -66,7 +66,7 @@ export function WithSections<T extends Constructor>(Base: T) {
     }
 
     private async _detectFocusCss(): Promise<string | null> {
-      const focusSections = (this.config.ai?.agents?.researcher as any)?.focusSections as string[] | undefined;
+      const focusSections = agentSettings(this.config, 'researcher').focusSections;
       if (!focusSections?.length) return null;
 
       for (const css of focusSections) {

package/src/ai/researcher.ts

@@ -1,7 +1,7 @@
 import dedent from 'dedent';
 import { ActionResult } from '../action-result.js';
 import { setActivity } from '../activity.ts';
-import { ConfigParser, type ExplorbotConfig, outputPath } from '../config.ts';
+import { ConfigParser, type ExplorbotConfig, type ResearcherAgentConfig, agentSettings, outputPath } from '../config.ts';
 import { executionController } from '../execution-controller.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
@@ -19,7 +19,7 @@ import { annotatePageElements } from '../utils/web-annotate.ts';
 import type { Agent, AgentDeps } from './agent.js';
 import type { Navigator } from './navigator.ts';
 import { ContextLengthError, type Provider } from './provider.js';
-import { findSimilarResearch, getCachedResearch, reportResearch, saveResearch } from './researcher/cache.ts';
+import { findSimilarResearch, getCachedResearch, getPreviousResearch, reportResearch, saveResearch } from './researcher/cache.ts';
 import { type CoordinateMethods, WithCoordinates } from './researcher/coordinates.ts';
 import { type DeepAnalysisMethods, WithDeepAnalysis } from './researcher/deep-analysis.ts';
 import { detectFocusedSection, hasFocusedSection, markSectionAsFocused, pickDefaultFocusedSection } from './researcher/focus.ts';
@@ -62,13 +62,23 @@ export class Researcher extends ResearcherBase implements Agent {
   constructor(deps: AgentDeps) {
     super(deps);
     this.experienceTracker = deps.stateManager.getExperienceTracker();
+    this.settings.reasoning ??= 'low';
+  }
 
-    const ai = deps.config.ai;
-    if (ai) {
-      ai.agents ??= {};
-      ai.agents.researcher ??= {};
-      ai.agents.researcher.reasoning ??= 'low';
-    }
+  get settings(): ResearcherAgentConfig {
+    return agentSettings(this.config, 'researcher');
+  }
+
+  isEnabled(): boolean {
+    return this.settings.enabled !== false;
+  }
+
+  enable(): void {
+    this.settings.enabled = true;
+  }
+
+  disable(): void {
+    this.settings.enabled = false;
   }
 
   protected getNavigator(): Navigator {
@@ -94,7 +104,7 @@ export class Researcher extends ResearcherBase implements Agent {
 
   async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; _retriesLeft?: number } = {}): Promise<string> {
     const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
-    const maxRetries = (this.config.ai?.agents?.researcher as any)?.retries ?? 2;
+    const maxRetries = this.settings.retries ?? 2;
     let retriesLeft = opts._retriesLeft ?? maxRetries;
     this.actionResult = ActionResult.fromState(state);
     const stateHash = this.actionResult.baseHash;
@@ -109,6 +119,13 @@ export class Researcher extends ResearcherBase implements Agent {
       }
     }
 
+    if (!this.isEnabled()) {
+      debugLog('Researcher is disabled, answering with the recorded map');
+      const recorded = getPreviousResearch(stateHash);
+      if (recorded) reportResearch(stateHash, recorded);
+      return recorded;
+    }
+
     Stats.researches++;
 
     const sessionName = `researcher: ${state.url}`;
@@ -341,7 +358,7 @@ export class Researcher extends ResearcherBase implements Agent {
   }
 
   private async waitUntilSettled(screenshot: boolean): Promise<boolean> {
-    const errorPageTimeout = (this.config.ai?.agents?.researcher as any)?.errorPageTimeout ?? 10;
+    const errorPageTimeout = this.settings.errorPageTimeout ?? 10;
     if (errorPageTimeout <= 0) return false;
 
     const includeScreenshot = screenshot && this.provider.hasVision();
@@ -374,7 +391,7 @@ export class Researcher extends ResearcherBase implements Agent {
   }
 
   private getConfiguredSections(): Record<string, string> {
-    const configSections = (this.config.ai?.agents?.researcher as any)?.sections as string[] | undefined;
+    const configSections = this.settings.sections;
     if (!configSections?.length) return POSSIBLE_SECTIONS;
     const filtered: Record<string, string> = {};
     for (const key of configSections) {

package/src/ai/tester.ts

@@ -53,6 +53,7 @@ export class Tester extends TaskAgent implements Agent {
   MAX_ITERATIONS = 30;
   MAX_EXTENSIONS = 2;
   ASSERTION_TOOLS = ['verify'];
+  private pendingReview = '';
   researcher: Researcher;
   navigator: Navigator;
   agentTools: any;
@@ -119,6 +120,7 @@ export class Tester extends TaskAgent implements Agent {
     this.seenUiMapUrls.clear();
     this.lastAnalyzedStateHash = null;
     this.stalledIterations = 0;
+    this.pendingReview = '';
     this.previousRegionPresent = null;
     this.regionTransitioned = false;
     this.stateManager.clearHistory();
@@ -333,7 +335,7 @@ export class Tester extends TaskAgent implements Agent {
           const result = await this.provider.invokeConversation(conversation, tools, {
             maxToolRoundtrips: 3,
             toolChoice: 'required',
-            stopWhen: () => task.hasFinished,
+            stopWhen: () => task.hasFinished || !!this.pendingReview,
           });
 
           if (!result) throw new Error('Failed to get response from provider');
@@ -388,6 +390,14 @@ export class Tester extends TaskAgent implements Agent {
             }
           }
 
+          if (this.pendingReview && this.pilot) {
+            const reviewed = this.pendingReview;
+            this.pendingReview = '';
+            const reviewState = this.getCurrentState();
+            if (reviewed === 'finish') await this.pilot.reviewFinish(task, reviewState, conversation, this.navigator);
+            if (reviewed === 'stop') await this.pilot.reviewStop(task, reviewState, conversation);
+          }
+
           if (task.hasFinished) {
             stop();
             return;
@@ -579,16 +589,19 @@ export class Tester extends TaskAgent implements Agent {
 
     if (region.isModal) {
       const areaName = region.name ? ` "${region.name}"` : '';
-      let rootHint = '';
-      if (region.root) rootHint = `\nIts content lives inside \`${region.root}\` — scope locators to it.`;
+      let scoping = 'Use <page_aria> to confirm the element you target is actually inside the overlay.';
+      if (region.root) {
+        scoping = `Its root is \`${region.root}\` — build every locator as ARIA scoped to that root, e.g. I.click({ role: 'button', text: 'Continue' }, '${region.root}')`;
+      }
       context += dedent`
         <overlay>
-        An overlay${areaName} is currently open above the page.${rootHint}
-        Scope all interactions to elements inside this overlay.
-        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the overlay.
-        Use <page_aria> to confirm the element you target is actually inside the overlay.
-        </overlay>
+        You are inside an overlay${areaName} opened above the page.
+        ${scoping}
+        Elements outside the overlay are behind it and not actionable while it is open — they may share names or roles with the ones inside, so never target them by bare text.
       `;
+      const regionAria = currentState.getRegionARIA();
+      if (regionAria) context += `\nIt holds exactly these elements:\n<overlay_aria>\n${regionAria}\n</overlay_aria>`;
+      context += '\n</overlay>\n';
     }
 
     if (!region.isModal && region.isOpen && isNewState) {
@@ -1006,18 +1019,9 @@ export class Tester extends TaskAgent implements Agent {
         }),
         execute: async ({ reason }) => {
           task.addNote(`Stop requested: ${reason}`);
+          this.pendingReview = 'stop';
 
-          if (this.pilot) {
-            const currentState = this.getCurrentState();
-            await this.pilot.reviewStop(task, currentState, conversation);
-            if (!task.hasFinished) {
-              return {
-                success: false,
-                action: 'stop',
-                message: 'Stop rejected; Continue execution',
-              };
-            }
-          } else {
+          if (!this.pilot) {
             task.addNote(reason, TestResult.FAILED);
             task.finish(TestResult.FAILED);
           }
@@ -1053,18 +1057,9 @@ export class Tester extends TaskAgent implements Agent {
             return { success: true, action: 'finish', message: 'already finished' };
           }
           task.addNote(`Finish requested: ${verify}`);
+          this.pendingReview = 'finish';
 
-          if (this.pilot) {
-            const currentState = this.getCurrentState();
-            await this.pilot.reviewFinish(task, currentState, conversation, this.navigator);
-            if (!task.hasFinished) {
-              return {
-                success: false,
-                action: 'finish',
-                message: 'Finishing rejected; Continue execution',
-              };
-            }
-          } else {
+          if (!this.pilot) {
             task.addNote('Test finished successfully', TestResult.PASSED);
             task.finish(TestResult.PASSED);
           }

package/src/ai/tools.ts

@@ -737,6 +737,12 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
 
           const researchResult = await researcher.research(currentState, { screenshot: true, data: true });
 
+          if (!researchResult) {
+            return failedToolResult('research', 'No UI map is available for this page.', {
+              suggestion: 'Use context() to read the page structure and act on the elements it lists.',
+            });
+          }
+
           return successToolResult('research', {
             analysis: researchResult,
             aria: cap(ActionResult.fromState(currentState).getInteractiveARIA(), ARIA_OUTPUT_CAP),

package/src/commands/config-command.ts

@@ -45,7 +45,10 @@ export class ConfigCommand extends BaseCommand {
     const env: Record<string, string> = {};
     for (const variable of EXPLORBOT_ENV_VARS) {
       const value = process.env[variable.name];
-      if (value) env[variable.name] = value;
+      if (!value) continue;
+      let shown = value;
+      if (variable.secret) shown = 'set';
+      env[variable.name] = shown;
     }
 
     const models: Record<string, string> = {};

package/src/config.ts

@@ -22,6 +22,7 @@ export const PROVIDERS: Record<string, ProviderInfo> = {
 export const MODEL_ROLES: ModelRole[] = ['model', 'visionModel', 'agenticModel'];
 
 let cachedOutputRoot: string | null = null;
+let runOutputDir: string | null = null;
 
 interface PlaywrightConfig {
   browser: 'chromium' | 'firefox' | 'webkit';
@@ -275,6 +276,7 @@ export const EXPLORBOT_ENV_VARS: EnvVar[] = [
   { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
   { name: 'EXPLORBOT_SPEC', description: 'Docbot application spec directory or index.md, used as page knowledge' },
   { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
+  { name: 'EXPLORBOT_API_HEADERS', description: 'Headers sent with every API request, one "Name: value" per line', secret: true },
   { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
   { name: 'EXPLORBOT_MAX_DURATION', description: 'Wall-clock budget in minutes for an explore run; same as --max-duration' },
 ];
@@ -496,6 +498,7 @@ export class ConfigParser {
   // For testing purposes only
   public static resetForTesting(): void {
     cachedOutputRoot = null;
+    runOutputDir = null;
     if (ConfigParser.instance) {
       ConfigParser.instance.config = null;
       ConfigParser.instance.configPath = null;
@@ -744,10 +747,22 @@ export class ConfigParser {
   }
 }
 
+export function setOutputDir(dir: string): void {
+  runOutputDir = dir;
+}
+
 export function outputPath(...segments: string[]): string {
+  if (runOutputDir) return path.join(runOutputDir, ...segments);
   return path.join(ConfigParser.getInstance().getOutputDir(), ...segments);
 }
 
+export function agentSettings<K extends keyof AgentsConfig>(config: ExplorbotConfig, agent: K): NonNullable<AgentsConfig[K]> {
+  const ai = (config.ai ??= { model: null });
+  const agents = (ai.agents ??= {}) as Record<K, NonNullable<AgentsConfig[K]>>;
+  agents[agent] ??= {} as NonNullable<AgentsConfig[K]>;
+  return agents[agent];
+}
+
 export async function resolveModel(spec: string, role: ModelRole = 'model'): Promise<any> {
   const separator = spec.indexOf('/');
   if (separator > 0) {
@@ -912,6 +927,7 @@ interface EnvVar {
   name: string;
   description: string;
   required?: boolean;
+  secret?: boolean;
 }
 
 export type { ModelRole, EnvVar, ProviderInfo, ConfiguredModel };

package/src/state-manager.ts

@@ -143,13 +143,18 @@ export class StateManager {
   updateState(actionResult: ActionResult, codeBlock?: string, trigger: 'manual' | 'navigation' | 'automatic' = 'manual'): WebPageState {
     const previousState = this.currentState;
     const previousHash = previousState?.hash;
+    const hashChanged = actionResult.hash !== previousHash;
+
+    if (!hashChanged && previousState?.verifications) {
+      const stillTrue = Object.entries(previousState.verifications).filter(([, passed]) => passed);
+      actionResult.verifications = { ...Object.fromEntries(stillTrue), ...actionResult.verifications };
+    }
 
     const newState = actionResult;
     this.currentState = newState;
     this.currentState.id = this.nextStateId++;
     if (newState.url) this.allVisitedUrls.add(normalizeUrl(newState.url));
 
-    const hashChanged = actionResult.hash !== previousHash;
     const regionOpened = !hashChanged && this.regionOpened(previousState, newState);
 
     if (hashChanged || regionOpened) {