explorbot 0.4.6 → 0.4.8

package/dist/src/ai/planner/session-dedup.d.ts

@@ -1,4 +1,4 @@
-import type { Plan } from '../../test-plan.js';
+import { type Plan, type Test } from '../../test-plan.js';
 import type { Constructor } from '../researcher/mixin.js';
 export declare function WithSessionDedup<T extends Constructor>(Base: T): {
     new (...args: any[]): {
@@ -9,4 +9,5 @@ export declare function WithSessionDedup<T extends Constructor>(Base: T): {
         getPreviousSessionScenariosExcluding(plan: Plan): Set<string>;
     };
 } & T;
+export declare function formatSessionTest(plan: Plan, test: Test): string;
 export declare function clearSessionDedup(): void;

package/dist/src/ai/planner/session-dedup.js

@@ -1,3 +1,4 @@
+import { TestResult } from "../../test-plan.js";
 const previousPlans = [];
 export function WithSessionDedup(Base) {
     return class extends Base {
@@ -12,7 +13,7 @@ export function WithSessionDedup(Base) {
                 if (plan === this.currentPlan)
                     continue;
                 for (const test of plan.tests) {
-                    lines.push(`${plan.url || '/'} | ${test.style || 'default'} | ${test.scenario}`);
+                    lines.push(formatSessionTest(plan, test));
                 }
             }
             return lines.join('\n');
@@ -25,6 +26,22 @@ export function WithSessionDedup(Base) {
         }
     };
 }
+export function formatSessionTest(plan, test) {
+    const lastNote = Object.values(test.notes)
+        .filter((note) => note.message)
+        .pop();
+    let outcome = test.result;
+    if (!outcome)
+        outcome = 'pending';
+    if (!test.result && lastNote)
+        outcome = 'unfinished';
+    const line = `${plan.url || '/'} | ${test.style || 'default'} | ${outcome} | ${test.scenario}`;
+    if (!lastNote)
+        return line;
+    if (outcome !== TestResult.FAILED && outcome !== 'unfinished')
+        return line;
+    return `${line} — ${lastNote.message.slice(0, 140)}`;
+}
 export function clearSessionDedup() {
     previousPlans.length = 0;
 }

package/dist/src/ai/planner.js

@@ -316,8 +316,10 @@ export class Planner extends PlannerBase {
       You can suggest scenarios that can be tested only through web interface.
       You can't test emails, database, SMS, or any external services.
       Suggest scenarios that can be potentially verified by UI.
-      Focus on error or success messages as outcome.
-      Focus on URL page change or data persistency after page reload.
+      Prefer outcomes grounded in observed interface behavior.
+      Every expected outcome must be verifiable through the web interface.
+      If a page or subpage has not been observed, describe the expected visible result generically instead of inventing interface details.
+      Persistency after a reload counts only when the persisted state can be confirmed through the interface.
       If there are subpages (pages with same URL path) plan testing of those subpages as well
       Plan CRUD operations in order: create, read, update, delete.
       Do not invent specific route names, success messages, validation texts, badge counts, or welcome messages unless they are visible in research, visited pages, or prior observed flows.
@@ -328,7 +330,7 @@ export class Planner extends PlannerBase {
       If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible, API preconditions can create it, or the scenario itself creates the record as its setup.
       If the page appears read-only, degraded, demo-limited, maintenance-like, or lacks write controls, prefer read-only scenarios such as opening panels, inspecting visible lists, filtering, searching, or verifying current state.
       Do not assume hidden data exists just because a control is present.
-      For scenarios that act on existing items or search/filter by existing values, use only item names or values visible in research, visited pages, or prior observed flows.
+      Do not put record IDs or unique record names in test plans. Describe which record is needed and let Pilot choose it during execution; name a specific record only when research shows a small, complete list of available records.
       If the list is empty or no concrete item names are visible, do not invent "known" or "existing" items. Prefer empty-state, no-match search, clear-search, or read-only list behavior scenarios.
       Search, filter, sorting, tab, and list scenarios must start from a stable page where those controls are visible; avoid transient create/edit/new URLs unless the scenario tests that form.
       For option values and list items, use only visible or previously observed data; do not add create/update/delete setup unless the user explicitly requests that workflow.
@@ -404,12 +406,16 @@ export class Planner extends PlannerBase {
         `);
             }
         }
+        let activeRegion = '';
+        if (state.overlay.isOpen)
+            activeRegion = `Active region: ${state.overlay.describe()} — the user's current focus area. Plan tests for the controls inside it first.`;
         conversation.addUserText(dedent `
       ${this.buildApproach(style)}
 
       <context>
       URL: ${state.url || 'Unknown'}
       Title: ${state.title || 'Unknown'}
+      ${activeRegion}
       </context>
     `);
         if (this.fisherman) {
@@ -536,7 +542,9 @@ export class Planner extends PlannerBase {
         const sessionTests = this.getSessionTestsSummary();
         if (sessionTests) {
             conversation.addUserText(dedent `
-        Tests already planned in this session across all pages. DO NOT duplicate any of these:
+        Tests already planned in this session across all pages, with how each one ended. DO NOT duplicate any of these.
+        A failed test means the app or the harness could not do what it tried: do not re-propose the same behavior on another page unless you can name what makes it work this time.
+        A failed or unfinished test carries the last thing it observed after the dash — read it before deciding that the behavior is worth trying again.
 
         <session_tests>
         ${sessionTests}

package/dist/src/ai/provider.js

@@ -32,6 +32,11 @@ function createHarmonyChannelFallbackTool() {
         execute: async () => ({ message: 'Noted. Continue with your next action.' }),
     });
 }
+function withHarmonyChannelFallback(tools) {
+    if (tools?.commentary)
+        return tools;
+    return { ...tools, commentary: createHarmonyChannelFallbackTool() };
+}
 let telemetryRegistered = false;
 let beforeExitFlushHooked = false;
 let activeOtelSdk = null;
@@ -367,8 +372,8 @@ export class Provider {
         setActivity(`🤖 Asking ${modelName} with dynamic tools`, 'ai');
         promptLog(`Using model: ${modelName}`);
         let toolsWithCommentary = tools;
-        if (!tools?.commentary && options.toolChoice !== 'required')
-            toolsWithCommentary = { ...tools, commentary: createHarmonyChannelFallbackTool() };
+        if (options.toolChoice !== 'required')
+            toolsWithCommentary = withHarmonyChannelFallback(tools);
         const toolNames = Object.keys(toolsWithCommentary || {});
         tag('debug').log(`Tools enabled: [${toolNames.join(', ')}]`);
         promptLog('Available tools:', toolNames);
@@ -378,9 +383,10 @@ export class Provider {
         const stopConditions = [isStepCount(maxRoundtrips)];
         if (extraStop)
             stopConditions.push(extraStop);
-        const config = this.buildGenerateConfig({ tools: toolsWithCommentary, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
+        let config = this.buildGenerateConfig({ tools: toolsWithCommentary, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
         let attemptMessages = messages;
         let invalidRequestFeedbackAdded = false;
+        let requiredToolChoiceRelaxed = false;
         const executedStepMessages = [];
         try {
             let response = await this.withModelRequestSlot(() => withRetry(async () => {
@@ -399,6 +405,11 @@ export class Provider {
                         invalidRequestFeedbackAdded = amended !== attemptMessages;
                         attemptMessages = amended;
                     }
+                    if (!requiredToolChoiceRelaxed && isRequiredToolChoiceError(error)) {
+                        requiredToolChoiceRelaxed = true;
+                        config = { ...config, tools: withHarmonyChannelFallback(tools), toolChoice: 'auto' };
+                        tag('warning').log('Provider rejected required tool choice — retrying with automatic tool choice and channel fallback');
+                    }
                     throw error;
                 }));
                 this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
@@ -422,7 +433,7 @@ export class Provider {
         }
         catch (error) {
             clearActivity();
-            if (error?.message?.includes('Tool choice is required')) {
+            if (isRequiredToolChoiceError(error)) {
                 return { text: '', toolCalls: [], toolResults: [], responseMessages: executedStepMessages, usage: null };
             }
             if (error?.name === 'AbortError')
@@ -659,6 +670,9 @@ function withInvalidRequestFeedback(messages, error) {
         },
     ];
 }
+function isRequiredToolChoiceError(error) {
+    return error instanceof Error && error.message.includes('Tool choice is required');
+}
 function repairChannelMarker({ toolCall, tools }) {
     const markerIndex = toolCall.toolName.indexOf('<|channel|>');
     if (markerIndex <= 0)

package/dist/src/ai/researcher/locators.js

@@ -281,7 +281,7 @@ export function WithLocators(Base) {
             if (sectionQuery.count() === 0)
                 sectionQuery = mdq(result.text).query(`section3(~"${escaped}")`);
             if (newCss) {
-                result.text = sectionQuery.query('blockquote[0]').replace(`Container: '${newCss}'`);
+                result.text = sectionQuery.query('blockquote[0]').setKeyValue('Container', `'${newCss}'`);
             }
             else {
                 result.text = sectionQuery.query('blockquote[0]').replace('');

package/dist/src/ai/researcher/pagination.d.ts

@@ -0,0 +1,16 @@
+import type Explorer from '../../explorer.js';
+import { type ListMeasure, type PaginationStrategy } from '../../utils/pagination.js';
+import { type Constructor } from './mixin.js';
+import type { ResearchResult } from './research-result.js';
+export declare function WithPagination<T extends Constructor>(Base: T): {
+    new (...args: any[]): {
+        explorer: Explorer;
+        detectPagination(result: ResearchResult): Promise<void>;
+        probeSection(css: string): Promise<PaginationStrategy | null>;
+        measure(css: string): Promise<ListMeasure | null>;
+        recordPagination(result: ResearchResult, name: string, strategy: PaginationStrategy): void;
+    };
+} & T;
+export interface PaginationMethods {
+    detectPagination(result: ResearchResult): Promise<void>;
+}

package/dist/src/ai/researcher/pagination.js

@@ -0,0 +1,62 @@
+import { mdq } from "../../utils/markdown-query.js";
+import { inspectList, restoreScroll } from "../../utils/pagination.js";
+import { debugLog } from "./mixin.js";
+import { extractPaginationFromBlockquote, parseDataSections, parseResearchSections } from "./parser.js";
+export function WithPagination(Base) {
+    return class extends Base {
+        async detectPagination(result) {
+            const sections = [...parseResearchSections(result.text), ...parseDataSections(result.text)];
+            for (const section of sections) {
+                const css = section.containerCss;
+                if (!css)
+                    continue;
+                if (extractPaginationFromBlockquote(section.rawMarkdown))
+                    continue;
+                const strategy = await this.probeSection(css);
+                if (!strategy)
+                    continue;
+                this.recordPagination(result, section.name, strategy);
+                debugLog(`Pagination in "${section.name}": ${strategy}`);
+            }
+        }
+        async probeSection(css) {
+            const before = await this.measure(css);
+            if (!before)
+                return null;
+            if (before.hasPagingControls)
+                return 'controls';
+            if (before.isFeed)
+                return 'infinite';
+            if (!before.scrolls)
+                return null;
+            const action = this.explorer.action();
+            const scrolled = await action.attempt(`I.scrollTo('${css} > *:last-child')`).catch(() => false);
+            if (!scrolled)
+                return null;
+            const after = await this.measure(css);
+            await this.explorer.withPage((page) => page.evaluate(restoreScroll, { css, scrollTop: before.scrollTop, pageScrollY: before.pageScrollY })).catch(() => { });
+            if (!after)
+                return null;
+            if (after.items > before.items)
+                return 'infinite';
+            return null;
+        }
+        measure(css) {
+            return this.explorer
+                .withPage((page) => page.evaluate(inspectList, css))
+                .catch((err) => {
+                debugLog(`List measurement failed for '${css}': ${err.message}`);
+                return null;
+            });
+        }
+        recordPagination(result, name, strategy) {
+            const escaped = name.replace(/"/g, '\\"');
+            let sectionQuery = mdq(result.text).query(`section2(~"${escaped}")`);
+            if (sectionQuery.count() === 0)
+                sectionQuery = mdq(result.text).query(`section3(~"${escaped}")`);
+            if (sectionQuery.count() === 0)
+                return;
+            result.text = sectionQuery.query('blockquote[0]').setKeyValue('Pagination', strategy);
+        }
+    };
+}

package/dist/src/ai/researcher/parser.d.ts

@@ -1,3 +1,4 @@
+import type { PaginationStrategy } from '../../utils/pagination.js';
 export interface ResearchElement {
     name: string;
     type: string | null;
@@ -23,6 +24,8 @@ export declare const RESEARCH_COLUMN_ORDER: string[];
 export declare function mapRowToElement(row: Record<string, string>): ResearchElement | null;
 export declare function extractContainerFromBlockquote(sectionMarkdown: string): string | null;
 export declare function parseResearchSections(markdown: string): ResearchSection[];
+export declare function parseDataSections(markdown: string): ResearchSection[];
+export declare function extractPaginationFromBlockquote(sectionMarkdown: string): PaginationStrategy | null;
 export declare function extractValidContainers(researchText: string, opts?: {
     exclude?: string[];
 }): Array<{

package/dist/src/ai/researcher/parser.js

@@ -57,13 +57,10 @@ export function mapRowToElement(row) {
     };
 }
 export function extractContainerFromBlockquote(sectionMarkdown) {
-    const bq = mdq(sectionMarkdown).query('blockquote[0]').text().trim();
-    if (!bq)
+    const entry = mdq(sectionMarkdown).query('blockquote[0]').keyValue().container;
+    if (!entry)
         return null;
-    const match = bq.match(/Container:\s*(.+)/i);
-    if (!match)
-        return null;
-    const css = normalizeLocatorValue(match[1]);
+    const css = normalizeLocatorValue(entry);
     if (!css || !/^[.#\[\w]/.test(css))
         return null;
     return css;
@@ -80,6 +77,25 @@ export function parseResearchSections(markdown) {
         return { name: section.name, containerCss, elements, rawMarkdown: section.rawMarkdown, isExtended };
     });
 }
+export function parseDataSections(markdown) {
+    return parseSections(markdown)
+        .filter((s) => s.name.toLowerCase().startsWith('data:'))
+        .map((section) => ({
+        name: section.name,
+        containerCss: extractContainerFromBlockquote(section.rawMarkdown),
+        elements: [],
+        rawMarkdown: section.rawMarkdown,
+        isExtended: false,
+    }));
+}
+export function extractPaginationFromBlockquote(sectionMarkdown) {
+    const value = mdq(sectionMarkdown).query('blockquote[0]').keyValue().pagination?.toLowerCase();
+    if (value === 'controls')
+        return 'controls';
+    if (value === 'infinite')
+        return 'infinite';
+    return null;
+}
 export function extractValidContainers(researchText, opts) {
     const exclude = opts?.exclude || [];
     return parseResearchSections(researchText)

package/dist/src/ai/researcher/sections.js

@@ -63,7 +63,7 @@ export function WithSections(Base) {
         }
         async _researchSingleSection(name, description, ariaSnapshot, focusCss) {
             const currentUrl = this.stateManager.getCurrentState()?.url || '';
-            const rules = RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl);
+            const rules = RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules', 'pagination'], currentUrl);
             const url = this.actionResult?.url || 'Unknown';
             const title = this.actionResult?.title || 'Unknown';
             let focusHint = '';

package/dist/src/ai/researcher.js

@@ -18,6 +18,7 @@ import { WithCoordinates } from "./researcher/coordinates.js";
 import { WithDeepAnalysis } from "./researcher/deep-analysis.js";
 import { detectFocusedSection, hasFocusedSection, markSectionAsFocused, pickDefaultFocusedSection } from "./researcher/focus.js";
 import { WithLocators } from "./researcher/locators.js";
+import { WithPagination } from "./researcher/pagination.js";
 import { extractValidContainers, formatResearchSummary, parseResearchSections } from "./researcher/parser.js";
 import { ResearchResult } from "./researcher/research-result.js";
 import { WithSections } from "./researcher/sections.js";
@@ -33,7 +34,7 @@ export const POSSIBLE_SECTIONS = {
     menu: 'page menu (toolbar, context actions, filters, dropdowns)',
     navigation: 'main navigation (top bar, sidebar, breadcrumbs)',
 };
-const ResearcherBase = WithSections(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent))));
+const ResearcherBase = WithSections(WithPagination(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent)))));
 export class Researcher extends ResearcherBase {
     ACTION_TOOLS = ['click'];
     emoji = '🔍';
@@ -230,6 +231,9 @@ export class Researcher extends ResearcherBase {
                 await this.backfillCoordinates(result);
                 await this.backfillBrokenLocators(result);
             }
+            if (!interrupted()) {
+                await this.detectPagination(result);
+            }
             // Focused section: final fallback (vision-only — without a screenshot we don't infer focus)
             if (this.hasScreenshotToAnalyze && !hasFocusedSection(result.text)) {
                 const sections = parseResearchSections(result.text);
@@ -366,7 +370,7 @@ export class Researcher extends ResearcherBase {
 
       ${generalLocatorRuleText}
 
-      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl)}
+      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules', 'pagination'], currentUrl)}
 
       <section_identification>
       Identify page sections in this priority order:
@@ -439,6 +443,7 @@ export class Researcher extends ResearcherBase {
       - When a section contains a list of similar data items (records, entities, rows — content that varies by data, not by app UI), output it as a Data section with NO table.
       - Data section heading MUST be a level-2 heading (##) that starts exactly with "Data:" — for example: "## Data: Suites List". Do NOT use ### or add section numbers.
       - Data sections must NOT include a UI map table. Only include the container and a brief summary line.
+      - When the data list has controls that move between pages of the collection, add "> Pagination: controls" under its container.
       - Example data section:
 
       ## Data: Suites List

package/dist/src/ai/rules.js

@@ -177,6 +177,7 @@ export const capabilityGroundingRule = dedent `
   When a scenario depends on a named action, menu item, status, option, workflow, or feature,
   that capability must be visible or explicitly confirmed in the current research/page context
   for the same target entity type.
+  Ground on the scenario's outcome, not a planned step's control label — a missing label is not a missing capability.
 
   Do not transfer capabilities between similar entities, rows, lists, detail pages, or menus.
   Do not replace a requested action with a synonym or related action unless the UI explicitly
@@ -332,6 +333,22 @@ export const actionRule = dedent `
   For checkboxes, prefer I.checkOption/I.uncheckOption over I.click.
 
 
+  ### I.scrollTo
+
+  scrolls until the element is in view
+
+  I.scrollTo(<locator>)
+
+  Scrolls every scrollable ancestor of the target, so it reaches an element inside a container
+  that has its own scrollbar. I.scrollPageToBottom() moves only the page itself.
+
+  <example>
+    I.scrollTo('.rows > *:last-child');
+    I.scrollTo({ role: 'listitem', text: 'Last entry' });
+    I.scrollPageToBottom();
+  </example>
+
+
   ### I.fillField
 
   fills the field with the given value

package/dist/src/ai/scout.js

@@ -47,12 +47,18 @@ export class Scout {
                 maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
                 agentName: 'scout',
             });
+            const responseText = invokeResult?.response?.text;
+            if (responseText?.trim()) {
+                finishFromText(responseText);
+                stop();
+                return;
+            }
             if (!invokeResult?.toolExecutions?.length) {
-                finishFromText(invokeResult?.response?.text);
                 stop();
                 return;
             }
-            if (iteration >= MAX_ITERATIONS) {
+            if (iteration >= MAX_ITERATIONS - 1) {
+                conversation.addUserText('Exploration time is over. Report your findings now as your final message.');
                 const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
                 finishFromText(final?.response?.text);
                 stop();

package/dist/src/ai/tester.js

@@ -29,7 +29,7 @@ const SAMPLE_FILES = {
 };
 export class Tester extends TaskAgent {
     ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
-    DELEGATED_ACTION_TOOLS = ['interact'];
+    DELEGATED_ACTION_TOOLS = ['interact', 'visualClick'];
     SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
     emoji = '🧪';
     requestStore;

package/dist/src/ai/tools.js

@@ -311,6 +311,8 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
         - Working with iframes (switch context with I.switchTo)
         - Performing multiple form actions in a single batch
         - Complex interactions requiring sequential commands
+        - Reaching items further down a list (I.scrollTo)
+        - Reloading the page to prove a change outlived it (I.reloadPage)
 
         Example - filling a form with context (PREFERRED):
         I.fillField('Username', 'John', '.login-form')
@@ -323,7 +325,7 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
         I.selectOption({"role":"combobox","text":"Category"}, 'Technology')
 
         Do not submit form - use verify() first to check fields were filled correctly, then click() to submit.
-        Do not use: wait functions, amOnPage, reloadPage, saveScreenshot        
+        Do not use: wait functions, amOnPage, saveScreenshot        
       `,
             inputSchema: z.object({
                 codeBlock: z.string().describe('Valid CodeceptJS code starting with I. Can contain multiple commands separated by newlines.'),
@@ -365,10 +367,10 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                     }
                     if (!hasObservablePageChange(toolResult)) {
                         activeNote.commit(TestResult.FAILED);
-                        return failedToolResult('form', 'Form command executed, but no observable page or form-state change was captured.', {
+                        return failedToolResult('form', 'Command executed, but nothing on the page changed: no navigation, no ARIA change, no HTML change and no request.', {
                             ...toolResult,
                             code: codeBlock,
-                            suggestion: 'Treat the field/form action as not completed. Re-locate the editable control, check whether another UI layer is active, then retry and verify the field value before submitting.',
+                            suggestion: 'The command ran without reaching anything. Re-locate the target, check whether another UI layer is active, then retry. If the goal was to load more of a list, no change means the collection has ended.',
                         });
                     }
                     await commitNote(activeNote, TestResult.PASSED, toolResult, action);
@@ -1080,7 +1082,13 @@ export function successToolResult(action, data, source) {
     return result;
 }
 export function isMajorPageChange(pageDiff) {
-    return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
+    if (pageDiff.urlChanged === true)
+        return false;
+    if ((pageDiff.ariaChangeCount ?? 0) < LARGE_ARIA_CHANGE_THRESHOLD)
+        return false;
+    if (pageDiff.ariaRemoved === 0 && (pageDiff.ariaAdded ?? 0) > 0)
+        return false;
+    return true;
 }
 export function hasFailedRequest(pageDiff) {
     return (pageDiff.requests ?? []).some((request) => request.status >= 400);

package/dist/src/commands/options/ws-option.d.ts

@@ -3,5 +3,12 @@ import { BaseOption } from './base-option.js';
 export declare class WsOption extends BaseOption {
     flags: string;
     description: string;
+    /**
+     * An open socket holds the event loop, and `WebSocket` has no `unref` on
+     * either runtime — so a command that ends by returning rather than through
+     * `showStatsAndExit` would never exit once it is attached. The option that
+     * opened the connection is what closes it.
+     */
+    register(command: Command): void;
     apply(options: Record<string, any>, command: Command): void;
 }

package/dist/src/commands/options/ws-option.js

@@ -3,6 +3,20 @@ import { BaseOption } from './base-option.js';
 export class WsOption extends BaseOption {
     flags = '--ws <url>';
     description = 'Stream this run to a remote UI over WebSocket';
+    /**
+     * An open socket holds the event loop, and `WebSocket` has no `unref` on
+     * either runtime — so a command that ends by returning rather than through
+     * `showStatsAndExit` would never exit once it is attached. The option that
+     * opened the connection is what closes it.
+     */
+    register(command) {
+        super.register(command);
+        command.hook('postAction', async () => {
+            if (!remote.isAttached())
+                return;
+            await remote.close(0);
+        });
+    }
     apply(options, command) {
         const url = options.ws || process.env.EXPLORBOT_WS_URL;
         if (!url)

package/dist/src/config.d.ts

@@ -287,6 +287,7 @@ 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 resolveLangfuse(ai?: AIConfig): void;
 export declare function resolveOutputRoot(baseUrl?: string): string;
 export declare function resolveStateRoot(baseUrl: string, ephemeral?: boolean): string;
 export declare function materializeKnowledge(outputRoot: string): void;

package/dist/src/config.js

@@ -377,17 +377,7 @@ export class ConfigParser {
             config.playwright = config.playwright || { browser: 'chromium', url: '' };
             config.playwright.url = options.baseUrl;
         }
-        if (config.ai) {
-            const langfuse = config.ai.langfuse;
-            const publicKey = langfuse?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
-            const secretKey = langfuse?.secretKey || process.env.LANGFUSE_SECRET_KEY;
-            config.ai.langfuse = {
-                enabled: langfuse?.enabled ?? Boolean(publicKey && secretKey),
-                publicKey,
-                secretKey,
-                baseUrl: langfuse?.baseUrl || process.env.LANGFUSE_BASE_URL || process.env.LANGFUSE_HOST,
-            };
-        }
+        resolveLangfuse(config.ai);
         return config;
     }
     validateConfig(config) {
@@ -540,6 +530,19 @@ export async function resolveConfigModels(ai) {
             agent.model = await resolveModel(agent.model);
     }
 }
+export function resolveLangfuse(ai) {
+    if (!ai)
+        return;
+    const langfuse = ai.langfuse;
+    const publicKey = langfuse?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
+    const secretKey = langfuse?.secretKey || process.env.LANGFUSE_SECRET_KEY;
+    ai.langfuse = {
+        enabled: langfuse?.enabled ?? Boolean(publicKey && secretKey),
+        publicKey,
+        secretKey,
+        baseUrl: langfuse?.baseUrl || process.env.LANGFUSE_BASE_URL || process.env.LANGFUSE_HOST,
+    };
+}
 export function resolveOutputRoot(baseUrl) {
     if (cachedOutputRoot)
         return cachedOutputRoot;

package/dist/src/remote.d.ts

@@ -18,6 +18,7 @@ export declare class Remote implements LogDestination {
     asks: Map<string, (value: string | null) => void>;
     askCounter: number;
     lastActivity: string | null;
+    closing: Promise<void> | null;
     attach(url: string, command: string): void;
     isAttached(): boolean;
     send(type: string, data?: Record<string, unknown>): void;
@@ -30,6 +31,7 @@ export declare class Remote implements LogDestination {
      * back out of flattened text.
      */
     write(entry: TaggedLogEntry): void;
+    shutdown(exitCode: number): Promise<void>;
     connect(): void;
     reconnect(): void;
     flush(): Promise<void>;

package/dist/src/remote.js

@@ -26,6 +26,7 @@ export class Remote {
     asks = new Map();
     askCounter = 0;
     lastActivity = null;
+    closing = null;
     attach(url, command) {
         if (this.url)
             return;
@@ -68,23 +69,12 @@ export class Remote {
             });
         });
     }
-    async close(exitCode) {
+    close(exitCode) {
         if (!this.url)
-            return;
-        this.send('result', { ok: exitCode === 0, exitCode });
-        await this.flush();
-        this.url = null;
-        if (this.reconnectTimer)
-            clearTimeout(this.reconnectTimer);
-        // Whoever asks next has nobody to ask — leaving the callback installed would
-        // route them into a closed socket and park them until the ask times out.
-        executionController.clearInputCallback();
-        for (const resolve of this.asks.values())
-            resolve(null);
-        this.asks.clear();
-        this.queue = [];
-        this.socket?.close();
-        this.socket = null;
+            return Promise.resolve();
+        if (!this.closing)
+            this.closing = this.shutdown(exitCode);
+        return this.closing;
     }
     isEnabled() {
         return this.isAttached();
@@ -112,6 +102,23 @@ export class Remote {
             error: this.errorOf(entry.originalArgs),
         });
     }
+    async shutdown(exitCode) {
+        this.send('result', { ok: exitCode === 0, exitCode });
+        await this.flush();
+        this.url = null;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        // Whoever asks next has nobody to ask — leaving the callback installed would
+        // route them into a closed socket and park them until the ask times out.
+        executionController.clearInputCallback();
+        for (const resolve of this.asks.values())
+            resolve(null);
+        this.asks.clear();
+        this.queue = [];
+        this.socket?.close();
+        this.socket = null;
+        this.closing = null;
+    }
     connect() {
         if (!this.url)
             return;

package/dist/src/utils/aria.d.ts

@@ -16,4 +16,6 @@ export declare const LARGE_ARIA_CHANGE_THRESHOLD = 50;
 export interface AriaDiff {
     text: string | null;
     count: number;
+    added: number;
+    removed: number;
 }