explorbot 0.1.29 → 0.1.31

package/dist/boat/doc-collector/src/ai/tools.js

@@ -1,18 +1,20 @@
 import { parseResearchSections } from "../../../../src/ai/researcher/parser.js";
-const MAX_PRIMARY_CANDIDATES = 3;
-const MAX_INTERACTIONS = 5;
+const DEFAULT_MAX_PRIMARY_CANDIDATES = 3;
+const DEFAULT_MAX_INTERACTIONS = 5;
 const MAX_LINKS = 15;
 const DEFAULT_WAIT_MS = 700;
 const TAB_WAIT_MS = 500;
-export async function collectDocInteractions(explorer, state, research) {
+const DEFAULT_DENIED_ACTION_LABELS = ['delete', 'remove', 'destroy', 'archive', 'discard', 'logout', 'sign out', 'signout', 'sign_out', 'erase', 'drop'];
+export async function collectDocInteractions(explorer, state, research, config = {}) {
     const sections = parseResearchSections(research);
     const transitions = [];
+    const maxInteractions = getPositiveConfigNumber(config.docs?.maxInteractions, DEFAULT_MAX_INTERACTIONS);
     const tabGroup = findTabGroup(sections);
     if (tabGroup) {
-        transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url)));
+        transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url, maxInteractions)));
     }
-    for (const candidate of findActionCandidates(sections)) {
-        if (transitions.length >= MAX_INTERACTIONS) {
+    for (const candidate of findActionCandidates(sections, config)) {
+        if (transitions.length >= maxInteractions) {
             break;
         }
         const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS);
@@ -23,16 +25,19 @@ export async function collectDocInteractions(explorer, state, research) {
     }
     return transitions;
 }
-export function pickDocActionCandidates(research) {
-    return findActionCandidates(parseResearchSections(research)).map((candidate) => ({
+export function pickDocActionCandidates(research, config = {}) {
+    return findActionCandidates(parseResearchSections(research), config).map((candidate) => ({
         label: candidate.element.name.trim(),
         role: candidate.role,
         section: candidate.sectionName,
     }));
 }
-async function exploreTabGroup(explorer, tabGroup, restoreUrl) {
+async function exploreTabGroup(explorer, tabGroup, restoreUrl, maxInteractions) {
     const transitions = [];
     for (const element of tabGroup.elements) {
+        if (transitions.length >= maxInteractions) {
+            break;
+        }
         const transition = await executeInteraction(explorer, {
             element,
             container: tabGroup.container,
@@ -164,21 +169,19 @@ function findTabGroup(sections) {
     }
     return null;
 }
-function findActionCandidates(sections) {
+function findActionCandidates(sections, config) {
     const candidates = [];
     const seen = new Set();
     const navigationLabels = collectNavigationLabels(sections);
+    const maxPrimaryCandidates = getPositiveConfigNumber(config.docs?.maxPrimaryCandidates, DEFAULT_MAX_PRIMARY_CANDIDATES);
     for (const section of sections) {
         const sectionName = section.name.toLowerCase();
         const container = section.containerCss?.toLowerCase() || '';
-        if (isOverlaySection(sectionName, container)) {
-            continue;
-        }
-        if (isNavigationSection(sectionName)) {
+        if (isIgnoredSection(sectionName, container)) {
             continue;
         }
         for (const element of section.elements) {
-            const candidate = toInteractionCandidate(element, section.name, section.containerCss, navigationLabels);
+            const candidate = toInteractionCandidate(element, section.name, section.containerCss, navigationLabels, config);
             if (!candidate) {
                 continue;
             }
@@ -190,9 +193,9 @@ function findActionCandidates(sections) {
             candidates.push(candidate);
         }
     }
-    return candidates.sort((a, b) => scoreCandidate(b) - scoreCandidate(a)).slice(0, MAX_PRIMARY_CANDIDATES);
+    return candidates.sort((a, b) => scoreCandidate(b) - scoreCandidate(a)).slice(0, maxPrimaryCandidates);
 }
-function toInteractionCandidate(element, sectionName, container, navigationLabels) {
+function toInteractionCandidate(element, sectionName, container, navigationLabels, config) {
     const role = getElementRole(element);
     if (role !== 'link' && role !== 'button' && role !== 'tab') {
         return null;
@@ -200,7 +203,10 @@ function toInteractionCandidate(element, sectionName, container, navigationLabel
     if (!hasUsableName(element)) {
         return null;
     }
-    if (isShellLocator(element.css) || isShellLocator(element.xpath) || isShellLocator(container)) {
+    if (isPageShellContainer(element.css) || isPageShellContainer(element.xpath)) {
+        return null;
+    }
+    if (isDestructiveAction(element, config)) {
         return null;
     }
     if (role === 'link' && navigationLabels.has(normalizeCandidateLabel(element.name))) {
@@ -340,6 +346,18 @@ function hasUsableName(element) {
 function isNavigationSection(sectionName) {
     return /(navigation|menu|header|footer|breadcrumb)/i.test(sectionName);
 }
+function isContentControlSection(sectionName) {
+    return /(content|control|filter|toolbar|action|list|data)/i.test(sectionName);
+}
+function isIgnoredSection(sectionName, container) {
+    if (isOverlaySection(sectionName, container)) {
+        return true;
+    }
+    if (isContentControlSection(sectionName)) {
+        return false;
+    }
+    return isNavigationSection(sectionName) || isPageShellContainer(container);
+}
 function isOverlaySection(sectionName, container) {
     return /(overlay|modal|popup|dialog)/i.test(sectionName) || /(overlay|modal|popup|dialog)/i.test(container);
 }
@@ -365,11 +383,11 @@ function scoreCandidate(candidate) {
     }
     return score;
 }
-function isShellLocator(locator) {
+function isPageShellContainer(locator) {
     if (!locator) {
         return false;
     }
-    return /(nav\[role="navigation"\]|header|menu|breadcrumb|footer)/i.test(locator);
+    return /(^|[\s>+~,.#\[])(nav|navigation|mainnav|header|menu|breadcrumb|footer)([\s>+~,.#\]_-]|$)/i.test(locator);
 }
 function collectNavigationLabels(sections) {
     const labels = new Set();
@@ -390,6 +408,21 @@ function collectNavigationLabels(sections) {
 function normalizeCandidateLabel(label) {
     return label.trim().toLowerCase();
 }
+function isDestructiveAction(element, config) {
+    const label = normalizeCandidateLabel(element.name);
+    const deniedLabels = config.docs?.deniedActionLabels || DEFAULT_DENIED_ACTION_LABELS;
+    if (deniedLabels.some((denied) => label.includes(normalizeCandidateLabel(denied)))) {
+        return true;
+    }
+    const locator = `${element.css || ''} ${element.xpath || ''}`.toLowerCase();
+    return deniedLabels.some((denied) => locator.includes(normalizeCandidateLabel(denied)));
+}
+function getPositiveConfigNumber(value, fallback) {
+    if (!value || value <= 0) {
+        return fallback;
+    }
+    return value;
+}
 function limitInlineText(text, maxLength) {
     const normalized = text.replace(/\s+/g, ' ').trim();
     if (normalized.length <= maxLength) {

package/dist/boat/doc-collector/src/cli.js

@@ -89,6 +89,9 @@ export function createDocsCommands(name = 'docs') {
             includePaths: [],
             excludePaths: [],
             deniedPathSegments: ['callback', 'callbacks', 'logout', 'signout', 'sign_out', 'destroy', 'delete', 'remove'],
+            deniedActionLabels: ['delete', 'remove', 'destroy', 'archive', 'discard', 'logout', 'sign out', 'signout', 'sign_out', 'erase', 'drop'],
+            maxPrimaryCandidates: 3,
+            maxInteractions: 5,
             minCanActions: 1,
             minInteractiveElements: 3,
             // prompt: 'Add domain-specific documentation guidance here',

package/dist/boat/doc-collector/src/config.js

@@ -110,6 +110,9 @@ class DocbotConfigParser {
                 includePaths: [],
                 excludePaths: [],
                 deniedPathSegments: ['callback', 'callbacks', 'logout', 'signout', 'sign_out', 'destroy', 'delete', 'remove'],
+                deniedActionLabels: ['delete', 'remove', 'destroy', 'archive', 'discard', 'logout', 'sign out', 'signout', 'sign_out', 'erase', 'drop'],
+                maxPrimaryCandidates: 3,
+                maxInteractions: 5,
                 minCanActions: 1,
                 minInteractiveElements: 3,
             },

package/dist/boat/doc-collector/src/docbot.js

@@ -2,13 +2,14 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { ExplorBot } from "../../../src/explorbot.js";
 import { normalizeUrl } from "../../../src/state-manager.js";
-import { sanitizeFilename } from "../../../src/utils/strings.js";
 import { tag } from "../../../src/utils/logger.js";
+import { sanitizeFilename } from "../../../src/utils/strings.js";
 import { Documentarian } from "./ai/documentarian.js";
 import { DocbotConfigParser } from "./config.js";
 import { renderPageDocumentation, renderSpecIndex } from "./docs-renderer.js";
 import { getDocPageKey, shouldCrawlDocPath } from "./path-filter.js";
 import { extractResearchNavigationTargets } from "./research-navigation.js";
+import { captureDocumentationScreenshots } from "./screenshots.js";
 class DocBot {
     explorBot;
     configParser;
@@ -105,7 +106,7 @@ class DocBot {
                     documented.add(pageKey);
                     continue;
                 }
-                const filePath = this.savePageDocumentation(state, documentation);
+                const filePath = await this.savePageDocumentation(state, documentation, research);
                 pages.push({
                     url: state.url,
                     title: state.title || '',
@@ -347,11 +348,22 @@ class DocBot {
         const matches = [...research.matchAll(/\((\d+) elements?\)/g)];
         return matches.reduce((sum, match) => sum + Number.parseInt(match[1], 10), 0);
     }
-    savePageDocumentation(state, documentation) {
+    async savePageDocumentation(state, documentation, research) {
         const pagePath = this.getPageFilePath(state.url);
-        writeFileSync(pagePath, renderPageDocumentation(state, documentation), 'utf8');
+        const screenshots = await this.captureScreenshots(state, research, pagePath);
+        writeFileSync(pagePath, renderPageDocumentation(state, documentation, screenshots), 'utf8');
         return pagePath;
     }
+    async captureScreenshots(state, research, pagePath) {
+        if (!this.shouldUseScreenshots()) {
+            return [];
+        }
+        return captureDocumentationScreenshots(this.explorBot.getExplorer(), state, research, {
+            pageFilePath: pagePath,
+            screenshotsDir: this.getScreenshotsDir(),
+            config: this.config,
+        });
+    }
     saveIndex(startPath, pages, skipped, maxPages) {
         const indexPath = path.join(this.configParser.getOutputDir(), 'spec.md');
         writeFileSync(indexPath, renderSpecIndex(this.configParser.getOutputDir(), startPath, pages, skipped, maxPages), 'utf8');
@@ -360,6 +372,9 @@ class DocBot {
     getPagesDir() {
         return path.join(this.configParser.getOutputDir(), 'pages');
     }
+    getScreenshotsDir() {
+        return path.join(this.configParser.getOutputDir(), 'screenshots');
+    }
     getPageFilePath(pageUrl) {
         const normalized = normalizeUrl(pageUrl || '/');
         const baseName = sanitizeFilename(normalized || 'root');

package/dist/boat/doc-collector/src/docs-renderer.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-function renderPageDocumentation(state, documentation) {
+function renderPageDocumentation(state, documentation, screenshots = []) {
     const lines = [];
     lines.push(`# ${state.url}`);
     lines.push('');
@@ -11,6 +11,17 @@ function renderPageDocumentation(state, documentation) {
     lines.push('');
     lines.push(ensureSentence(documentation.summary));
     lines.push('');
+    if (screenshots.length > 0) {
+        lines.push('## Screenshots');
+        lines.push('');
+        for (const screenshot of screenshots) {
+            lines.push(`![${normalizeInlineText(screenshot.title)}](${screenshot.relativePath})`);
+            if (screenshot.selector) {
+                lines.push(`Section: \`${screenshot.selector}\``);
+            }
+            lines.push('');
+        }
+    }
     const interactions = documentation.interactions;
     if (interactions && interactions.length > 0) {
         lines.push('## State Transitions');

package/dist/boat/doc-collector/src/screenshots.js

@@ -0,0 +1,90 @@
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { parseResearchSections } from "../../../src/ai/researcher/parser.js";
+import { safeFilename, sanitizeFilename } from "../../../src/utils/strings.js";
+const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
+export async function captureDocumentationScreenshots(explorer, state, research, options) {
+    const page = explorer.playwrightHelper?.page;
+    if (!page) {
+        return [];
+    }
+    mkdirSync(options.screenshotsDir, { recursive: true });
+    const screenshots = [];
+    const pageName = sanitizeFilename(state.url || 'page') || 'page';
+    const fullPage = await captureFullPageScreenshot(page, pageName, options);
+    if (fullPage) {
+        screenshots.push(fullPage);
+    }
+    const maxSections = getMaxSectionScreenshots(options.config);
+    for (const section of getScreenshotSections(research).slice(0, maxSections)) {
+        const screenshot = await captureSectionScreenshot(page, pageName, section, options);
+        if (!screenshot) {
+            continue;
+        }
+        screenshots.push(screenshot);
+    }
+    return screenshots;
+}
+export function getScreenshotSections(research) {
+    const sections = [];
+    const seen = new Set();
+    for (const section of parseResearchSections(research)) {
+        if (!section.containerCss) {
+            continue;
+        }
+        if (section.elements.length === 0) {
+            continue;
+        }
+        if (seen.has(section.containerCss)) {
+            continue;
+        }
+        seen.add(section.containerCss);
+        sections.push({
+            title: section.name,
+            selector: section.containerCss,
+        });
+    }
+    return sections;
+}
+async function captureFullPageScreenshot(page, pageName, options) {
+    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
+    try {
+        await page.screenshot({ path: filePath, fullPage: true });
+    }
+    catch {
+        return null;
+    }
+    return {
+        title: 'Page screenshot',
+        path: filePath,
+        relativePath: toMarkdownPath(options.pageFilePath, filePath),
+        kind: 'page',
+    };
+}
+async function captureSectionScreenshot(page, pageName, section, options) {
+    const sectionName = sanitizeFilename(section.title) || 'section';
+    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${sectionName}`, '.png'));
+    try {
+        await page.locator(section.selector).first().screenshot({ path: filePath });
+    }
+    catch {
+        return null;
+    }
+    return {
+        title: section.title,
+        path: filePath,
+        relativePath: toMarkdownPath(options.pageFilePath, filePath),
+        kind: 'section',
+        selector: section.selector,
+    };
+}
+function getMaxSectionScreenshots(config) {
+    const configured = config.docs?.maxSectionScreenshots;
+    if (configured && configured > 0) {
+        return configured;
+    }
+    return DEFAULT_MAX_SECTION_SCREENSHOTS;
+}
+function toMarkdownPath(pageFilePath, assetPath) {
+    return path.relative(path.dirname(pageFilePath), assetPath).replaceAll('\\', '/');
+}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -74,7 +74,7 @@
     "@faker-js/faker": "^10.4.0",
     "@inkjs/ui": "^2.0.0",
     "@langfuse/otel": "^4.5.1",
-    "@openrouter/ai-sdk-provider": "^2.3.3",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.67.3",
     "@opentelemetry/instrumentation": "^0.208.0",

package/dist/src/action.js

@@ -10,11 +10,13 @@ import { ActionResult } from './action-result.js';
 import { clearActivity, setActivity } from "./activity.js";
 import { ConfigParser, outputPath } from './config.js';
 import { Observability } from "./observability.js";
+import { isFatalBrowserError, isNavigationTransitionError } from "./utils/browser-errors.js";
 import { htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
+import { waitForPageReadiness } from "./utils/page-readiness.js";
 import { safeFilename } from "./utils/strings.js";
-import { isFatalBrowserError } from "./utils/browser-errors.js";
 const debugLog = createDebug('explorbot:action');
+const CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS = 3;
 class Action {
     actor;
     stateManager;
@@ -63,17 +65,24 @@ class Action {
             const timestamp = Date.now();
             const page = this.playwrightHelper.page;
             const frame = this.playwrightHelper.frame;
-            await page?.waitForLoadState('domcontentloaded', { timeout: 10000 })?.catch(() => { });
-            await waitForUsablePageDom(page);
+            await this.waitForPageReadiness(page);
             const grabAll = () => Promise.all([captureHtml(page, frame, this.actor), captureTitle(page, this.actor), this.captureBrowserLogs()]);
-            const [html, title, browserLogs] = await grabAll().catch(async (err) => {
-                const msg = err instanceof Error ? err.message : String(err);
-                if (!/navigating and changing the content/i.test(msg))
-                    throw err;
-                await page?.waitForLoadState('domcontentloaded', { timeout: 10000 })?.catch(() => { });
-                await waitForUsablePageDom(page);
-                return grabAll();
-            });
+            let html = '';
+            let title = '';
+            let browserLogs = [];
+            for (let attempt = 1; attempt <= CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS; attempt++) {
+                try {
+                    [html, title, browserLogs] = await grabAll();
+                    break;
+                }
+                catch (err) {
+                    if (!isNavigationTransitionError(err))
+                        throw err;
+                    if (attempt === CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS)
+                        throw err;
+                    await this.waitForPageReadiness(page);
+                }
+            }
             const url = page?.url() || (await this.actor.grabCurrentUrl?.());
             let screenshotFile = undefined;
             const statesDir = outputPath('states');
@@ -399,6 +408,12 @@ class Action {
     getActionResult() {
         return this.actionResult;
     }
+    async waitForPageReadiness(page) {
+        await waitForPageReadiness(page, {
+            timeout: this.config.playwright.waitForTimeout,
+            spinnerSelectors: this.config.playwright.spinnerSelectors,
+        });
+    }
 }
 export default Action;
 function errorToString(error) {
@@ -407,18 +422,6 @@ function errorToString(error) {
     }
     return error.message || error.toString();
 }
-async function waitForUsablePageDom(page) {
-    if (!page?.waitForFunction)
-        return;
-    await page
-        .waitForFunction(() => {
-        const body = document.body;
-        if (!body)
-            return false;
-        return body.children.length > 0 || body.textContent?.trim().length > 0;
-    }, undefined, { timeout: 5000 })
-        .catch(() => { });
-}
 async function captureHtml(page, frame, actor) {
     if (frame?.content)
         return frame.content();

package/dist/src/ai/conversation.js

@@ -34,7 +34,7 @@ export class Conversation {
         const imageData = image.startsWith('data:') ? image : `data:image/png;base64,${image}`;
         this.messages.push({
             role: 'user',
-            content: [{ type: 'image', image: imageData }],
+            content: [{ type: 'file', mediaType: 'image/png', data: imageData }],
         });
     }
     addAssistantText(text) {

package/dist/src/ai/historian/codeceptjs.js

@@ -6,8 +6,9 @@ import { KnowledgeTracker } from "../../knowledge-tracker.js";
 import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
 import { safeFilename } from "../../utils/strings.js";
-import { ASSERTION_TOOLS, CODECEPT_TOOLS } from "../tools.js";
-import { escapeString, getExecutionLabel, isNonReusableCode, stripComments } from "./utils.js";
+import { CODECEPT_TOOLS, isNonReusableCode, stripComments } from "../../utils/step-analyzer.js";
+import { ASSERTION_TOOLS } from "../tools.js";
+import { escapeString, getExecutionLabel } from "./utils.js";
 export function WithCodeceptJS(Base) {
     return class extends Base {
         toCode(conversation, scenario) {

package/dist/src/ai/historian/experience.js

@@ -3,10 +3,10 @@ import { z } from 'zod';
 import { ActionResult } from "../../action-result.js";
 import { Test } from "../../test-plan.js";
 import { tag } from "../../utils/logger.js";
+import { isCodeceptToolName, isNonReusableCode, mergeUniqueStepsByCode, stripComments, toReusableSessionStep } from "../../utils/step-analyzer.js";
 import { extractStatePath } from "../../utils/url-matcher.js";
-import { CODECEPT_TOOLS } from "../tools.js";
 import { debugLog } from "./mixin.js";
-import { getExecutionLabel, isNonReusableCode, stripComments } from "./utils.js";
+import { getExecutionLabel } from "./utils.js";
 export function WithExperience(Base) {
     return class extends Base {
         async saveSession(task, initialState, conversation) {
@@ -16,11 +16,17 @@ export function WithExperience(Base) {
             if (task instanceof Test) {
                 task.generatedCode = this.isPlaywrightFramework() ? await this.toPlaywrightCode(conversation, task.description) : this.toCode(conversation, task.description);
             }
-            const steps = await this.extractSteps(toolExecutions);
+            const conversationSteps = await this.extractSteps(toolExecutions);
+            const taskSteps = this.extractPassedCodeceptSteps(task);
+            const steps = mergeUniqueStepsByCode(conversationSteps, taskSteps);
             const skipExperience = result === 'failed' || (task instanceof Test && (task.hasFailed || task.isSkipped));
             if (!skipExperience) {
+                const hasExistingFlow = this.hasRelevantFlowExperience(initialState);
                 await this.detectRetryPatterns(toolExecutions, initialState);
-                const body = await this.curateFlow(steps, task, initialState);
+                let body = await this.curateFlow(steps, task, initialState);
+                if (!body.trim() && !hasExistingFlow) {
+                    body = this.renderFlowFromSuccessfulSteps(steps, task);
+                }
                 if (body.trim()) {
                     const relatedUrls = this.extractVisitedUrls(toolExecutions, initialState.url || '');
                     this.experienceTracker.writeFlow(initialState, body, relatedUrls);
@@ -46,7 +52,7 @@ export function WithExperience(Base) {
         async extractSteps(toolExecutions) {
             const stepsWithDiffs = [];
             for (const exec of toolExecutions) {
-                if (!CODECEPT_TOOLS.includes(exec.toolName))
+                if (!isCodeceptToolName(exec.toolName))
                     continue;
                 if (!exec.output?.code)
                     continue;
@@ -65,6 +71,18 @@ export function WithExperience(Base) {
             await this.analyzeDiscoveries(stepsWithDiffs);
             return stepsWithDiffs.map((s) => s.step);
         }
+        hasRelevantFlowExperience(state) {
+            return this.experienceTracker.getRelevantExperience(state).some((experience) => experience.content.includes('## FLOW:'));
+        }
+        extractPassedCodeceptSteps(task) {
+            const steps = [];
+            for (const step of Object.values(task.steps)) {
+                const sessionStep = toReusableSessionStep(step);
+                if (sessionStep)
+                    steps.push(sessionStep);
+            }
+            return steps;
+        }
         async curateFlow(steps, task, initialState) {
             if (steps.length === 0)
                 return '';
@@ -167,13 +185,37 @@ export function WithExperience(Base) {
                 return '';
             }
         }
+        renderFlowFromSuccessfulSteps(steps, task) {
+            if (steps.length === 0)
+                return '';
+            const title = task.description.charAt(0).toLowerCase() + task.description.slice(1);
+            const blocks = steps
+                .filter((step) => step.code)
+                .map((step) => {
+                const lines = [`* ${step.message}`];
+                lines.push('');
+                lines.push('```js');
+                lines.push(stripComments(step.code || ''));
+                lines.push('```');
+                if (step.discovery) {
+                    lines.push('');
+                    for (const discovery of step.discovery.split('\n').filter((line) => line.trim())) {
+                        lines.push(`> ${discovery.trim()}`);
+                    }
+                }
+                return lines.join('\n');
+            });
+            if (blocks.length === 0)
+                return '';
+            return `## FLOW: ${title}\n\n${blocks.join('\n\n')}\n\n---\n`;
+        }
         async detectRetryPatterns(toolExecutions, initialState) {
             if (!this.experienceTracker || !this.stateManager)
                 return;
             const failedByTool = new Map();
             const candidates = [];
             for (const exec of toolExecutions) {
-                if (!CODECEPT_TOOLS.includes(exec.toolName))
+                if (!isCodeceptToolName(exec.toolName))
                     continue;
                 if (!exec.output?.code)
                     continue;

package/dist/src/ai/historian/playwright.js

@@ -7,7 +7,8 @@ import { renderAssertion, renderCall } from "../../playwright-recorder.js";
 import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
 import { safeFilename } from "../../utils/strings.js";
-import { ASSERTION_TOOLS, CODECEPT_TOOLS } from "../tools.js";
+import { CODECEPT_TOOLS } from "../../utils/step-analyzer.js";
+import { ASSERTION_TOOLS } from "../tools.js";
 import { escapeString, getExecutionLabel } from "./utils.js";
 const PLAYWRIGHT_EMITTED_TOOLS = [...CODECEPT_TOOLS, ...ASSERTION_TOOLS];
 export function WithPlaywright(Base) {

package/dist/src/ai/historian/utils.js

@@ -1,25 +1,7 @@
-import { isDynamicId } from "../../utils/xpath.js";
-export function isNonReusableCode(code) {
-    if (/\bI\.clickXY\s*\(/.test(code))
-        return true;
-    for (const m of code.matchAll(/#([A-Za-z_][\w-]*)/g)) {
-        if (isDynamicId(m[1]))
-            return true;
-    }
-    return false;
-}
+export { isNonReusableCode, stripComments } from "../../utils/step-analyzer.js";
 export function escapeString(str) {
     return str.replace(/'/g, "\\'").replace(/\n/g, ' ');
 }
-export function stripComments(code) {
-    return code
-        .split('\n')
-        .filter((line) => {
-        const trimmed = line.trim();
-        return trimmed && !trimmed.startsWith('//') && !trimmed.startsWith('/*') && !trimmed.startsWith('*');
-    })
-        .join('\n');
-}
 export function getExecutionLabel(exec, fallback) {
     return exec.input?.explanation || exec.input?.assertion || exec.input?.note || fallback || '';
 }

package/dist/src/ai/historian.js

@@ -6,7 +6,7 @@ import { WithCodeceptJS } from "./historian/codeceptjs.js";
 import { WithExperience } from "./historian/experience.js";
 import { WithPlaywright } from "./historian/playwright.js";
 import { WithScreencast } from "./historian/screencast.js";
-export { isNonReusableCode } from "./historian/utils.js";
+export { isNonReusableCode } from "../utils/step-analyzer.js";
 const HistorianBase = WithScreencast(WithPlaywright(WithCodeceptJS(WithExperience(Object))));
 export class Historian extends HistorianBase {
     constructor(provider, experienceTracker, reporter, stateManager, config, playwright) {

package/dist/src/ai/provider.js

@@ -578,8 +578,9 @@ export class Provider {
                         text: prompt,
                     },
                     {
-                        type: 'image',
-                        image: imageData,
+                        type: 'file',
+                        mediaType: 'image/png',
+                        data: imageData,
                     },
                 ],
             },

package/dist/src/ai/quartermaster.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { z } from 'zod';
 import { ConfigParser } from "../config.js";
 import { createDebug, tag } from "../utils/logger.js";
-import { CODECEPT_TOOLS } from "./tools.js";
+import { isCodeceptToolName } from "../utils/step-analyzer.js";
 const debugLog = createDebug('explorbot:quartermaster');
 export class Quartermaster {
     provider;
@@ -88,7 +88,7 @@ export class Quartermaster {
             const stateHash = initialState.getStateHash();
             const pageAnalysis = this.pageAnalyses.get(stateHash);
             const toolExecutions = conversation.getToolExecutions();
-            const codeceptExecutions = toolExecutions.filter((e) => CODECEPT_TOOLS.includes(e.toolName));
+            const codeceptExecutions = toolExecutions.filter((e) => isCodeceptToolName(e.toolName));
             if (codeceptExecutions.length === 0 && !pageAnalysis?.axeViolations.length) {
                 debugLog('No interactions or violations to analyze');
                 return null;