explorbot 0.4.1 → 0.4.2

package/dist/src/ai/tools.js

@@ -16,7 +16,7 @@ import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 const debugLog = createDebug('explorbot:tools');
 export const ASSERTION_TOOLS = ['verify'];
-export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
+export function createCodeceptJSTools({ explorer, stateManager }, task) {
     return {
         click: tool({
             description: dedent `
@@ -29,6 +29,12 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
           Container narrows search area. Use when page has multiple matching elements.
           Example: Page has 3 "Delete" buttons in different rows:
           I.click("Delete", ".row-1") - clicks Delete inside element with class row-1
+        I.click(locator, step.opts({ elementIndex: N })) - click the Nth element the locator matches
+          Use after a result reported several matches. N is the "Element N" number from that list.
+          step.opts() always goes LAST, after the container when there is one.
+          Example: the result listed 3 "Delete" buttons and you want the second:
+          I.click("Delete", step.opts({ elementIndex: 2 }))
+          I.click("Delete", ".table", step.opts({ elementIndex: 2 })) - same, narrowed to a container
 
         IMPORTANT: This tool ONLY accepts click commands. For typing text, use form() tool.
         CRITICAL: All commands MUST target the SAME element using different locators.
@@ -47,6 +53,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
           5. I.clickXY(x, y) - coordinates fallback
+          After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
         `),
                 explanation: z.string().describe('Why you are clicking this element'),
             }),
@@ -72,6 +79,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
                 const action = explorer.action();
                 const attempts = [];
+                let ambiguityError = null;
                 for (let i = 0; i < commands.length; i++) {
                     const command = transformContainsCommand(commands[i]);
                     const success = await action.attempt(command, explanation);
@@ -79,34 +87,14 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     if (action.lastError)
                         attempt.error = errorText(action.lastError);
                     attempts.push(attempt);
+                    if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound')
+                        ambiguityError = action.lastError;
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
                         await commitNote(activeNote, TestResult.PASSED, toolResult, action);
                         return successToolResult('click', { ...toolResult, attempts, code: command }, action);
                     }
                 }
-                let disambiguated = null;
-                if (attempts.some((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
-                    disambiguated = await disambiguateElements(action.lastError, explanation, ai);
-                }
-                if (disambiguated) {
-                    debugLog('Disambiguation picked element %d', disambiguated.position);
-                    const failedCommand = attempts.find((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))?.command;
-                    const retryCommands = [];
-                    if (failedCommand) {
-                        retryCommands.push(failedCommand.replace(/\)$/, `, step.opts({ elementIndex: ${disambiguated.position} }))`));
-                    }
-                    retryCommands.push(`I.click('${disambiguated.xpath.replace(/'/g, "\\'")}')`);
-                    for (const retryCmd of retryCommands) {
-                        if (!(await action.attempt(retryCmd, explanation))) {
-                            attempts.push({ command: retryCmd, success: false, error: errorText(action.lastError) });
-                            continue;
-                        }
-                        const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, retryCmd);
-                        await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-                        return successToolResult('click', { ...toolResult, attempts, code: retryCmd, disambiguated: true }, action);
-                    }
-                }
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
                 await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                 const suggestion = clickFailureSuggestion(attempts);
@@ -114,7 +102,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     ...toolResult,
                     attempts,
                     suggestion,
-                }, action.lastError);
+                }, ambiguityError || action.lastError);
             },
         }),
         hover: tool({
@@ -344,13 +332,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     if (action.lastError) {
                         const message = errorText(action.lastError);
                         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
-                        let formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
-                        if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
-                            const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
-                            if (disambiguated) {
-                                formSuggestion = `Multiple elements matched. Add step.opts({ elementIndex: ${disambiguated.position} }) to the failing command. Fallback locator: ${disambiguated.xpath}`;
-                            }
-                        }
+                        const formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
                         return failedToolResult('form', `Form execution FAILED! ${message}\n${formatExecutedSteps(action.executedSteps, codeLines.length)}`, {
                             ...toolResult,
                             code: codeBlock,
@@ -1123,13 +1105,11 @@ export async function failedToolResult(action, message, data, error) {
 }
 function getMultipleElementsSuggestion() {
     return dedent `
-    Multiple elements matched your locator. To fix this:
-    1. Use container context: I.click({ "role": "button", "text": "Submit" }, '.form-container')
-    2. Use more specific CSS: target the actual element (input, button, a) not wrapper divs
-    3. Add distinguishing attributes: input[type="submit"], button[type="submit"], [value="..."]
-    4. If buttons have similar text like "Create" and "Create Demo", use the FULL unique text
-    5. Use xpathCheck() to inspect matched elements and pick the correct one
-    6. Use visualClick() to click the right element by visual appearance
+    Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
+    Read the numbered elements list and click the one you meant by its number:
+    reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    If none of them is the element you want, narrow the locator with a container or its full unique text.
+    If the list is missing, call xpathCheck() to see what the locator matches.
   `;
 }
 export function withdrawVisionTools(tools) {
@@ -1194,42 +1174,6 @@ export async function formatMatchedElements(error) {
         return 'Could not fetch element details. Repeat the action to get better info.';
     return formatElementList(details);
 }
-async function disambiguateElements(error, explanation, provider) {
-    const elementDetails = await extractWebElements(error);
-    if (!elementDetails)
-        return null;
-    const elementList = formatElementList(elementDetails);
-    const schema = z.object({
-        position: z.number().nullable().describe('1-based position of the correct element, or null if none match'),
-    });
-    try {
-        const result = await provider.generateObject([
-            {
-                role: 'user',
-                content: dedent `
-            A click action failed because multiple elements matched the locator.
-            The intended action was: ${explanation}
-
-            Here are the matched elements:
-
-            ${elementList}
-
-            Which element (1-${elementDetails.length}) best matches the intended action?
-            Return the position number, or null if none of them match.
-          `,
-            },
-        ], schema, provider.getModelForAgent(), { agentName: 'disambiguator', timeout: 15000 });
-        const position = result?.object?.position;
-        if (position && position >= 1 && position <= elementDetails.length) {
-            return { position, xpath: elementDetails[position - 1].xpath };
-        }
-        return null;
-    }
-    catch (e) {
-        debugLog('Element disambiguation AI call failed: %s', e);
-        return null;
-    }
-}
 function getNotFoundSuggestion(errorMessage) {
     if (!errorMessage.includes('not found')) {
         return null;

package/dist/src/api/request-store.d.ts

@@ -12,14 +12,9 @@ export declare class RequestStore {
     getFailedRequests(): RequestResult[];
     onFailedRequest(cb: (r: RequestResult) => void): () => void;
     addMadeRequest(result: RequestResult): void;
-    addRequest(result: RequestResult): void;
     getCapturedRequests(): RequestResult[];
     getMadeRequests(): RequestResult[];
-    getRequests(): RequestResult[];
     getLastRequest(): RequestResult | undefined;
-    getRequestsByEndpoint(pathPrefix: string): RequestResult[];
-    getRequestsByMethod(method: string): RequestResult[];
-    getRequestsByStatus(status: number): RequestResult[];
     toEndpointList(scopePath?: string): string;
     extractAuthHeaders(): Record<string, string>;
     findCapturedRequest(method: string, searchPath: string): RequestResult | undefined;
@@ -28,3 +23,4 @@ export declare class RequestStore {
     getWriteRequestsForScope(scopePath: string): RequestResult[];
     clear(): void;
 }
+export declare function isFailedRequest(request: RequestResult): boolean;

package/dist/src/api/request-store.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { isDynamicSegment } from "../utils/url-matcher.js";
+import { generalizeUrl, isDynamicSegment } from "../utils/url-matcher.js";
 import { RequestResult } from "./request-result.js";
 const AUTH_HEADERS = ['authorization', 'x-api-key', 'x-csrf-token'];
 export class RequestStore {
@@ -38,31 +38,15 @@ export class RequestStore {
         this.madeRequests.push(result);
         result.save(this.outputDir);
     }
-    addRequest(result) {
-        this.addMadeRequest(result);
-    }
     getCapturedRequests() {
         return this.capturedRequests;
     }
     getMadeRequests() {
         return this.madeRequests;
     }
-    getRequests() {
-        return this.madeRequests;
-    }
     getLastRequest() {
         return this.madeRequests[this.madeRequests.length - 1];
     }
-    getRequestsByEndpoint(pathPrefix) {
-        return this.madeRequests.filter((r) => r.path.startsWith(pathPrefix));
-    }
-    getRequestsByMethod(method) {
-        const upper = method.toUpperCase();
-        return this.madeRequests.filter((r) => r.method === upper);
-    }
-    getRequestsByStatus(status) {
-        return this.madeRequests.filter((r) => r.status === status);
-    }
     toEndpointList(scopePath) {
         let requests = this.capturedRequests;
         if (scopePath)
@@ -70,7 +54,7 @@ export class RequestStore {
         const seen = new Set();
         const lines = [];
         for (const req of requests) {
-            const key = `${req.method} ${normalizePathPattern(req.path)}`;
+            const key = `${req.method} ${generalizeUrl(req.path, () => '{id}')}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
@@ -92,13 +76,17 @@ export class RequestStore {
     }
     findCapturedRequest(method, searchPath) {
         const upper = method.toUpperCase();
-        const search = normalizePathPattern(searchPath).split('/').filter(Boolean);
+        const search = generalizeUrl(searchPath, () => '{id}')
+            .split('/')
+            .filter(Boolean);
         let best;
         let bestScore = -1;
         for (const req of this.capturedRequests) {
             if (req.method !== upper)
                 continue;
-            const segments = normalizePathPattern(req.path).split('/').filter(Boolean);
+            const segments = generalizeUrl(req.path, () => '{id}')
+                .split('/')
+                .filter(Boolean);
             if (segments.length < search.length)
                 continue;
             if (!search.every((segment, i) => segment === segments[i]))
@@ -139,8 +127,7 @@ export class RequestStore {
         }
     }
     getWriteRequestsForScope(scopePath) {
-        const writeMethods = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
-        const writes = this.capturedRequests.filter((r) => writeMethods.has(r.method));
+        const writes = this.capturedRequests.filter((r) => r.isWrite);
         const scopeSegments = scopePath.split('/').filter(Boolean);
         if (scopeSegments.length === 0)
             return writes;
@@ -172,6 +159,9 @@ export class RequestStore {
         this.failedRequests = [];
     }
 }
+export function isFailedRequest(request) {
+    return request.status >= 400 || Boolean(request.error);
+}
 function normalizePathPattern(urlPath) {
     return urlPath
         .split('/')

package/dist/src/commands/config-command.js

@@ -5,6 +5,7 @@ import { ConfigParser, EXPLORBOT_ENV_VARS, configuredModels } from '../config.js
 import { listSites } from '../global-config.js';
 import { Reporter } from '../reporter.js';
 import { getCliName } from '../utils/cli-name.js';
+import { renderSection } from '../utils/cli-section.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
 export class ConfigCommand extends BaseCommand {
@@ -68,15 +69,7 @@ export class ConfigCommand extends BaseCommand {
         if (options.json)
             return JSON.stringify(data, null, 2);
         const lines = [];
-        const section = (title, entries) => {
-            if (!entries.length)
-                return;
-            const width = Math.max(...entries.map(([label]) => label.length));
-            lines.push(chalk.bold(title));
-            for (const [label, value] of entries)
-                lines.push(`  ${chalk.dim(label.padEnd(width))}  ${value}`);
-            lines.push('');
-        };
+        const section = (title, entries) => lines.push(...renderSection(title, entries));
         const general = [['config', data.config || 'EXPLORBOT_* environment variables']];
         if (data.url)
             general.push(['url', data.url]);

package/dist/src/commands/index.js

@@ -26,6 +26,7 @@ import { PlanLoadCommand } from './plan-load-command.js';
 import { PlanReloadCommand } from './plan-reload-command.js';
 import { PlanSaveCommand } from './plan-save-command.js';
 import { PlansCommand } from './plans-command.js';
+import { RecommendedModelsCommand } from './recommended-models-command.js';
 import { RerunCommand } from './rerun-command.js';
 import { ResearchCommand } from './research-command.js';
 import { RunsCommand } from './runs-command.js';
@@ -66,6 +67,7 @@ const commandClasses = [
     RerunCommand,
     StatusCommand,
     ConfigCommand,
+    RecommendedModelsCommand,
     DebugCommand,
     ExitCommand,
 ];

package/dist/src/commands/init-command.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
-import { ConfigParser, PROVIDERS } from "../config.js";
+import { ConfigParser, PROVIDERS, missingModelRoles } from "../config.js";
 import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from "../global-config.js";
 import { getCliName } from "../utils/cli-name.js";
 import { log, tag } from '../utils/logger.js';
@@ -82,7 +82,7 @@ export function writeGlobalConfig(provider, apiKey) {
     const envKey = PROVIDERS[provider].envKey;
     writeEnvKey(envKey, apiKey || '');
     log(`Stored ${envKey} in ${globalEnvPath()}`);
-    const missing = missingRoles(provider);
+    const missing = missingModelRoles(provider);
     if (missing.length) {
         tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${globalConfigPath()}`);
     }
@@ -139,7 +139,7 @@ export function runInitCommand(options) {
         else {
             log(`Env file already exists: ${relativeToCwd(envPath)}`);
         }
-        const missing = missingRoles(provider);
+        const missing = missingModelRoles(provider);
         if (missing.length) {
             tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${relativeToCwd(outPath)}`);
         }
@@ -269,10 +269,6 @@ function isModuleProject(configDir) {
         currentDir = parentDir;
     }
 }
-function missingRoles(provider) {
-    const recommended = ConfigParser.recommendedModels()[provider] || {};
-    return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);
-}
 function writeEnvKey(key, value) {
     const envPath = globalEnvPath();
     let content = '# AI provider API keys';

package/dist/src/commands/plans-command.d.ts

@@ -11,7 +11,10 @@ export declare class PlansCommand extends BaseCommand {
     getPlanFiles(): PlanFile[];
     printPlans(files: PlanFile[]): void;
     printPlanDetails(plan: Plan, file: PlanFile): void;
-    resolvePlanFile(target: string, files: PlanFile[]): PlanFile;
+    resolvePlanFile(target: string, files: PlanFile[]): {
+        plan: Plan;
+        file: PlanFile;
+    };
 }
 interface PlanFile {
     name: string;

package/dist/src/commands/plans-command.js

@@ -17,8 +17,7 @@ export class PlansCommand extends BaseCommand {
             this.printPlans(files);
             return;
         }
-        const file = this.resolvePlanFile(target, files);
-        const plan = Plan.fromMarkdown(file.path);
+        const { plan, file } = this.resolvePlanFile(target, files);
         this.printPlanDetails(plan, file);
     }
     getPlanFiles() {
@@ -68,16 +67,17 @@ export class PlansCommand extends BaseCommand {
             const file = files[index - 1];
             if (!file)
                 throw new Error(`Plan #${target} not found. Available: 1-${files.length}`);
-            return file;
+            return { plan: Plan.fromMarkdown(file.path), file };
         }
         const plan = Plan.loadFromFile(target, this.explorBot.getPlansDir());
         if (!plan?.filePath) {
             throw new Error(`Plan file not found: ${target}`);
         }
-        return {
+        const file = {
             name: path.basename(plan.filePath),
             path: plan.filePath,
             modifiedAt: statSync(plan.filePath).mtimeMs,
         };
+        return { plan, file };
     }
 }

package/dist/src/commands/recommended-models-command.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import { BaseCommand } from './base-command.js';
+export declare class RecommendedModelsCommand extends BaseCommand {
+    name: string;
+    description: string;
+    execute(): Promise<void>;
+    static register(program: Command): void;
+    static render(json?: boolean): string;
+}

package/dist/src/commands/recommended-models-command.js

@@ -0,0 +1,85 @@
+import chalk from 'chalk';
+import { ConfigParser, EXPLORBOT_ENV_VARS, MODEL_ROLES, PROVIDERS } from '../config.js';
+import { getCliName } from '../utils/cli-name.js';
+import { renderSection } from '../utils/cli-section.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+const DESCRIPTION = 'Show the models recommended for every AI provider';
+const ROLES = {
+    model: { hint: 'fast', env: 'EXPLORBOT_AI_MODEL' },
+    visionModel: { hint: 'screenshots', env: 'EXPLORBOT_VISION_MODEL' },
+    agenticModel: { hint: 'smart', env: 'EXPLORBOT_AGENTIC_MODEL' },
+};
+const MODEL_ENV_VARS = MODEL_ROLES.map((role) => ROLES[role].env);
+export class RecommendedModelsCommand extends BaseCommand {
+    name = 'recommended-models';
+    description = DESCRIPTION;
+    async execute() {
+        tag('info').log(RecommendedModelsCommand.render());
+    }
+    static register(program) {
+        program
+            .command('recommended-models')
+            .description(DESCRIPTION)
+            .option('--json', 'Print the recommendations as JSON')
+            .action((options) => console.log(RecommendedModelsCommand.render(options.json)));
+    }
+    static render(json = false) {
+        const recommended = ConfigParser.recommendedModels();
+        if (json)
+            return JSON.stringify(recommended, null, 2);
+        const lines = [
+            chalk.bold('Export the provider key, then pick one of two ways to select models:'),
+            `  ${chalk.bold('EXPLORBOT_AI_PROVIDER')} — every role takes that provider's recommendation below`,
+            `  ${chalk.bold(MODEL_ENV_VARS.join(' + '))} — no provider variable, pin every role yourself as ${chalk.dim('provider/model-id')}`,
+            '',
+        ];
+        for (const [provider, roles] of Object.entries(recommended)) {
+            lines.push(chalk.bold.yellow(`${provider}:`));
+            const models = [];
+            for (const role of MODEL_ROLES) {
+                const label = `${role} (${ROLES[role].hint})`;
+                if (roles[role])
+                    models.push([label, roles[role]]);
+                if (!roles[role])
+                    models.push([label, chalk.dim('not served, pair with another provider')]);
+            }
+            lines.push(...renderSection('models', models, 2));
+            const envKey = PROVIDERS[provider]?.envKey;
+            if (!envKey) {
+                lines.push(`  ${chalk.dim('not bundled — import the provider in your config')}`, '');
+                continue;
+            }
+            const env = [
+                ['key', envKey],
+                ['provider', `EXPLORBOT_AI_PROVIDER=${provider}`],
+            ];
+            let label = 'or models';
+            for (const role of MODEL_ROLES) {
+                if (!roles[role])
+                    continue;
+                env.push([label, `${ROLES[role].env}=${provider}/${roles[role]}`]);
+                label = '';
+            }
+            lines.push(...renderSection('env variables', env, 2));
+        }
+        const modelVars = ['EXPLORBOT_AI_PROVIDER', ...MODEL_ENV_VARS];
+        const current = [];
+        for (const variable of EXPLORBOT_ENV_VARS) {
+            if (!modelVars.includes(variable.name))
+                continue;
+            if (process.env[variable.name])
+                current.push([variable.name, process.env[variable.name]]);
+        }
+        for (const [provider, { envKey }] of Object.entries(PROVIDERS)) {
+            if (process.env[envKey])
+                current.push([envKey, chalk.dim(`set, ${provider} usable`)]);
+        }
+        if (!current.length)
+            lines.push(chalk.dim('Nothing set — export one of the variables above, or write models into your config'), '');
+        if (current.length)
+            lines.push(...renderSection('Currently set', current));
+        lines.push(chalk.bold('Example using OpenRouter:'), `  OPENROUTER_API_KEY=sk-... EXPLORBOT_AI_PROVIDER=openrouter ${getCliName()} <command>`);
+        return lines.join('\n');
+    }
+}

package/dist/src/config.d.ts

@@ -1,5 +1,6 @@
 import { type SiteRecord } from './global-config.js';
 export declare const PROVIDERS: Record<string, ProviderInfo>;
+export declare const MODEL_ROLES: ModelRole[];
 interface PlaywrightConfig {
     browser: 'chromium' | 'firefox' | 'webkit';
     url: string;
@@ -270,6 +271,7 @@ export declare class ConfigParser {
 }
 export declare function outputPath(...segments: string[]): string;
 export declare function resolveModel(spec: string, role?: ModelRole): Promise<any>;
+export declare function missingModelRoles(provider: string): ModelRole[];
 export declare class ConfigMissingError extends Error {
 }
 export declare function envConfigRequested(): boolean;

package/dist/src/config.js

@@ -25,6 +25,7 @@ export const PROVIDERS = {
     openrouter: { envKey: 'OPENROUTER_API_KEY', load: async () => (await import('@openrouter/ai-sdk-provider')).createOpenRouter() },
     sambanova: { envKey: 'SAMBANOVA_API_KEY', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
 };
+export const MODEL_ROLES = ['model', 'visionModel', 'agenticModel'];
 let cachedOutputRoot = null;
 const config = {
     playwright: {
@@ -458,6 +459,10 @@ export async function resolveModel(spec, role = 'model') {
     }
     return createModel(spec, modelId);
 }
+export function missingModelRoles(provider) {
+    const recommended = ConfigParser.recommendedModels()[provider] || {};
+    return MODEL_ROLES.filter((role) => !recommended[role]);
+}
 export class ConfigMissingError extends Error {
 }
 export function envConfigRequested() {
@@ -478,6 +483,7 @@ export function missingConfigMessage(configFile = 'explorbot.config.js') {
         EXPLORBOT_AI_PROVIDER=openrouter EXPLORBOT_URL=https://your-app.example.com ${cli} ...
 
     Providers: ${Object.keys(PROVIDERS).join(', ')}
+    See the models each one recommends: ${cli} recommended-models
   `;
 }
 export function modelName(model) {
@@ -511,8 +517,7 @@ export function configuredModels(ai) {
 export async function resolveConfigModels(ai) {
     if (!ai)
         return;
-    const roles = ['model', 'visionModel', 'agenticModel'];
-    for (const role of roles) {
+    for (const role of MODEL_ROLES) {
         if (typeof ai[role] === 'string')
             ai[role] = await resolveModel(ai[role], role);
     }

package/dist/src/experience-tracker.js

@@ -105,7 +105,7 @@ export class ExperienceTracker {
                 url: state.url ? extractStatePath(state.url) : '',
                 title: state.title,
             };
-            if (state.overlay.present && state.overlay.name) {
+            if (state.overlay.isOpen && state.overlay.name) {
                 frontmatter.region = state.overlay.name;
                 if (state.overlay.root)
                     frontmatter.root = state.overlay.root;

package/dist/src/explorbot.js

@@ -399,10 +399,10 @@ export class ExplorBot {
         return plan;
     }
     loadPlans(filename) {
-        const plan = Plan.loadFromFile(filename, this.getPlansDir());
-        if (!plan?.filePath)
+        const filePath = Plan.resolveFile(filename, this.getPlansDir());
+        if (!filePath)
             throw new Error(`Plan file not found: ${filename}`);
-        return parsePlansFromMarkdown(plan.filePath);
+        return parsePlansFromMarkdown(filePath);
     }
     setCurrentPlan(plan) {
         this.currentPlan = plan;

package/dist/src/global-config.d.ts

@@ -6,6 +6,8 @@ export declare function isGlobalConfigPath(configPath: string): boolean;
 export declare function sitesDir(): string;
 export declare function siteFolderName(url: string): string;
 export declare function listSites(): SiteRecord[];
+export declare function findSiteWith(subpath: string): SiteRecord | undefined;
+export declare function listSitePlanDirs(): string[];
 export declare function registerSite(baseUrl: string): SiteRecord;
 export declare function resolveSiteTarget(target?: string, defaultBaseUrl?: string): SiteTarget;
 interface SiteRecord {

package/dist/src/global-config.js

@@ -38,6 +38,12 @@ export function listSites() {
         .filter((site) => !!site)
         .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
 }
+export function findSiteWith(subpath) {
+    return listSites().find((site) => existsSync(join(site.dir, subpath)));
+}
+export function listSitePlanDirs() {
+    return listSites().map((site) => join(site.dir, 'output', 'plans'));
+}
 export function registerSite(baseUrl) {
     const folder = siteFolderName(baseUrl);
     const dir = join(sitesDir(), folder);

package/dist/src/state-manager.d.ts

@@ -1,7 +1,7 @@
 import { ActionResult, type FocusedElement } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
-import { Overlay } from './utils/overlay.js';
+import type { Region } from './utils/region.js';
 export interface Link {
     title: string;
     url: string;
@@ -41,7 +41,7 @@ export interface WebPageState {
     focusedElement?: FocusedElement | null;
     links?: Link[];
     verifications?: Record<string, boolean>;
-    overlay?: Overlay;
+    overlay?: Region;
     /** Region name, the persisted scalar form of overlay.name used in experience frontmatter */
     region?: string;
     /** Region root selector, the persisted scalar form of overlay.root used in experience frontmatter */
@@ -95,7 +95,7 @@ export declare class StateManager {
      * Update state from basic data (for navigation events)
      */
     updateStateFromBasic(url: string, title?: string, trigger?: 'manual' | 'navigation' | 'automatic'): WebPageState;
-    hasRegionAppeared(previousState: WebPageState | null, newState: WebPageState): boolean;
+    regionOpened(previousState: WebPageState | null, newState: WebPageState): boolean;
     /**
      * Generate a basic hash for state comparison
      */