explorbot 0.3.5 → 0.4.1

package/dist/src/ai/tester.d.ts

@@ -32,6 +32,8 @@ export declare class Tester extends TaskAgent implements Agent {
     seenUiMapUrls: Set<string>;
     lastAnalyzedStateHash: string | null;
     stalledIterations: number;
+    previousRegionPresent: boolean | null;
+    regionTransitioned: boolean;
     readonly MAX_STALLED_ITERATIONS = 3;
     skipResearch: (err: Error) => string;
     constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any);
@@ -96,5 +98,6 @@ interface TestSessionHandlers {
 }
 export interface TestOptions {
     startOnCurrentPage?: boolean;
+    deadline?: number;
 }
 export {};

package/dist/src/ai/tester.js

@@ -50,6 +50,8 @@ export class Tester extends TaskAgent {
     seenUiMapUrls = new Set();
     lastAnalyzedStateHash = null;
     stalledIterations = 0;
+    previousRegionPresent = null;
+    regionTransitioned = false;
     MAX_STALLED_ITERATIONS = 3;
     skipResearch = (err) => {
         if (err.name === 'AbortError')
@@ -95,6 +97,8 @@ export class Tester extends TaskAgent {
         this.seenUiMapUrls.clear();
         this.lastAnalyzedStateHash = null;
         this.stalledIterations = 0;
+        this.previousRegionPresent = null;
+        this.regionTransitioned = false;
         this.stateManager.clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
@@ -214,10 +218,17 @@ export class Tester extends TaskAgent {
         const codeceptjsTools = createCodeceptJSTools(this.toolDeps, task);
         let assertionPerformed = false;
         let extensions = 0;
+        let deadlineReached = false;
         let shouldContinue = true;
         while (shouldContinue) {
             shouldContinue = false;
             await loop(async ({ stop, pause, iteration, userInput }) => {
+                if (opts.deadline != null && Date.now() >= opts.deadline) {
+                    deadlineReached = true;
+                    task.addNote('Time budget reached. Stopped');
+                    stop();
+                    return;
+                }
                 debugLog('iteration', iteration);
                 if (!(await this.explorer.recover()).ok) {
                     task.addNote('Browser page is unavailable');
@@ -369,6 +380,8 @@ export class Tester extends TaskAgent {
             });
             if (task.hasFinished)
                 break;
+            if (deadlineReached)
+                break;
             if (!(await this.explorer.recover()).ok)
                 break;
             const finalState = this.getCurrentState();
@@ -403,6 +416,10 @@ export class Tester extends TaskAgent {
         };
     }
     shouldAnalyzeProgress(iteration, currentState) {
+        if (this.regionTransitioned) {
+            this.regionTransitioned = false;
+            return true;
+        }
         if (this.consecutiveFailures >= 3)
             return true;
         if (this.consecutiveEmptyResults >= 2)
@@ -468,6 +485,11 @@ export class Tester extends TaskAgent {
         const currentUrl = currentState.url;
         const currentStateHash = currentState.hash;
         const isNewUrl = this.previousUrl !== currentUrl;
+        const isNewState = !isNewUrl && this.previousStateHash !== null && this.previousStateHash !== currentStateHash;
+        if (this.previousRegionPresent !== null && this.previousRegionPresent !== currentState.overlay.present) {
+            this.regionTransitioned = true;
+        }
+        this.previousRegionPresent = currentState.overlay.present;
         this.previousUrl = currentUrl;
         this.previousStateHash = currentStateHash;
         let context = '';
@@ -491,13 +513,28 @@ export class Tester extends TaskAgent {
         }
         if (focusArea.detected) {
             const areaName = focusArea.name ? ` "${focusArea.name}"` : '';
+            let rootHint = '';
+            if (focusArea.root)
+                rootHint = `\nIts content lives inside \`${focusArea.root}\` — scope locators to it.`;
             context += dedent `
         <focus_scope>
-        A ${focusArea.type}${areaName} is currently open above the page.
+        A ${focusArea.type}${areaName} is currently open above the page.${rootHint}
         Scope all interactions to elements inside this ${focusArea.type}.
         Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the ${focusArea.type}.
         Use <page_aria> to confirm the element you target is actually inside the ${focusArea.type}.
         </focus_scope>
+      `;
+        }
+        if (!focusArea.detected && focusArea.present && isNewState) {
+            let rootHint = '';
+            if (focusArea.root)
+                rootHint = `\nIt lives inside \`${focusArea.root}\`.`;
+            context += dedent `
+        <area_of_interest>
+        A large new area "${focusArea.name || 'unnamed area'}" appeared on this page without navigation.${rootHint}
+        The scenario most likely continues inside this area — prefer its elements for your next actions.
+        The rest of the page (navigation, menus, filters) is still interactive and remains available.
+        </area_of_interest>
       `;
         }
         if (currentState.isInsideIframe) {
@@ -520,7 +557,7 @@ export class Tester extends TaskAgent {
             if (!alreadySeenUiMap) {
                 research = await this.researcher.research(currentState).catch(this.skipResearch);
             }
-            this.pageStateHash = currentStateHash;
+            this.pageStateHash = currentState.baseHash;
             this.pageActionResult = currentState;
             let uiMapSection = '';
             if (research) {
@@ -557,7 +594,7 @@ export class Tester extends TaskAgent {
       `;
             return context;
         }
-        if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
+        if (focusArea.present && focusArea.name && this.pageStateHash && this.pageActionResult) {
             const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash).catch(this.skipResearch);
             if (overlaySection) {
                 context += dedent `

package/dist/src/ai/tools.d.ts

@@ -69,4 +69,5 @@ export declare function withdrawVisionTools(tools: Record<string, any>): void;
 export declare function clickFailureSuggestion(attempts: Array<{
     error?: string;
 }>): string;
+export declare function formatMatchedElements(error: Error | null | undefined): Promise<string | null>;
 export {};

package/dist/src/ai/tools.js

@@ -7,8 +7,9 @@ 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 { cleanHtmlSnippet } from "../utils/html.js";
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage } from "../utils/strings.js";
+import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
@@ -1161,6 +1162,8 @@ export function clickFailureSuggestion(attempts) {
     return "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
 }
 const MAX_DISAMBIGUATE_ELEMENTS = 10;
+const MAX_DISAMBIGUATE_TEXT = 80;
+const MAX_DISAMBIGUATE_HTML = 300;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
 async function extractWebElements(error) {
     if (!error || error.name !== 'MultipleElementsFound')
@@ -1172,8 +1175,9 @@ async function extractWebElements(error) {
     for (let i = 0; i < Math.min(elements.length, MAX_DISAMBIGUATE_ELEMENTS); i++) {
         try {
             const xpath = await elements[i].toAbsoluteXPath();
-            const html = await elements[i].toSimplifiedHTML();
-            result.push({ xpath, html });
+            const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
+            const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
+            result.push({ xpath, html, text });
         }
         catch (e) {
             debugLog('Failed to get details for element %d: %s', i, e);
@@ -1181,17 +1185,20 @@ async function extractWebElements(error) {
     }
     return result.length > 0 ? result : null;
 }
-async function formatMatchedElements(error) {
+function formatElementList(details) {
+    return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+}
+export async function formatMatchedElements(error) {
     const details = await extractWebElements(error);
     if (!details)
         return 'Could not fetch element details. Repeat the action to get better info.';
-    return details.map((el, i) => `Element ${i + 1}\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+    return formatElementList(details);
 }
 async function disambiguateElements(error, explanation, provider) {
     const elementDetails = await extractWebElements(error);
     if (!elementDetails)
         return null;
-    const elementList = elementDetails.map((el, i) => `Element ${i + 1}:\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+    const elementList = formatElementList(elementDetails);
     const schema = z.object({
         position: z.number().nullable().describe('1-based position of the correct element, or null if none match'),
     });

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

@@ -33,8 +33,10 @@ export declare class RequestResult {
     get rawResponseBody(): string;
     set rawResponseBodyValue(value: string);
     get responseBody(): any;
+    get isWrite(): boolean;
     save(outputDir: string): void;
     static load(requestFile: string): RequestResult;
+    toEndpoint(): string;
     toSummary(): string;
     extractIdAndTitle(): {
         id?: string | number;

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

@@ -64,6 +64,9 @@ export class RequestResult {
             return raw;
         }
     }
+    get isWrite() {
+        return ['POST', 'PUT', 'PATCH', 'DELETE'].includes(this.method);
+    }
     save(outputDir) {
         const requestsDir = path.join(outputDir, 'requests');
         if (!existsSync(requestsDir)) {
@@ -137,14 +140,17 @@ export class RequestResult {
             statusText: meta.statusText || '',
             responseHeaders: meta.responseHeaders || {},
             timing: Number.parseInt(meta.timing) || 0,
-            timestamp: new Date(meta.timestamp || Date.now()),
+            timestamp: new Date(meta.timestamp || 0),
         });
         result.requestFile = requestFile;
         result.responseFile = responseFile;
         return result;
     }
+    toEndpoint() {
+        return `${this.method} ${this.path}`;
+    }
     toSummary() {
-        return `${this.method} ${this.path} → ${this.status} (${this.timing}ms)`;
+        return `${this.toEndpoint()} → ${this.status} (${this.timing}ms)`;
     }
     extractIdAndTitle() {
         const body = this.responseBody;

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

@@ -5,6 +5,7 @@ export declare class RequestStore {
     failedRequests: RequestResult[];
     onFailedListeners: Array<(r: RequestResult) => void>;
     outputDir: string;
+    sessionStartedAt: Date;
     constructor(outputDir: string);
     addCapturedRequest(result: RequestResult): void;
     addFailedRequest(result: RequestResult): void;
@@ -19,9 +20,9 @@ export declare class RequestStore {
     getRequestsByEndpoint(pathPrefix: string): RequestResult[];
     getRequestsByMethod(method: string): RequestResult[];
     getRequestsByStatus(status: number): RequestResult[];
-    toEndpointList(): string;
+    toEndpointList(scopePath?: string): string;
     extractAuthHeaders(): Record<string, string>;
-    findCapturedRequest(method: string, pathPrefix: string): RequestResult | undefined;
+    findCapturedRequest(method: string, searchPath: string): RequestResult | undefined;
     toLog(): string;
     loadFromDisk(): void;
     getWriteRequestsForScope(scopePath: string): RequestResult[];

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

@@ -1,13 +1,15 @@
 import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { isDynamicSegment } from "../utils/url-matcher.js";
 import { RequestResult } from "./request-result.js";
-const AUTH_HEADERS = ['authorization', 'cookie', 'x-api-key', 'x-csrf-token'];
+const AUTH_HEADERS = ['authorization', 'x-api-key', 'x-csrf-token'];
 export class RequestStore {
     capturedRequests = [];
     madeRequests = [];
     failedRequests = [];
     onFailedListeners = [];
     outputDir;
+    sessionStartedAt = new Date();
     constructor(outputDir) {
         this.outputDir = outputDir;
     }
@@ -61,12 +63,14 @@ export class RequestStore {
     getRequestsByStatus(status) {
         return this.madeRequests.filter((r) => r.status === status);
     }
-    toEndpointList() {
+    toEndpointList(scopePath) {
+        let requests = this.capturedRequests;
+        if (scopePath)
+            requests = this.getWriteRequestsForScope(scopePath);
         const seen = new Set();
         const lines = [];
-        for (const req of this.capturedRequests) {
-            const normalized = normalizePathPattern(req.path);
-            const key = `${req.method} ${normalized}`;
+        for (const req of requests) {
+            const key = `${req.method} ${normalizePathPattern(req.path)}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
@@ -76,21 +80,42 @@ export class RequestStore {
     }
     extractAuthHeaders() {
         const headers = {};
-        for (let i = this.capturedRequests.length - 1; i >= 0; i--) {
-            const req = this.capturedRequests[i];
+        const sessionCaptures = this.capturedRequests.filter((r) => r.timestamp >= this.sessionStartedAt).sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+        for (const req of sessionCaptures) {
             for (const [key, value] of Object.entries(req.requestHeaders)) {
                 if (AUTH_HEADERS.includes(key.toLowerCase()) && !headers[key]) {
                     headers[key] = value;
                 }
             }
-            if (AUTH_HEADERS.every((h) => Object.keys(headers).some((k) => k.toLowerCase() === h)))
-                break;
         }
         return headers;
     }
-    findCapturedRequest(method, pathPrefix) {
+    findCapturedRequest(method, searchPath) {
         const upper = method.toUpperCase();
-        return this.capturedRequests.find((r) => r.method === upper && r.path.startsWith(pathPrefix));
+        const search = normalizePathPattern(searchPath).split('/').filter(Boolean);
+        let best;
+        let bestScore = -1;
+        for (const req of this.capturedRequests) {
+            if (req.method !== upper)
+                continue;
+            const segments = normalizePathPattern(req.path).split('/').filter(Boolean);
+            if (segments.length < search.length)
+                continue;
+            if (!search.every((segment, i) => segment === segments[i]))
+                continue;
+            let score = 0;
+            if (segments.length === search.length)
+                score += 4;
+            if (req.status < 400)
+                score += 2;
+            if (score < bestScore)
+                continue;
+            if (score === bestScore && best && req.timestamp <= best.timestamp)
+                continue;
+            best = req;
+            bestScore = score;
+        }
+        return best;
     }
     toLog() {
         return this.madeRequests.map((r, i) => `${i + 1}. ${r.toSummary()} [${r.id}]`).join('\n');
@@ -100,7 +125,7 @@ export class RequestStore {
         if (!existsSync(requestsDir))
             return;
         const existingIds = new Set(this.capturedRequests.map((r) => r.id));
-        const files = readdirSync(requestsDir).filter((f) => f.endsWith('.request.yaml'));
+        const files = readdirSync(requestsDir).filter((f) => f.startsWith('xhr_') && f.endsWith('.request.yaml'));
         for (const file of files) {
             try {
                 const result = RequestResult.load(path.join(requestsDir, file));
@@ -115,7 +140,31 @@ export class RequestStore {
     }
     getWriteRequestsForScope(scopePath) {
         const writeMethods = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
-        return this.capturedRequests.filter((r) => writeMethods.has(r.method) && r.path.startsWith(scopePath));
+        const writes = this.capturedRequests.filter((r) => writeMethods.has(r.method));
+        const scopeSegments = scopePath.split('/').filter(Boolean);
+        if (scopeSegments.length === 0)
+            return writes;
+        let scoped = [];
+        let fewest = Number.POSITIVE_INFINITY;
+        let ambiguous = false;
+        for (const segment of scopeSegments) {
+            if (isDynamicSegment(segment))
+                continue;
+            const matches = writes.filter((r) => r.path.split('/').includes(segment));
+            if (matches.length === 0 || matches.length > fewest)
+                continue;
+            if (matches.length === fewest) {
+                if (!scoped.every((r, i) => r.id === matches[i].id))
+                    ambiguous = true;
+                continue;
+            }
+            scoped = matches;
+            fewest = matches.length;
+            ambiguous = false;
+        }
+        if (ambiguous)
+            return [];
+        return scoped;
     }
     clear() {
         this.capturedRequests = [];
@@ -124,5 +173,8 @@ export class RequestStore {
     }
 }
 function normalizePathPattern(urlPath) {
-    return urlPath.replace(/\/[0-9a-f]{24}\b/g, '/{id}').replace(/\/\d+\b/g, '/{id}');
+    return urlPath
+        .split('/')
+        .map((segment) => (segment && isDynamicSegment(segment) ? '{id}' : segment))
+        .join('/');
 }

package/dist/src/api/spec-reader.js

@@ -5,7 +5,7 @@ import { dereference } from '@scalar/openapi-parser';
 import { tag } from "../utils/logger.js";
 export function validateSpecs(specs) {
     if (!specs?.length) {
-        throw new Error('API spec is required. Set api.spec in your config file.');
+        throw new Error('API spec is required. Pass --spec, set EXPLORBOT_API_SPEC, or set api.spec in your config file.');
     }
 }
 export async function loadSpec(specPaths, outputDir) {

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

@@ -32,7 +32,7 @@ export class ConfigCommand extends BaseCommand {
         const dirs = {};
         if (options.root) {
             for (const [name, dir] of Object.entries({ output: 'output', ...config.dirs })) {
-                dirs[name] = path.join(options.root, dir);
+                dirs[name] = path.resolve(options.root, dir);
             }
         }
         const env = {};

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

@@ -21,7 +21,7 @@ export class DrillCommand extends BaseCommand {
         });
     }
     parseKnowledgeArg(args) {
-        const match = args.match(/--knowledge\s+(\S+)/);
+        const match = args.match(/--save-knowledge\s+(\S+)/);
         return match ? match[1] : undefined;
     }
     parseMaxArg(args) {

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

@@ -1,5 +1,7 @@
 import { type Plan, type Test } from '../test-plan.js';
 import { BaseCommand, type Suggestion } from './base-command.js';
+export declare const DEADLINE_RESERVE_MS: number;
+export declare const DEADLINE_TEST_ALLOWANCE_MS: number;
 export declare class ExploreCommand extends BaseCommand {
     name: string;
     description: string;
@@ -9,8 +11,11 @@ export declare class ExploreCommand extends BaseCommand {
     }[];
     suggestions: Suggestion[];
     maxTests?: number;
+    maxDurationMinutes?: number;
+    hardDeadlineAt?: number;
     dryRun: boolean;
     testsRun: number;
+    deadlineLogged: boolean;
     completedPlans: Plan[];
     failedSubPages: Set<string>;
     oldTestRefs: Set<Test>;
@@ -36,6 +41,7 @@ export declare class ExploreCommand extends BaseCommand {
     printResults(): void;
     printNextSteps(savedPlanPath?: string | null): void;
     isLimitReached(): boolean;
+    isDeadlineReached(): boolean;
     runPendingTests(): Promise<void>;
     runOneTest(test: Test): Promise<void>;
 }

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

@@ -13,11 +13,14 @@ import { safeFilename } from "../utils/strings.js";
 import { BaseCommand } from './base-command.js';
 const MAX_SUB_PAGE_ATTEMPTS = 30;
 const PRIORITY_ORDER = { critical: 0, important: 1, high: 2, normal: 3, low: 4 };
+export const DEADLINE_RESERVE_MS = 3 * 60_000;
+export const DEADLINE_TEST_ALLOWANCE_MS = 5 * 60_000;
 export class ExploreCommand extends BaseCommand {
     name = 'explore';
     description = 'Start web exploration';
     options = [
         { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
+        { flags: '--max-duration <minutes>', description: 'Wall-clock budget in minutes; wraps up the session before the limit is hit' },
         { flags: '--focus <feature>', description: 'Focus area for exploration' },
         { flags: '--configure <spec>', description: 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"' },
         { flags: '--dry-run', description: 'Mark picked tests as skipped without executing or generating new ones' },
@@ -28,8 +31,11 @@ export class ExploreCommand extends BaseCommand {
         { command: 'plan <feature>', hint: 'plan testing' },
     ];
     maxTests;
+    maxDurationMinutes;
+    hardDeadlineAt;
     dryRun = false;
     testsRun = 0;
+    deadlineLogged = false;
     completedPlans = [];
     failedSubPages = new Set();
     oldTestRefs = new Set();
@@ -43,6 +49,12 @@ export class ExploreCommand extends BaseCommand {
         if (opts.maxTests) {
             this.maxTests = Number.parseInt(opts.maxTests, 10);
         }
+        if (opts.maxDuration) {
+            this.maxDurationMinutes = Number.parseInt(opts.maxDuration, 10);
+        }
+        if (this.hardDeadlineAt == null && this.maxDurationMinutes != null) {
+            this.hardDeadlineAt = Date.now() + this.maxDurationMinutes * 60_000 - DEADLINE_RESERVE_MS;
+        }
         const feature = opts.focus || remaining.join(' ') || undefined;
         const cfg = this.parseConfigure(opts.configure);
         if (cfg.priorities)
@@ -244,9 +256,15 @@ export class ExploreCommand extends BaseCommand {
             tag('info').log(`Exploring sub-page: ${pick.url} (${pick.reason})`);
             try {
                 await this.explorBot.visit(pick.url);
+                const errorPage = getStateErrorPageError(this.explorBot.stateManager().getCurrentState());
+                if (errorPage) {
+                    tag('warning').log(`Skipping sub-page: ${errorPage.message}`);
+                    this.failedSubPages.add(normalizeUrl(pick.url));
+                    continue;
+                }
                 await this.runAllStyles(pick.url, undefined, mainPlan, this.completedPlans, styles);
                 const subPlan = this.explorBot.getCurrentPlan();
-                if (subPlan && !this.completedPlans.includes(subPlan)) {
+                if (subPlan?.tests.length && !this.completedPlans.includes(subPlan)) {
                     this.completedPlans.push(subPlan);
                 }
                 knownUrls.add(normalizeUrl(pick.url));
@@ -285,6 +303,11 @@ export class ExploreCommand extends BaseCommand {
             if (this.dryRun)
                 opts.noSave = true;
             await this.planWithRetry(feature, opts, pageUrl);
+            const plan = this.explorBot.getCurrentPlan();
+            if (plan && plan.tests.length === 0) {
+                tag('warning').log('Nothing to test on this page, moving on');
+                return;
+            }
             await this.runPendingTests();
             this.rememberCurrentPlan();
             fresh = false;
@@ -515,7 +538,20 @@ export class ExploreCommand extends BaseCommand {
         printNextSteps(sections);
     }
     isLimitReached() {
-        return this.maxTests != null && this.testsRun >= this.maxTests;
+        if (this.maxTests != null && this.testsRun >= this.maxTests)
+            return true;
+        return this.isDeadlineReached();
+    }
+    isDeadlineReached() {
+        if (this.hardDeadlineAt == null)
+            return false;
+        if (Date.now() < this.hardDeadlineAt - DEADLINE_TEST_ALLOWANCE_MS)
+            return false;
+        if (!this.deadlineLogged) {
+            this.deadlineLogged = true;
+            tag('info').log(`Time budget reached after ${this.testsRun} test(s): stopping new work and finishing the session`);
+        }
+        return true;
     }
     async runPendingTests() {
         const plan = this.explorBot.getCurrentPlan();
@@ -539,7 +575,7 @@ export class ExploreCommand extends BaseCommand {
             test.finish(TestResult.SKIPPED);
         }
         else {
-            await this.explorBot.agentTester().test(test);
+            await this.explorBot.agentTester().test(test, { deadline: this.hardDeadlineAt });
         }
         this.testsRun++;
     }

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

@@ -4,7 +4,7 @@ import { Stats } from '../stats.js';
 import { tag } from '../utils/logger.js';
 import { loop } from '../utils/loop.js';
 import { BaseCommand } from './base-command.js';
-import { ExploreCommand } from './explore-command.js';
+import { DEADLINE_RESERVE_MS, DEADLINE_TEST_ALLOWANCE_MS, ExploreCommand } from './explore-command.js';
 export class FreesailCommand extends BaseCommand {
     name = 'freesail';
     description = 'Continuously explore and navigate to new pages autonomously';
@@ -15,6 +15,7 @@ export class FreesailCommand extends BaseCommand {
         { flags: '--shallow', description: 'Use shallow navigation strategy' },
         { flags: '--scope <url>', description: 'Limit navigation to URLs starting with this prefix' },
         { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
+        { flags: '--max-duration <number>', description: 'Wall-clock budget in minutes for the whole run' },
     ];
     async execute(args) {
         Stats.mode = 'freesail';
@@ -26,11 +27,17 @@ export class FreesailCommand extends BaseCommand {
             strategy = 'shallow';
         const scope = opts.scope;
         const maxTests = opts.maxTests ? Number.parseInt(opts.maxTests, 10) : undefined;
+        const maxDuration = opts.maxDuration ? Number.parseInt(opts.maxDuration, 10) : undefined;
+        let hardDeadlineAt;
+        if (maxDuration != null)
+            hardDeadlineAt = Date.now() + maxDuration * 60_000 - DEADLINE_RESERVE_MS;
         await this.explorBot.visitInitialState();
         let testsRun = 0;
         await loop(async (ctx) => {
             if (maxTests != null && testsRun >= maxTests)
                 ctx.stop();
+            if (hardDeadlineAt != null && Date.now() >= hardDeadlineAt - DEADLINE_TEST_ALLOWANCE_MS)
+                ctx.stop();
             const stateManager = this.explorBot.stateManager();
             const state = stateManager.getCurrentState();
             if (state && !Researcher.getCachedResearch(state)) {
@@ -44,6 +51,8 @@ export class FreesailCommand extends BaseCommand {
                 const exploreCmd = new ExploreCommand(this.explorBot);
                 if (maxTests != null)
                     exploreCmd.maxTests = maxTests - testsRun;
+                if (hardDeadlineAt != null)
+                    exploreCmd.hardDeadlineAt = hardDeadlineAt;
                 await exploreCmd.execute('');
                 const plan = this.explorBot.getCurrentPlan();
                 if (plan)

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

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+export declare abstract class BaseOption {
+    abstract flags: string;
+    abstract description: string;
+    collect?: (value: string, previous: any) => any;
+    register(program: Command): void;
+    abstract apply(options: Record<string, any>, command: Command): void;
+}

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

@@ -0,0 +1,12 @@
+export class BaseOption {
+    collect;
+    register(program) {
+        if (this.collect)
+            program.option(this.flags, this.description, this.collect);
+        if (!this.collect)
+            program.option(this.flags, this.description);
+        program.hook('preAction', (_thisCommand, actionCommand) => {
+            this.apply(actionCommand.optsWithGlobals(), actionCommand);
+        });
+    }
+}

package/dist/src/commands/options/index.d.ts

@@ -0,0 +1,5 @@
+import { KnowledgeOption } from './knowledge-option.js';
+import { WsOption } from './ws-option.js';
+export { BaseOption } from './base-option.js';
+export declare const knowledgeOption: KnowledgeOption;
+export declare const wsOption: WsOption;

package/dist/src/commands/options/index.js

@@ -0,0 +1,5 @@
+import { KnowledgeOption } from './knowledge-option.js';
+import { WsOption } from './ws-option.js';
+export { BaseOption } from './base-option.js';
+export const knowledgeOption = new KnowledgeOption();
+export const wsOption = new WsOption();

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

@@ -0,0 +1,7 @@
+import { BaseOption } from './base-option.js';
+export declare class KnowledgeOption extends BaseOption {
+    flags: string;
+    description: string;
+    collect: (value: string, previous?: string[]) => string[];
+    apply(options: Record<string, any>): void;
+}

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

@@ -0,0 +1,12 @@
+import { KnowledgeTracker } from '../../knowledge-tracker.js';
+import { BaseOption } from './base-option.js';
+export class KnowledgeOption extends BaseOption {
+    flags = '--knowledge <text>';
+    description = 'Knowledge for this run only, not saved to disk. Markdown text; add url: or endpoint: frontmatter to scope it, otherwise it applies everywhere. Repeatable';
+    collect = (value, previous = []) => [...previous, value];
+    apply(options) {
+        for (const text of options.knowledge || []) {
+            KnowledgeTracker.appendSessionKnowledge(text);
+        }
+    }
+}