explorbot 0.4.10 → 0.5.1

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/explorbot-cli.ts

@@ -12,7 +12,7 @@ import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { knowledgeOption, wsOption } from '../src/commands/options/index.js';
+import { decisionModelOption, knowledgeOption, wsOption } from '../src/commands/options/index.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot, type ExplorBotOptions } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
@@ -33,6 +33,7 @@ const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version as stri
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
 wsOption.register(program);
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 
 process.on('uncaughtException', async (error) => {
   tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);

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/README.md

@@ -61,22 +61,49 @@ prima-cli browser stop
 
 Prima needs a model, and takes it from the environment. There is no `init` to run and nothing is written for you.
 
+The setup we recommend runs everything through OpenRouter with one key: GPT-OSS 120B served by Groq as the main model, and TypeSafe's Jev as the [decision model](https://github.com/testomatio/explorbot/blob/main/docs/web-testing/decisions.md), which answers narrow yes/no and pick-one questions so the main model is called less often.
+
 ```bash
-export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b
-export OPENROUTER_API_KEY=your-key
+PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b:nitro
+PRIMA_CLI_DECISION_MODEL=openrouter/typesafe/jev-1.13
+OPENROUTER_API_KEY=your-key
 ```
 
-The provider comes from the model name, so that is the whole setup. Fish uses `set -gx` instead of `export`. Since prima is usually run by a coding agent, the better home is the agent's own config — in `~/.claude/settings.json`, an `env` block reaches every command the agent runs:
+The provider comes from each model name, and `:nitro` asks OpenRouter for its fastest host, which is Groq for this model. Jev is optional: leave `PRIMA_CLI_DECISION_MODEL` unset and prima never calls it, or pass `--decision-model` for a single run.
+
+Prima is usually run by a coding agent, so the best home for these variables is the agent's own config, where they reach every command the agent runs.
+
+Claude Code, in `~/.claude/settings.json`:
 
 ```json
 {
   "env": {
-    "PRIMA_CLI_AI_MODEL": "openrouter/openai/gpt-oss-120b",
+    "PRIMA_CLI_AI_MODEL": "openrouter/openai/gpt-oss-120b:nitro",
+    "PRIMA_CLI_DECISION_MODEL": "openrouter/typesafe/jev-1.13",
     "OPENROUTER_API_KEY": "your-key"
   }
 }
 ```
 
+Codex, in `~/.codex/config.toml`:
+
+```toml
+[shell_environment_policy]
+set = { PRIMA_CLI_AI_MODEL = "openrouter/openai/gpt-oss-120b:nitro", PRIMA_CLI_DECISION_MODEL = "openrouter/typesafe/jev-1.13", OPENROUTER_API_KEY = "your-key" }
+```
+
+`set` is applied after Codex filters the inherited environment, so the key survives even where names containing `KEY` are stripped.
+
+To run prima yourself, or from any agent that inherits your shell, export them in `~/.bashrc` or `~/.zshrc`:
+
+```bash
+export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b:nitro
+export PRIMA_CLI_DECISION_MODEL=openrouter/typesafe/jev-1.13
+export OPENROUTER_API_KEY=your-key
+```
+
+Fish uses `set -gx` in `~/.config/fish/config.fish` instead of `export`.
+
 Screenshot analysis needs its own model — one is never guessed from the main model. Set `PRIMA_CLI_VISION_MODEL`, or pass `--vision-model` for a single run, as `--model` does for the main one. Without it prima still runs, but settles `check` outcomes from the run log rather than from the page as seen.
 
 Every `PRIMA_CLI_*` variable mirrors the `EXPLORBOT_*` one of the same name and wins over it, so prima can be pointed at a different provider, model or URL without disturbing an explorbot setup on the same machine. `PRIMA_CLI_AI_MODEL`, `PRIMA_CLI_URL`, `PRIMA_CLI_VISION_MODEL` and the rest all work this way.

package/boat/prima/bin/prima-cli.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
-import { knowledgeOption } from '../../../src/commands/options/index.ts';
+import { decisionModelOption, knowledgeOption } from '../../../src/commands/options/index.ts';
 import { createPrimaCommands } from '../src/cli.ts';
 
 const program = createPrimaCommands('prima');
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 program.parse();

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/explorbot-cli.js

@@ -12,7 +12,7 @@ import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { knowledgeOption, wsOption } from '../src/commands/options/index.js';
+import { decisionModelOption, knowledgeOption, wsOption } from '../src/commands/options/index.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
@@ -30,6 +30,7 @@ const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
 wsOption.register(program);
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 process.on('uncaughtException', async (error) => {
     tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);
     await flushTelemetry();

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/bin/prima-cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { knowledgeOption } from "../../../src/commands/options/index.js";
+import { decisionModelOption, knowledgeOption } from "../../../src/commands/options/index.js";
 import { createPrimaCommands } from "../src/cli.js";
 const program = createPrimaCommands('prima');
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 program.parse();

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.10",
+  "version": "0.5.1",
   "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",
@@ -101,7 +102,7 @@
     "bash-tool": "^1.3.15",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "^4.2.0-beta.3",
+    "codeceptjs": "^4.2.0",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",