explorbot 0.2.4 → 0.3.0

package/dist/src/ai/tools.js

@@ -2,11 +2,13 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
+import { renderExperienceRecipes } from "../experience-tracker.js";
 import { Stats } from "../stats.js";
 import { TestResult } from '../test-plan.js';
 import { LARGE_ARIA_CHANGE_THRESHOLD } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { createDebug, tag } from '../utils/logger.js';
+import { compactErrorMessage } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
@@ -19,10 +21,6 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
             description: dedent `
         Click an element by trying multiple CodeceptJS commands in order until one succeeds.
 
-        Use this only for elements the page context gives you no ref for. When the element shows a ref such as [ref=e14],
-        call clickRef with that ref instead — composing a locator for an element that already has a ref is wasted work,
-        and a locator can match several elements where a ref cannot.
-
         Follow <locator_priority> from system prompt for locator selection.
 
         I.click(locator) - click element matching locator
@@ -78,7 +76,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     const success = await action.attempt(command, explanation);
                     const attempt = { command, success };
                     if (action.lastError)
-                        attempt.error = action.lastError.toString();
+                        attempt.error = errorText(action.lastError);
                     attempts.push(attempt);
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
@@ -100,7 +98,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     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: action.lastError?.toString() });
+                            attempts.push({ command: retryCmd, success: false, error: errorText(action.lastError) });
                             continue;
                         }
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, retryCmd);
@@ -118,38 +116,6 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 }, action.lastError);
             },
         }),
-        clickRef: tool({
-            description: dedent `
-        Click an element by the ref the page context gave it, e.g. [ref=e14].
-
-        Prefer this over click() whenever the element you want carries a ref. A ref names one exact element, so it
-        cannot match several by mistake and never needs disambiguating — it is the fastest way to click.
-        Only pass a ref that appears in the page context you were given. Never invent or guess one.
-        If it reports the ref is gone, the page has been rebuilt: get fresh context and use the new ref.
-      `,
-            inputSchema: z.object({
-                ref: z.string().describe('The ref exactly as it appears in the page context, e.g. "e14"'),
-                element: z.string().describe('Role and name of the element you are clicking, for the record'),
-            }),
-            execute: async ({ ref, element }) => {
-                const activeNote = task.startNote(`Click ${element}`);
-                const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                const action = explorer.action();
-                const named = await describeRef(explorer, ref);
-                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
-                if (!(await action.attempt(run, `Click ${element}`))) {
-                    activeNote.commit(TestResult.FAILED);
-                    return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
-                        suggestion: 'The ref may belong to an older version of the page. Get fresh context and use the ref it gives, or fall back to click() with a locator.',
-                    });
-                }
-                // a ref belongs to this session only, so the run is reported as the locator a later test can replay
-                const code = named ? `I.click(${JSON.stringify(named)})` : run;
-                const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, code);
-                await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-                return successToolResult('clickRef', { ...toolResult, code }, action);
-            },
-        }),
         hover: tool({
             description: dedent `
         Move the mouse cursor to an element to reveal hover-only controls.
@@ -197,7 +163,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     const success = await action.attempt(command, explanation);
                     const attempt = { command, success };
                     if (action.lastError)
-                        attempt.error = action.lastError.toString();
+                        attempt.error = errorText(action.lastError);
                     attempts.push(attempt);
                     if (!success)
                         continue;
@@ -264,7 +230,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                                 fallback: true,
                             }, action);
                         }
-                        const errorMsg = `pressKey fallback to type() failed: ${action.lastError?.toString()}`;
+                        const errorMsg = `pressKey fallback to type() failed: ${errorText(action.lastError)}`;
                         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                         return failedToolResult('pressKey', errorMsg, {
                             ...toolResult,
@@ -300,7 +266,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                             code: pressKeyCommand,
                         }, action);
                     }
-                    const errorMsg = `pressKey() failed: ${action.lastError?.toString()}`;
+                    const errorMsg = `pressKey() failed: ${errorText(action.lastError)}`;
                     await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                     return failedToolResult('pressKey', errorMsg, {
                         ...toolResult,
@@ -321,8 +287,6 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
         Execute raw CodeceptJS code block with multiple commands.
         USE THIS TOOL for typing text into fields: I.fillField, I.type
 
-        Do not put a click on a ref-bearing element in here — clickRef with its ref is cheaper and cannot mis-target.
-
         Follow <actions> from system prompt for available commands.
         Follow <locator_priority> from system prompt for locator selection.
 
@@ -377,7 +341,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     await action.attempt(codeBlock, explanation);
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, formLocator);
                     if (action.lastError) {
-                        const message = action.lastError ? String(action.lastError) : 'Unknown error';
+                        const message = errorText(action.lastError);
                         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                         let formSuggestion = 'Look into error message and identify which commands passed and which failed. Continue execution using step-by-step approach using click() and form() tools.';
                         if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
@@ -419,6 +383,42 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
         }),
     };
 }
+export function createRefTools({ explorer, stateManager }, task) {
+    return {
+        clickRef: tool({
+            description: dedent `
+        Click an element by the ref the page context gave it, e.g. [ref=e14].
+
+        Prefer this over click() whenever the element you want carries a ref. A ref names one exact element, so it
+        cannot match several by mistake and never needs disambiguating — it is the fastest way to click.
+        Only pass a ref that appears in the page context you were given. Never invent or guess one.
+        If it reports the ref is gone, the page has been rebuilt: get fresh context and use the new ref.
+      `,
+            inputSchema: z.object({
+                ref: z.string().describe('The ref exactly as it appears in the page context, e.g. "e14"'),
+                element: z.string().describe('Role and name of the element you are clicking, for the record'),
+            }),
+            execute: async ({ ref, element }) => {
+                const activeNote = task.startNote(`Click ${element}`);
+                const previousState = ActionResult.fromState(stateManager.getCurrentState());
+                const action = explorer.action();
+                const named = await describeRef(explorer, ref);
+                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+                if (!(await action.attempt(run, `Click ${element}`))) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
+                        suggestion: 'The ref may belong to an older version of the page. Get fresh context and use the ref it gives, or fall back to click() with a locator.',
+                    });
+                }
+                // a ref belongs to this session only, so the run is reported as the locator a later test can replay
+                const code = named ? `I.click(${JSON.stringify(named)})` : run;
+                const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, code);
+                await commitNote(activeNote, TestResult.PASSED, toolResult, action);
+                return successToolResult('clickRef', { ...toolResult, code }, action);
+            },
+        }),
+    };
+}
 export function createIframeTools({ explorer, stateManager }) {
     return {
         exitIframe: tool({
@@ -535,7 +535,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
         
         DO NOT call this if:
         - You just performed an action (pageDiff already provided in response)
-        - You already have recent <page_html>/<page_aria> in context
+        - You already have a recent <page_aria> snapshot in context
         - You're about to perform an action (you'll get pageDiff after)
         
         Call ONLY when:
@@ -675,12 +675,18 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
         }),
         interact: tool({
             description: dedent `
-        Execute an action on the current page using AI-powered interaction.
-        Use this to perform actions like clicking buttons, selecting options, filling forms, etc.
-        The AI will generate and try multiple CodeceptJS code strategies to accomplish the instruction.
+        Delegate one step to the Navigator, which reads the full page HTML and tries multiple CodeceptJS strategies.
+        Slower than the direct action tools — use it as a fallback, not as the default.
+
+        Use when:
+        - direct action tools failed and you have no better locator to try
+        - the step needs a sequence of actions to complete
+        - the element is not in the context you have
+
+        Describe the outcome to reach, not the locator to use.
       `,
             inputSchema: z.object({
-                instruction: z.string().describe('What action to perform on the page, e.g. "select new suite option", "click the Submit button"'),
+                instruction: z.string().describe('The step to perform on the page, described by its intent'),
             }),
             execute: async ({ instruction }) => {
                 try {
@@ -690,7 +696,8 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                     }
                     const previousState = ActionResult.fromState(currentState);
                     const actionResult = ActionResult.fromState(currentState);
-                    const success = await navigator.resolveState(instruction, actionResult);
+                    const experience = renderExperienceRecipes(explorer.activeTest?.getAppliedExperience(actionResult) ?? []);
+                    const success = await navigator.resolveState(instruction, actionResult, { experience });
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, instruction);
                     if (success) {
                         return successToolResult('interact', {
@@ -698,7 +705,10 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                             message: `Successfully executed: ${instruction}`,
                         });
                     }
-                    return failedToolResult('interact', `Failed to execute: ${instruction}`, {
+                    let reason = '';
+                    if (navigator.lastFailureReason)
+                        reason = `: ${navigator.lastFailureReason}`;
+                    return failedToolResult('interact', `Failed to execute: ${instruction}${reason}`, {
                         ...toolResult,
                         suggestion: 'The action could not be completed. Try a different instruction or use more specific element descriptions.',
                     });
@@ -821,7 +831,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                 }
                 const failData = { suggestion: 'Try reset() to return to the starting page.' };
                 if (action.lastError)
-                    failData.error = action.lastError.toString();
+                    failData.error = errorText(action.lastError);
                 return failedToolResult('back', `Failed to navigate back to ${targetUrl}`, failData);
             },
         }),
@@ -878,7 +888,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                 }
                 if (result.totalFound === 0) {
                     return failedToolResult('xpathCheck', `No elements matched XPath: ${xpath}`, {
-                        suggestion: 'Try a broader expression. Examples: //*[contains(@class, "btn")], //button, //*[contains(text(), "keyword")]',
+                        suggestion: 'Do not guess another expression. Narrow down from what you know about the target: its role, its visible text, its nearest labelled ancestor. Add one constraint at a time.',
                     });
                 }
                 const action = explorer.action();
@@ -960,7 +970,9 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
     withdrawVisionTools(tools);
     return tools;
 }
-const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';
+const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff. messages holds text the app showed in response, requests the calls it made and consoleErrors what it logged.';
+const FAILED_REQUEST_SUGGESTION = 'The server rejected a request made by this action (see requests). The UI accepted the interaction but the operation did not complete — read messages and consoleErrors for the reason and report it instead of repeating the action.';
+const NAVIGATED_SUGGESTION = 'The action left the page. Elements are never compared across pages, so this diff carries the move itself and what the app announced in transit — an empty element diff does not mean nothing happened.';
 const ARIA_OUTPUT_CAP = 4000;
 const HTML_OUTPUT_CAP = 6000;
 const ANALYSIS_OUTPUT_CAP = 2000;
@@ -998,7 +1010,7 @@ function transformContainsCommand(command) {
 }
 function errorText(error) {
     if (error instanceof Error)
-        return error.toString();
+        return compactErrorMessage(error);
     return 'Unknown error occurred';
 }
 export async function commitNote(activeNote, result, toolResult, action) {
@@ -1034,7 +1046,13 @@ export function successToolResult(action, data, source) {
         const ariaChanges = data.pageDiff.ariaChanges || '';
         const urlChanged = data.pageDiff.urlChanged === true;
         const hasHtmlParts = Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
-        if (isMajorPageChange(data.pageDiff)) {
+        if (hasFailedRequest(data.pageDiff)) {
+            suggestion = `${FAILED_REQUEST_SUGGESTION} ${suggestion}`;
+        }
+        else if (urlChanged) {
+            suggestion = `${NAVIGATED_SUGGESTION} ${suggestion}`;
+        }
+        else if (isMajorPageChange(data.pageDiff)) {
             suggestion = `MAJOR PAGE CHANGE. Page entered a different mode. Check htmlParts and iframes in pageDiff before next action. ${suggestion}`;
         }
         else if (!urlChanged && !ariaChanges && !hasHtmlParts) {
@@ -1050,6 +1068,9 @@ export function successToolResult(action, data, source) {
 export function isMajorPageChange(pageDiff) {
     return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
 }
+export function hasFailedRequest(pageDiff) {
+    return (pageDiff.requests ?? []).some((request) => request.status >= 400);
+}
 function hasObservablePageChange(data) {
     if (!data?.pageDiff)
         return false;
@@ -1057,6 +1078,8 @@ function hasObservablePageChange(data) {
         return true;
     if (data.pageDiff.ariaChanges)
         return true;
+    if (data.pageDiff.messages?.length)
+        return true;
     return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
 export async function failedToolResult(action, message, data, error) {
@@ -1108,6 +1131,9 @@ export function clickFailureSuggestion(attempts) {
     if (errors.some((e) => e.includes('is not visible'))) {
         return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
     }
+    if (errors.some((e) => e.includes('SyntaxError'))) {
+        return 'The command string never parsed as JavaScript — quotes or brackets do not match. No element was looked up, so this tells you nothing about the page. Re-emit the same intent as valid CodeceptJS.';
+    }
     const notFound = errors.filter((e) => e.includes('was not found'));
     if (notFound.length && notFound.every((e) => e.includes('was not found inside element'))) {
         return 'Element was not found inside that container — the container is wrong or stale, and the element may exist elsewhere on the page. Retry the same locator WITHOUT a container, or verify the container with xpathCheck().';
@@ -1188,7 +1214,7 @@ function getNotFoundSuggestion(errorMessage) {
     Element was not found. The locator does not exist on this page.
     1. Use see() to visually analyze what elements are actually on the page
     2. Use context() to get fresh HTML and ARIA snapshot
-    3. Use ONLY locators from <page_aria> or <page_html>
+    3. Use ONLY locators from <page_aria> or from HTML returned by context()
     4. Prefer ARIA locators: { "role": "button", "text": "visible text" }
   `;
 }

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

@@ -0,0 +1,51 @@
+import { type AIConfig, type ReporterConfig } from '../config.js';
+import { BaseCommand } from './base-command.js';
+export declare class ConfigCommand extends BaseCommand {
+    name: string;
+    description: string;
+    execute(): Promise<void>;
+    static summary(options?: {
+        config?: string;
+        path?: string;
+        url?: string;
+        json?: boolean;
+    }): Promise<string>;
+    static data(config: SummarizedConfig, options?: ConfigSummaryOptions): ConfigData;
+    static render(config: SummarizedConfig, options?: ConfigSummaryOptions): string;
+}
+interface ConfigSummaryOptions {
+    configPath?: string | null;
+    root?: string;
+    json?: boolean;
+}
+export interface ConfigData {
+    config: string;
+    url: string;
+    browser: string;
+    headless: boolean;
+    dirs: Record<string, string>;
+    models: Record<string, string>;
+    providers: Record<string, string>;
+    integrations: {
+        langfuse: boolean;
+        testomatio: boolean;
+    };
+    env: Record<string, string>;
+}
+interface SummarizedConfig {
+    ai?: AIConfig;
+    playwright?: {
+        url?: string;
+        browser?: string;
+        show?: boolean;
+    };
+    web?: {
+        url?: string;
+    };
+    api?: {
+        baseEndpoint?: string;
+    };
+    dirs?: Record<string, string>;
+    reporter?: ReporterConfig;
+}
+export {};

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

@@ -0,0 +1,117 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+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 { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+export class ConfigCommand extends BaseCommand {
+    name = 'config';
+    description = 'Show models, config file and paths used by this run';
+    async execute() {
+        const parser = ConfigParser.getInstance();
+        tag('info').log(ConfigCommand.render(this.explorBot.getConfig(), { configPath: parser.getConfigPath(), root: parser.getProjectRoot() }));
+    }
+    static async summary(options = {}) {
+        const parser = ConfigParser.getInstance();
+        const [site] = listSites();
+        const load = (baseUrl) => parser.loadConfig({ config: options.config, path: options.path, baseUrl });
+        const config = await load(options.url).catch((error) => {
+            if (!site)
+                throw error;
+            return load(site.url);
+        });
+        return ConfigCommand.render(config, { configPath: parser.getConfigPath(), root: parser.getProjectRoot(), json: options.json });
+    }
+    static data(config, options = {}) {
+        let configPath = '';
+        if (options.configPath && existsSync(options.configPath))
+            configPath = options.configPath;
+        const dirs = {};
+        if (options.root) {
+            for (const [name, dir] of Object.entries({ output: 'output', ...config.dirs })) {
+                dirs[name] = path.join(options.root, dir);
+            }
+        }
+        const env = {};
+        for (const variable of EXPLORBOT_ENV_VARS) {
+            const value = process.env[variable.name];
+            if (value)
+                env[variable.name] = value;
+        }
+        const models = {};
+        const providers = {};
+        for (const [role, model] of Object.entries(configuredModels(config.ai))) {
+            models[role] = model.name;
+            if (model.provider)
+                providers[role] = model.provider;
+        }
+        return {
+            config: configPath,
+            url: config.playwright?.url || config.web?.url || config.api?.baseEndpoint || '',
+            browser: config.playwright?.browser || '',
+            headless: !config.playwright?.show,
+            dirs,
+            models,
+            providers,
+            integrations: {
+                langfuse: !!config.ai?.langfuse?.enabled,
+                testomatio: Reporter.resolveEnabled(config.reporter),
+            },
+            env,
+        };
+    }
+    static render(config, options = {}) {
+        const data = ConfigCommand.data(config, options);
+        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 general = [['config', data.config || 'EXPLORBOT_* environment variables']];
+        if (data.url)
+            general.push(['url', data.url]);
+        if (data.browser) {
+            let window = 'visible';
+            if (data.headless)
+                window = 'headless';
+            general.push(['browser', `${data.browser}, ${window}`]);
+        }
+        for (const [name, dir] of Object.entries(data.dirs))
+            general.push([name, dir]);
+        section('Config', general);
+        const providerWidth = Math.max(0, ...Object.values(data.providers).map((provider) => provider.length));
+        const models = Object.entries(data.models).map(([role, model]) => {
+            if (!providerWidth)
+                return [role, model];
+            return [role, `${chalk.dim((data.providers[role] || '').padEnd(providerWidth))}  ${model}`];
+        });
+        if (!models.length)
+            models.push(['model', chalk.red(`not configured — run ${getCliName()} init`)]);
+        section('Models', models);
+        const integrations = [];
+        if (data.integrations.langfuse)
+            integrations.push(['langfuse', 'traces sent']);
+        if (data.integrations.testomatio)
+            integrations.push(['testomatio', 'runs reported']);
+        section('Integrations', integrations);
+        const env = Object.entries(data.env).map(([name, value]) => {
+            let shown = value;
+            if (shown.length > 60)
+                shown = `${shown.slice(0, 57)}...`;
+            return [name, shown];
+        });
+        section('Environment', env);
+        lines.push(chalk.dim(`Every EXPLORBOT_* variable: ${getCliName()} --help`));
+        return lines.join('\n');
+    }
+}

package/dist/src/commands/index.js

@@ -1,6 +1,7 @@
 import { AddRuleCommand } from './add-rule-command.js';
 import { CleanCommand } from './clean-command.js';
 import { CompactCommand } from './compact-command.js';
+import { ConfigCommand } from './config-command.js';
 import { ContextAriaCommand } from './context-aria-command.js';
 import { ContextCommand } from './context-command.js';
 import { ContextDataCommand } from './context-data-command.js';
@@ -64,6 +65,7 @@ const commandClasses = [
     RunsCommand,
     RerunCommand,
     StatusCommand,
+    ConfigCommand,
     DebugCommand,
     ExitCommand,
 ];

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

@@ -7,15 +7,10 @@ import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from "..
 import { getCliName } from "../utils/cli-name.js";
 import { log, tag } from '../utils/logger.js';
 import { relativeToCwd } from "../utils/next-steps.js";
-const DEFAULT_CONFIG_TEMPLATE = `import { createOpenRouter } from '@openrouter/ai-sdk-provider';
-// import { '<your provider here>' } from '<your provider package here>';
-
-// Vercel AI SDK is used to connect to AI providers.
-// Bring your own provider or use OpenRouter (one API key, many providers).
-// https://github.com/testomatio/explorbot/blob/main/docs/providers.md
-const openrouter = createOpenRouter({
-  apiKey: process.env.OPENROUTER_API_KEY,
-});
+function defaultConfigTemplate() {
+    return `// 'provider/model-id' uses a bundled provider.
+// It is also possible to import provider as a module from Vercel AI SDK.  
+// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
 
 const config = {
   web: {
@@ -24,12 +19,7 @@ const config = {
   },
 
   ai: {
-    // fast model with tool calling capabilities
-    model: openrouter('openai/gpt-oss-20b:nitro'),
-    // vision model for screenshot analysis
-    visionModel: openrouter('meta-llama/llama-4-scout-17b-16e-instruct'),
-    // agentic model for decision making
-    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+${modelLines('openrouter')}
   },
 
   reporter: {
@@ -44,6 +34,7 @@ const config = {
 
 export default config;
 `;
+}
 const DEFAULT_ENV_TEMPLATE = dedent `
 # AI provider API keys
 OPENROUTER_API_KEY=
@@ -127,7 +118,7 @@ export function runInitCommand(options) {
             log('Use --force to overwrite existing file');
             process.exit(1);
         }
-        writeFileSync(outPath, DEFAULT_CONFIG_TEMPLATE, 'utf8');
+        writeFileSync(outPath, defaultConfigTemplate(), 'utf8');
         log(`Created config file: ${relativeToCwd(outPath)}`);
         const envPath = resolve(process.cwd(), '.env');
         if (!existsSync(envPath)) {
@@ -196,15 +187,17 @@ async function renderInitWizard(mode) {
         }), { exitOnCtrlC: false, patchConsole: false });
     });
 }
-function globalConfigTemplate(provider) {
-    const { envKey } = PROVIDERS[provider];
+function modelLines(provider) {
     const recommended = ConfigParser.recommendedModels()[provider] || {};
     const roles = [
         ['model', 'fast model with tool calling capabilities'],
         ['visionModel', 'vision model for screenshot analysis'],
         ['agenticModel', 'agentic model for decision making'],
     ];
-    const models = roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+    return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+}
+function globalConfigTemplate(provider) {
+    const { envKey } = PROVIDERS[provider];
     return `// Global Explorbot configuration — used by every directory without its own explorbot.config.js.
 // Models are written as 'provider/model-id' so they resolve without a local node_modules.
 // The key is read from ${envKey} in ~/.explorbot/.env
@@ -212,7 +205,7 @@ function globalConfigTemplate(provider) {
 // https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
 const config = {
   ai: {
-${models}
+${modelLines(provider)}
   },
 
   reporter: {

package/dist/src/config.d.ts

@@ -272,12 +272,19 @@ export declare class ConfigMissingError extends Error {
 }
 export declare function envConfigRequested(): boolean;
 export declare function missingConfigMessage(configFile?: string): string;
+export declare function modelName(model: unknown): string;
+export declare function modelProvider(model: unknown): string;
+export declare function configuredModels(ai?: AIConfig): Record<string, ConfiguredModel>;
 export declare function resolveConfigModels(ai?: AIConfig): Promise<void>;
 export declare function resolveOutputRoot(baseUrl?: string): string;
 export declare function resolveStateRoot(baseUrl: string, ephemeral?: boolean): string;
 export declare function materializeKnowledge(outputRoot: string): void;
 export declare function createModel(provider: string, modelId: string): Promise<any>;
 type ModelRole = 'model' | 'visionModel' | 'agenticModel';
+interface ConfiguredModel {
+    name: string;
+    provider: string;
+}
 interface ProviderInfo {
     envKey: string;
     load: () => Promise<(modelId: string) => any>;
@@ -287,4 +294,4 @@ interface EnvVar {
     description: string;
     required?: boolean;
 }
-export type { ModelRole, EnvVar, ProviderInfo };
+export type { ModelRole, EnvVar, ProviderInfo, ConfiguredModel };