explorbot 0.4.9 → 0.5.0

package/README.md

@@ -1,5 +1,8 @@
 <p align="center">
-  <img src="assets/explorbot-logo.png" alt="Explorbot" width="560">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logos/explorbot/explorbot-for-dark-theme.svg">
+    <img src="assets/logos/explorbot/explorbot-for-light-theme.svg" alt="Explorbot" width="560">
+  </picture>
 </p>
 
 <p align="center"><b>The vibe-testing agent for web applications.</b></p>

package/bin/mdq.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { runMdq } from '../src/utils/mdq/cli.ts';
+
+async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) return '';
+  process.stdin.setEncoding('utf8');
+  let text = '';
+  for await (const chunk of process.stdin) text += chunk;
+  return text;
+}
+
+const result = await runMdq(process.argv.slice(2), readStdin);
+if (result.output) {
+  let text = result.output;
+  if (!text.endsWith('\n')) text = `${text}\n`;
+  process.stdout.write(text);
+}
+process.exit(result.code);

package/boat/api-tester/src/ai/chief.ts

@@ -8,6 +8,7 @@ import { Observability } from '../../../../src/observability.ts';
 import { Plan, Test } from '../../../../src/test-plan.ts';
 import { createDebug, tag } from '../../../../src/utils/logger.ts';
 import { RulesLoader } from '../../../../src/utils/rules-loader.ts';
+import { isSecretName, registerSecret } from '../../../../src/utils/secrets.ts';
 import type { ApiClient } from '../api-client.ts';
 import type { ApibotConfig } from '../config.ts';
 import { getActiveStyle, getStyles } from './chief/styles.ts';
@@ -28,6 +29,21 @@ const ApiTasksSchema = z.object({
     .describe('List of testing scenarios'),
 });
 
+const NamedValueSchema = z.object({ name: z.string(), value: z.string() });
+
+const RequestDefaultsSchema = z.object({
+  files: z
+    .array(
+      z.object({
+        file: z.number().describe('Number of the knowledge file the values come from'),
+        headers: z.array(NamedValueSchema).describe('Headers to send, each value exactly as it goes on the wire'),
+        query: z.array(NamedValueSchema).describe('Query parameters to send'),
+        body: z.array(NamedValueSchema).describe('Fields a request body must contain, each value as a JSON literal'),
+      })
+    )
+    .describe('One entry per knowledge file that names values to send with requests'),
+});
+
 const ChiefBase = WithSessionDedup(Object as unknown as new (...args: any[]) => object);
 
 export class Chief extends ChiefBase {
@@ -37,6 +53,7 @@ export class Chief extends ChiefBase {
   private knowledgeTracker?: KnowledgeTracker;
   currentPlan: Plan | null = null;
   private lastStyleName = '';
+  private readKnowledgeFiles = new Set<string>();
 
   MIN_TASKS = 3;
   MAX_TASKS = 10;
@@ -56,6 +73,7 @@ export class Chief extends ChiefBase {
     debugLog('Sending planning prompt to AI provider');
 
     await Observability.run(`chief: ${endpoint}`, { tags: ['chief'], sessionId: endpoint }, async () => {
+      await this.prepareRequestDefaults(endpoint);
       const sampleData = await this.collectSampleData(endpoint);
       const conversation = this.buildConversation(endpoint, opts?.style, sampleData);
 
@@ -127,6 +145,52 @@ export class Chief extends ChiefBase {
     }
   }
 
+  private async prepareRequestDefaults(endpoint: string): Promise<void> {
+    if (!this.apiClient) return;
+    const files = (this.knowledgeTracker?.getEndpointKnowledge(endpoint) || []).filter((knowledge) => !this.readKnowledgeFiles.has(knowledge.filePath));
+    if (!files.length) return;
+
+    const knowledgeFiles = files.map((knowledge, index) => `<file number="${index + 1}" endpoint="${knowledge.endpoint}">\n${knowledge.content}\n</file>`).join('\n\n');
+    const prompt = dedent`
+      <task>
+      Extract the values these knowledge files say must be sent with API requests:
+      - headers: authentication, API keys and other headers, written exactly as sent (include the auth scheme when one is named)
+      - query: query parameters requests need
+      - body: fields request bodies must contain, each value written as a JSON literal
+      Copy values exactly as written. Never invent a value. Skip facts that are not about what to send.
+      </task>
+
+      <knowledge_files>
+      ${knowledgeFiles}
+      </knowledge_files>
+    `;
+
+    const result = await this.provider.generateObject([{ role: 'user', content: prompt }], RequestDefaultsSchema, this.provider.getModelForAgent('chief'), { agentName: 'chief' }).catch((error: Error) => {
+      tag('warning').log(`Could not read request defaults from knowledge: ${error.message}`);
+      return null;
+    });
+    if (!result) return;
+    for (const knowledge of files) this.readKnowledgeFiles.add(knowledge.filePath);
+
+    const entries: z.infer<typeof RequestDefaultsSchema>['files'] = result.object?.files || [];
+    for (const entry of entries) {
+      const knowledge = files[entry.file - 1];
+      if (!knowledge?.endpoint) continue;
+
+      const headers = Object.fromEntries(entry.headers.map(({ name, value }) => [name, value]));
+      const query = Object.fromEntries(entry.query.map(({ name, value }) => [name, value]));
+      const body = Object.fromEntries(entry.body.map(({ name, value }) => [name, parseJsonLiteral(value)]));
+      const sent = Object.entries({ headers, query, body }).filter(([, values]) => Object.keys(values).length);
+      if (!sent.length) continue;
+
+      for (const [name, value] of sent.flatMap(([, values]) => Object.entries(values))) {
+        if (isSecretName(name)) registerSecret(String(value));
+      }
+      this.apiClient.addRequestDefaults({ pattern: knowledge.endpoint, headers, query, body });
+      tag('info').log(`Request defaults from knowledge for ${knowledge.endpoint}: ${sent.map(([kind, values]) => `${kind} ${Object.keys(values).join(', ')}`).join('; ')}`);
+    }
+  }
+
   private async collectSampleData(endpoint: string): Promise<string> {
     if (!this.apiClient) return '';
 
@@ -341,3 +405,11 @@ export class Chief extends ChiefBase {
     `;
   }
 }
+
+function parseJsonLiteral(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}

package/boat/api-tester/src/api-client.ts

@@ -1,9 +1,14 @@
 import { ApiClient as BaseApiClient } from '../../../src/api/api-client.ts';
+import type { RequestResult } from '../../../src/api/request-result.ts';
+import { extractStatePath, matchesUrl } from '../../../src/utils/url-matcher.ts';
 import type { HookFn } from './config.ts';
 
+const BODY_METHODS = ['POST', 'PUT', 'PATCH'];
+
 export class ApiClient extends BaseApiClient {
   private bootstrapHook?: HookFn;
   private teardownHook?: HookFn;
+  private requestDefaults: RequestDefaults[] = [];
 
   constructor(baseEndpoint: string, defaultHeaders: Record<string, string> = {}, hooks?: { bootstrap?: HookFn; teardown?: HookFn }) {
     super(baseEndpoint, defaultHeaders);
@@ -25,4 +30,36 @@ export class ApiClient extends BaseApiClient {
     const ctx = { headers: this.getHeaders(), baseEndpoint: this.getBaseEndpoint() };
     await this.teardownHook(ctx);
   }
+
+  addRequestDefaults(defaults: RequestDefaults): void {
+    this.requestDefaults.push(defaults);
+  }
+
+  override async request(opts: Parameters<BaseApiClient['request']>[0]): Promise<RequestResult> {
+    const path = extractStatePath(opts.path);
+    const matching = this.requestDefaults.filter((defaults) => matchesUrl(defaults.pattern, path));
+    if (!matching.length) return super.request(opts);
+
+    const knowledgeHeaders: Record<string, string> = {};
+    for (const defaults of matching) {
+      for (const [name, value] of Object.entries(defaults.headers)) knowledgeHeaders[name.toLowerCase()] = value;
+    }
+    for (const name of Object.keys({ ...this.getHeaders(), ...opts.headers })) delete knowledgeHeaders[name.toLowerCase()];
+
+    const headers = { ...knowledgeHeaders, ...this.getHeaders(), ...opts.headers };
+    const queryParams = Object.assign({}, ...matching.map((defaults) => defaults.query), opts.queryParams);
+    let body = opts.body;
+    if (BODY_METHODS.includes(opts.method.toUpperCase()) && body && typeof body === 'object' && !Array.isArray(body)) {
+      body = Object.assign({}, ...matching.map((defaults) => defaults.body), body);
+    }
+
+    return super.request({ ...opts, headers, queryParams, body });
+  }
+}
+
+export interface RequestDefaults {
+  pattern: string;
+  headers: Record<string, string>;
+  query: Record<string, string>;
+  body: Record<string, unknown>;
 }

package/boat/prima/src/prima.ts

@@ -8,6 +8,7 @@ import * as playwright from 'playwright';
 import type { Browser } from 'playwright';
 import { z } from 'zod';
 import { ActionResult } from '../../../src/action-result.ts';
+import { JUDGE_PAGE_CAP, UNDECIDED } from '../../../src/ai/judge.ts';
 import { getPreviousResearch } from '../../../src/ai/researcher/cache.ts';
 import { actionRule, locatorRule } from '../../../src/ai/rules.ts';
 import { createAgentTools, createCodeceptJSTools, createRefTools } from '../../../src/ai/tools.ts';
@@ -20,7 +21,7 @@ import { Reporter } from '../../../src/reporter.ts';
 import type { WebPageState } from '../../../src/state-manager.ts';
 import { Stats } from '../../../src/stats.ts';
 import { Task, Test, TestResult } from '../../../src/test-plan.ts';
-import { ariaRefSnapshot } from '../../../src/utils/aria-ref.ts';
+import { ariaRefSelector, ariaRefSnapshot, describeRef, parseAriaRefs, refIsGone } from '../../../src/utils/aria-ref.ts';
 import { compactAriaSnapshot } from '../../../src/utils/aria.ts';
 import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
 import { pluralize } from '../../../src/utils/logger.ts';
@@ -57,7 +58,8 @@ function dropVolatileColumns(markdown: string): string {
       const divider = `|${columns.map(() => '------').join('|')}|`;
       const body = rows.map((row) => `| ${columns.map((name) => row[name] || '-').join(' | ')} |`);
       return [header, divider, ...body, ''].join('\n');
-    });
+    })
+    .toString();
 }
 
 function cap(text: string, max: number): string {
@@ -446,6 +448,12 @@ export class Prima {
     }
 
     const previousState = this.bot.stateManager().getCurrentState();
+
+    if (!isUrl) {
+      const judged = await this.judgedGo(target, previousState);
+      if (judged) return judged;
+    }
+
     let navigationError: unknown = null;
 
     try {
@@ -925,6 +933,37 @@ export class Prima {
     return snapshot || result.ariaSnapshot;
   }
 
+  private async judgedGo(target: string, previousState: WebPageState | null): Promise<EnvelopeData | null> {
+    if (!previousState) return null;
+    const judge = this.bot.judge?.();
+    if (!judge) return null;
+
+    const refs = parseAriaRefs((await this.refAriaSnapshot(ActionResult.fromState(previousState))) || '').filter((entry) => entry.name);
+    const labels = refs.map((entry) => `${entry.role} named "${entry.name}"`);
+    const pick = await judge.decide(`Which listed control leads to: ${target}`, [...labels, UNDECIDED], { target });
+    if (!pick.value) return null;
+
+    const ref = refs[labels.indexOf(pick.value)].ref;
+    const explorer = this.bot.getExplorer();
+    if (await refIsGone(explorer, ref)) return null;
+
+    const named = await describeRef(explorer, ref);
+    const run = `I.usePlaywrightTo(${JSON.stringify(`go to ${target}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
+    if (!(await explorer.action().attempt(run, `go ${target}`))) return null;
+
+    const newState = this.bot.stateManager().getCurrentState();
+    if (!newState) return null;
+    if (newState.hash === previousState.hash && newState.url === previousState.url) return null;
+
+    const page = ((await this.refAriaSnapshot(ActionResult.fromState(newState))) || '').slice(0, JUDGE_PAGE_CAP);
+    const arrived = await judge.decide(`The page now shows: ${target}`, null, { target, page });
+    if (arrived.rejected) return null;
+
+    let code = run;
+    if (named) code = `I.click(${JSON.stringify(named)})`;
+    return this.successEnvelope(`go ${target}`, [code], await this.capturedResult(newState), previousState);
+  }
+
   private executedCodes(code: unknown): string[] {
     if (typeof code !== 'string') return [];
     return code

package/dist/bin/mdq.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { runMdq } from "../src/utils/mdq/cli.js";
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    process.stdin.setEncoding('utf8');
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += chunk;
+    return text;
+}
+const result = await runMdq(process.argv.slice(2), readStdin);
+if (result.output) {
+    let text = result.output;
+    if (!text.endsWith('\n'))
+        text = `${text}\n`;
+    process.stdout.write(text);
+}
+process.exit(result.code);

package/dist/boat/api-tester/src/ai/chief.js

@@ -6,6 +6,7 @@ import { Observability } from "../../../../src/observability.js";
 import { Plan, Test } from "../../../../src/test-plan.js";
 import { createDebug, tag } from "../../../../src/utils/logger.js";
 import { RulesLoader } from "../../../../src/utils/rules-loader.js";
+import { isSecretName, registerSecret } from "../../../../src/utils/secrets.js";
 import { getActiveStyle, getStyles } from "./chief/styles.js";
 const debugLog = createDebug('explorbot:chief');
 const ApiTasksSchema = z.object({
@@ -19,6 +20,17 @@ const ApiTasksSchema = z.object({
     }))
         .describe('List of testing scenarios'),
 });
+const NamedValueSchema = z.object({ name: z.string(), value: z.string() });
+const RequestDefaultsSchema = z.object({
+    files: z
+        .array(z.object({
+        file: z.number().describe('Number of the knowledge file the values come from'),
+        headers: z.array(NamedValueSchema).describe('Headers to send, each value exactly as it goes on the wire'),
+        query: z.array(NamedValueSchema).describe('Query parameters to send'),
+        body: z.array(NamedValueSchema).describe('Fields a request body must contain, each value as a JSON literal'),
+    }))
+        .describe('One entry per knowledge file that names values to send with requests'),
+});
 const ChiefBase = WithSessionDedup(Object);
 export class Chief extends ChiefBase {
     provider;
@@ -27,6 +39,7 @@ export class Chief extends ChiefBase {
     knowledgeTracker;
     currentPlan = null;
     lastStyleName = '';
+    readKnowledgeFiles = new Set();
     MIN_TASKS = 3;
     MAX_TASKS = 10;
     constructor(provider, config, apiClient, knowledgeTracker) {
@@ -42,6 +55,7 @@ export class Chief extends ChiefBase {
             tag('info').log(`Planning style: ${opts.style}`);
         debugLog('Sending planning prompt to AI provider');
         await Observability.run(`chief: ${endpoint}`, { tags: ['chief'], sessionId: endpoint }, async () => {
+            await this.prepareRequestDefaults(endpoint);
             const sampleData = await this.collectSampleData(endpoint);
             const conversation = this.buildConversation(endpoint, opts?.style, sampleData);
             const knowledge = this.knowledgeTracker?.renderEndpointKnowledge(endpoint);
@@ -105,6 +119,53 @@ export class Chief extends ChiefBase {
             existing.add(test.scenario.toLowerCase());
         }
     }
+    async prepareRequestDefaults(endpoint) {
+        if (!this.apiClient)
+            return;
+        const files = (this.knowledgeTracker?.getEndpointKnowledge(endpoint) || []).filter((knowledge) => !this.readKnowledgeFiles.has(knowledge.filePath));
+        if (!files.length)
+            return;
+        const knowledgeFiles = files.map((knowledge, index) => `<file number="${index + 1}" endpoint="${knowledge.endpoint}">\n${knowledge.content}\n</file>`).join('\n\n');
+        const prompt = dedent `
+      <task>
+      Extract the values these knowledge files say must be sent with API requests:
+      - headers: authentication, API keys and other headers, written exactly as sent (include the auth scheme when one is named)
+      - query: query parameters requests need
+      - body: fields request bodies must contain, each value written as a JSON literal
+      Copy values exactly as written. Never invent a value. Skip facts that are not about what to send.
+      </task>
+
+      <knowledge_files>
+      ${knowledgeFiles}
+      </knowledge_files>
+    `;
+        const result = await this.provider.generateObject([{ role: 'user', content: prompt }], RequestDefaultsSchema, this.provider.getModelForAgent('chief'), { agentName: 'chief' }).catch((error) => {
+            tag('warning').log(`Could not read request defaults from knowledge: ${error.message}`);
+            return null;
+        });
+        if (!result)
+            return;
+        for (const knowledge of files)
+            this.readKnowledgeFiles.add(knowledge.filePath);
+        const entries = result.object?.files || [];
+        for (const entry of entries) {
+            const knowledge = files[entry.file - 1];
+            if (!knowledge?.endpoint)
+                continue;
+            const headers = Object.fromEntries(entry.headers.map(({ name, value }) => [name, value]));
+            const query = Object.fromEntries(entry.query.map(({ name, value }) => [name, value]));
+            const body = Object.fromEntries(entry.body.map(({ name, value }) => [name, parseJsonLiteral(value)]));
+            const sent = Object.entries({ headers, query, body }).filter(([, values]) => Object.keys(values).length);
+            if (!sent.length)
+                continue;
+            for (const [name, value] of sent.flatMap(([, values]) => Object.entries(values))) {
+                if (isSecretName(name))
+                    registerSecret(String(value));
+            }
+            this.apiClient.addRequestDefaults({ pattern: knowledge.endpoint, headers, query, body });
+            tag('info').log(`Request defaults from knowledge for ${knowledge.endpoint}: ${sent.map(([kind, values]) => `${kind} ${Object.keys(values).join(', ')}`).join('; ')}`);
+        }
+    }
     async collectSampleData(endpoint) {
         if (!this.apiClient)
             return '';
@@ -305,3 +366,11 @@ export class Chief extends ChiefBase {
     `;
     }
 }
+function parseJsonLiteral(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}

package/dist/boat/api-tester/src/api-client.js

@@ -1,7 +1,10 @@
 import { ApiClient as BaseApiClient } from "../../../src/api/api-client.js";
+import { extractStatePath, matchesUrl } from "../../../src/utils/url-matcher.js";
+const BODY_METHODS = ['POST', 'PUT', 'PATCH'];
 export class ApiClient extends BaseApiClient {
     bootstrapHook;
     teardownHook;
+    requestDefaults = [];
     constructor(baseEndpoint, defaultHeaders = {}, hooks) {
         super(baseEndpoint, defaultHeaders);
         this.bootstrapHook = hooks?.bootstrap;
@@ -22,4 +25,27 @@ export class ApiClient extends BaseApiClient {
         const ctx = { headers: this.getHeaders(), baseEndpoint: this.getBaseEndpoint() };
         await this.teardownHook(ctx);
     }
+    addRequestDefaults(defaults) {
+        this.requestDefaults.push(defaults);
+    }
+    async request(opts) {
+        const path = extractStatePath(opts.path);
+        const matching = this.requestDefaults.filter((defaults) => matchesUrl(defaults.pattern, path));
+        if (!matching.length)
+            return super.request(opts);
+        const knowledgeHeaders = {};
+        for (const defaults of matching) {
+            for (const [name, value] of Object.entries(defaults.headers))
+                knowledgeHeaders[name.toLowerCase()] = value;
+        }
+        for (const name of Object.keys({ ...this.getHeaders(), ...opts.headers }))
+            delete knowledgeHeaders[name.toLowerCase()];
+        const headers = { ...knowledgeHeaders, ...this.getHeaders(), ...opts.headers };
+        const queryParams = Object.assign({}, ...matching.map((defaults) => defaults.query), opts.queryParams);
+        let body = opts.body;
+        if (BODY_METHODS.includes(opts.method.toUpperCase()) && body && typeof body === 'object' && !Array.isArray(body)) {
+            body = Object.assign({}, ...matching.map((defaults) => defaults.body), body);
+        }
+        return super.request({ ...opts, headers, queryParams, body });
+    }
 }

package/dist/boat/prima/src/prima.js

@@ -7,6 +7,7 @@ import dedent from 'dedent';
 import * as playwright from 'playwright';
 import { z } from 'zod';
 import { ActionResult } from "../../../src/action-result.js";
+import { JUDGE_PAGE_CAP, UNDECIDED } from "../../../src/ai/judge.js";
 import { getPreviousResearch } from "../../../src/ai/researcher/cache.js";
 import { actionRule, locatorRule } from "../../../src/ai/rules.js";
 import { createAgentTools, createCodeceptJSTools, createRefTools } from "../../../src/ai/tools.js";
@@ -18,7 +19,7 @@ import { findSiteWith, listSites } from "../../../src/global-config.js";
 import { Reporter } from "../../../src/reporter.js";
 import { Stats } from "../../../src/stats.js";
 import { Task, Test, TestResult } from "../../../src/test-plan.js";
-import { ariaRefSnapshot } from "../../../src/utils/aria-ref.js";
+import { ariaRefSelector, ariaRefSnapshot, describeRef, parseAriaRefs, refIsGone } from "../../../src/utils/aria-ref.js";
 import { compactAriaSnapshot } from "../../../src/utils/aria.js";
 import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { pluralize } from "../../../src/utils/logger.js";
@@ -52,7 +53,8 @@ function dropVolatileColumns(markdown) {
         const divider = `|${columns.map(() => '------').join('|')}|`;
         const body = rows.map((row) => `| ${columns.map((name) => row[name] || '-').join(' | ')} |`);
         return [header, divider, ...body, ''].join('\n');
-    });
+    })
+        .toString();
 }
 function cap(text, max) {
     if (text.length <= max)
@@ -405,6 +407,11 @@ export class Prima {
                 return guard;
         }
         const previousState = this.bot.stateManager().getCurrentState();
+        if (!isUrl) {
+            const judged = await this.judgedGo(target, previousState);
+            if (judged)
+                return judged;
+        }
         let navigationError = null;
         try {
             await this.bot.agentNavigator().visit(target);
@@ -868,6 +875,39 @@ export class Prima {
         const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.(ariaRefSnapshot)).catch(() => null);
         return snapshot || result.ariaSnapshot;
     }
+    async judgedGo(target, previousState) {
+        if (!previousState)
+            return null;
+        const judge = this.bot.judge?.();
+        if (!judge)
+            return null;
+        const refs = parseAriaRefs((await this.refAriaSnapshot(ActionResult.fromState(previousState))) || '').filter((entry) => entry.name);
+        const labels = refs.map((entry) => `${entry.role} named "${entry.name}"`);
+        const pick = await judge.decide(`Which listed control leads to: ${target}`, [...labels, UNDECIDED], { target });
+        if (!pick.value)
+            return null;
+        const ref = refs[labels.indexOf(pick.value)].ref;
+        const explorer = this.bot.getExplorer();
+        if (await refIsGone(explorer, ref))
+            return null;
+        const named = await describeRef(explorer, ref);
+        const run = `I.usePlaywrightTo(${JSON.stringify(`go to ${target}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
+        if (!(await explorer.action().attempt(run, `go ${target}`)))
+            return null;
+        const newState = this.bot.stateManager().getCurrentState();
+        if (!newState)
+            return null;
+        if (newState.hash === previousState.hash && newState.url === previousState.url)
+            return null;
+        const page = ((await this.refAriaSnapshot(ActionResult.fromState(newState))) || '').slice(0, JUDGE_PAGE_CAP);
+        const arrived = await judge.decide(`The page now shows: ${target}`, null, { target, page });
+        if (arrived.rejected)
+            return null;
+        let code = run;
+        if (named)
+            code = `I.click(${JSON.stringify(named)})`;
+        return this.successEnvelope(`go ${target}`, [code], await this.capturedResult(newState), previousState);
+    }
     executedCodes(code) {
         if (typeof code !== 'string')
             return [];

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -60,7 +60,8 @@
     "check": "biome check .",
     "check:fix": "biome check --write .",
     "langfuse:export": "bun run .claude/skills/explorbot-debug/langfuse-export.ts",
-    "build:prima": "bun run scripts/build-prima-npm.ts"
+    "build:prima": "bun run scripts/build-prima-npm.ts",
+    "build:mdq": "bun run scripts/build-mdq-npm.ts"
   },
   "keywords": [
     "cli",

package/dist/src/action.js

@@ -12,7 +12,9 @@ import { captureHtmlForSnapshot, htmlCombinedSnapshot, minifyHtml } from './util
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
 import { Overlay, OverlayPage } from './utils/overlay.js';
 import { sleep, waitForPageReadiness } from "./utils/page-readiness.js";
+import { isInternalStep } from "./utils/step-analyzer.js";
 import { safeFilename } from "./utils/strings.js";
+import { isSameHostFamily } from './utils/url-matcher.js';
 import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from "./utils/web-sandbox.js";
 const debugLog = createDebug('explorbot:action');
 const CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS = 3;
@@ -303,7 +305,7 @@ class Action {
         const url = URL.parse(request.url());
         if (!url)
             return;
-        if (url.origin !== this.baseOrigin)
+        if (!isSameHostFamily(url.href, this.baseOrigin))
             return;
         const call = { method: request.method(), path: url.pathname, status };
         if (this.networkRequests.some((r) => r.method === call.method && r.path === call.path && r.status === call.status))
@@ -523,7 +525,7 @@ export const attachStepLogger = (target, assertionsTarget) => {
     const listener = (step, error) => {
         if (!step?.toCode)
             return;
-        if (step.name?.startsWith('grab'))
+        if (isInternalStep(step))
             return;
         const existing = recorded.get(step);
         if (existing) {

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

@@ -4,6 +4,7 @@ import type Explorer from '../explorer.js';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import type { PlaywrightRecorder } from '../playwright-recorder.js';
 import type { StateManager } from '../state-manager.js';
+import type { Judge } from './judge.js';
 import type { AIProvider } from './provider.js';
 export interface Agent {
     emoji?: string;
@@ -16,5 +17,6 @@ export interface AgentDeps {
     knowledgeTracker: KnowledgeTracker;
     requestStore: RequestStore;
     playwrightRecorder: PlaywrightRecorder;
+    judge?: Judge;
 }
-export type ToolDeps = Pick<AgentDeps, 'explorer' | 'stateManager' | 'ai'>;
+export type ToolDeps = Pick<AgentDeps, 'explorer' | 'stateManager' | 'ai' | 'judge'>;

package/dist/src/ai/judge-provider.d.ts

@@ -0,0 +1,17 @@
+export declare class JudgeProvider {
+    readonly model: string;
+    fetchImpl: typeof fetch;
+    requestTimeoutMs: number;
+    url: string;
+    apiKey: string;
+    constructor(provider: string, model: string);
+    decide(state: unknown, question: string, options?: string[]): Promise<ProviderDecision>;
+    static endpointFor(provider: string): {
+        url: string;
+        keyName: string;
+    };
+}
+export interface ProviderDecision {
+    value: string;
+    probability: number;
+}

package/dist/src/ai/judge-provider.js

@@ -0,0 +1,56 @@
+const REQUEST_TIMEOUT_MS = 15000;
+export class JudgeProvider {
+    model;
+    fetchImpl = fetch;
+    requestTimeoutMs = REQUEST_TIMEOUT_MS;
+    url;
+    apiKey;
+    constructor(provider, model) {
+        this.model = model;
+        const { url, keyName } = JudgeProvider.endpointFor(provider);
+        const apiKey = process.env[keyName];
+        if (!apiKey)
+            throw new Error(`Set ${keyName} to use the decision model`);
+        this.url = url;
+        this.apiKey = apiKey;
+    }
+    async decide(state, question, options) {
+        let q = { type: 'noul', instructions: question };
+        if (options)
+            q = { type: 'choice', instructions: question, criteria: Object.fromEntries(options.map((option, index) => [String(index), option])) };
+        const body = JSON.stringify({ model: this.model, state, questions: { q } });
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            const response = await this.fetchImpl(this.url, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+                body,
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                throw new Error(`http_${response.status}`);
+            const answer = (await response.json())?.answers?.q;
+            if (!options && typeof answer?.noul === 'number')
+                return { value: 'yes', probability: answer.noul };
+            const value = options?.[Number(answer?.choice)];
+            const probability = answer?.probabilities?.[answer?.choice];
+            if (value === undefined || typeof probability !== 'number')
+                throw new Error('malformed_body');
+            return { value, probability };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    static endpointFor(provider) {
+        switch (provider) {
+            case 'openrouter':
+                return { url: 'https://openrouter.ai/api/alpha/decisions', keyName: 'OPENROUTER_API_KEY' };
+            case 'typesafe':
+                return { url: 'https://api.typesafe.ai/v1/systemone', keyName: 'TYPESAFE_API_KEY' };
+            default:
+                throw new Error(`Unknown decision model provider "${provider}" — use "openrouter" or "typesafe"`);
+        }
+    }
+}

package/dist/src/ai/judge-tool.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDeps } from './agent.js';
+export declare function createJudgeTool(deps: ToolDeps, buildState: () => Promise<Record<string, unknown>>): Record<string, any>;