explorbot 0.2.5 → 0.3.1

package/docs/contributing/npm-package.md

@@ -6,7 +6,7 @@ Explorbot develops on Bun but ships to npm as a Node.js-compatible package. This
 
 - Bun (for development and running the build)
 - Node.js >= 24 (for verifying the build output)
-- npm account with publish access to `explorbot` package
+- npm account with publish access to `explorbot` and `prima-cli`, for publishing by hand; releases go out over OIDC (see [Trusted Publishing and Provenance](#trusted-publishing-and-provenance))
 
 ## How the Build Works
 
@@ -90,14 +90,16 @@ Key `package.json` fields:
     "boat/prima/src/**/*.ts",
     "boat/prima/bin/**/*.ts",
     "boat/prima/package.json",
+    "boat/prima/README.md",
     "rules/",
-    "assets/sample-files/"
+    "assets/sample-files/",
+    "models.json"
   ],
   "engines": { "node": ">=24.0.0" }
 }
 ```
 
-The package ships two commands: `explorbot`, and `prima` for the [prima boat](../reference/commands.md#prima-boat), so `npx -p explorbot prima <command>` works without a separate install.
+The package ships two commands, `explorbot` and `prima` for the [prima boat](../reference/commands.md#prima-boat). Prima is also mounted as a subcommand, so `npx explorbot prima <command>`, `npx -p explorbot prima <command>` and the standalone [`prima-cli`](#publishing-prima-cli) package all reach the same code.
 
 Explorbot is both a CLI (`bin`) and a library (`exports`). The `.` entry point is `src/index.ts`, a side-effect-free barrel that re-exports the public API (`ExplorBot`, `Plan`, `Test`, and their types). The `exports` conditions are ordered so each consumer gets the right entry: `types` (the emitted `.d.ts`) for type-checking, `bun` (the TypeScript source) under Bun, and `import` (the compiled JS) under Node.js. This is why the source `src/**` files ship alongside `dist/`.
 
@@ -127,6 +129,73 @@ npm version patch  # or minor, major
 npm publish
 ```
 
+## Publishing prima-cli
+
+Prima ships three ways, all the same code:
+
+| | |
+|---|---|
+| `npx prima-cli` | its own package |
+| `npx explorbot prima` | subcommand of the explorbot CLI |
+| `npx -p explorbot prima` | the `prima` bin explorbot installs |
+
+Prima is compiled into `dist/` by the same `tsc` run as everything else; only the packaging differs. `bun run build:prima` (`scripts/build-prima-npm.ts`) runs after `build:npm` and stages a second package:
+
+```
+dist-prima/
+├── package.json            # boat/prima/package.json + version and dependencies from the root manifest
+├── README.md               # boat/prima/README.md, the npm page
+└── dist/
+    ├── boat/prima/
+    ├── src/
+    ├── models.json
+    ├── rules/
+    └── assets/sample-files/
+```
+
+The `dist/` layout is copied, not flattened: `config.js` reads `../models.json`, `rules-loader.js` reads `../../rules`, and `tester.js` reads `../../assets/sample-files`. Dependencies are copied verbatim from the root manifest rather than pruned to prima's closure — pruning saves little next to playwright and codeceptjs, and breaks on the first moved import. Edit `boat/prima/package.json` for the package name, bin, keywords or engines.
+
+`publish-prima.yml` publishes it when a GitHub release is **published**, so a draft ships nothing. The version is the release tag with `prima-` and a leading `v` stripped: `0.2.6`, `v0.2.6` and `prima-v0.2.6` all publish `prima-cli@0.2.6`. A `prima-v*` tag is how prima ships on its own — `publish.yml` ignores it. A pre-release release, or a version containing `beta`, `alpha`, `pre` or `rc`, goes to the `beta` dist-tag.
+
+Before publishing, the workflow packs the staged package, installs the tarball into an empty directory and runs it there with an empty `HOME` — a real consumer install, which is what catches a missing file, dependency or asset. It skips a version already on the registry, so a failed run can be re-run.
+
+To check it locally:
+
+```bash
+bun run build:npm && bun run build:prima
+npm pack ./dist-prima --pack-destination /tmp
+cd $(mktemp -d) && npm init -y && npm install --ignore-scripts /tmp/prima-cli-*.tgz
+./node_modules/.bin/prima-cli --help
+```
+
+## Trusted Publishing and Provenance
+
+Both packages publish over OIDC, with no npm token in the repository. npm checks GitHub's identity token against a trusted publisher registered on the package, then attaches a provenance attestation. No `--provenance` flag is needed; trusted publishing does it.
+
+The workflows are already set up for this: `id-token: write`, `ubuntu-latest`, and `npm@latest` for the npm 11.5.1+ requirement. The rest is per package on npmjs.com, because a trusted publisher names one package and one workflow file — `explorbot`'s does not cover `prima-cli`. The package has to exist before it can be configured, which is why a new one is claimed with a manual publish first.
+
+On the package's **Settings** tab, under **Trusted Publisher**, choose **GitHub Actions**:
+
+| Field | `explorbot` | `prima-cli` |
+|---|---|---|
+| Organization or user | `testomatio` | `testomatio` |
+| Repository | `explorbot` | `explorbot` |
+| Workflow filename | `publish.yml` | `publish-prima.yml` |
+| Allowed actions | `npm publish` | `npm publish` |
+| Environment name | empty | empty |
+
+The workflow filename is a basename, and it is the field that differs — pointing `prima-cli` at `publish.yml` fails every release. Leave the environment empty unless the publish job gains an `environment:` key; a mismatch fails the publish.
+
+To check a publish was attested:
+
+```bash
+npm view <package>@<version> dist.attestations
+```
+
+A `slsa.dev/provenance/v1` predicate means it worked. Nothing printed means the version went out unattested. `npm audit signatures` checks an installed tree.
+
+Once no workflow needs a token, revoke the package's automation tokens and set its publishing access to require two-factor authentication and disallow tokens.
+
 ## Known Limitations
 
 - **Type declarations are transform-generated** - Declarations come from a transformed copy of the source (see [Type Declarations](#type-declarations)), not from `tsc --declaration` directly, because the mixin-based agents can't emit declarations as written. The published `.d.ts` types are exact; the workaround only concerns how they're produced.
@@ -135,4 +204,4 @@ npm publish
 
 The `test.yml` workflow verifies the npm build on every push. On Node.js 24 it runs `bun run build:npm`, then the Node smoke tests: `node --test tests/node/*.mjs`. The `publish.yml` workflow additionally checks `node dist/bin/explorbot-cli.js --help` before publishing.
 
-The `publish.yml` workflow publishes to npm when you push a version tag (`v*` or a bare `1.2.3`-style tag). It overwrites the package version from the tag; tags containing `beta`, `alpha`, `pre`, or `rc` publish to the `beta` dist-tag instead of `latest`.
+The `publish.yml` workflow publishes `explorbot` when you push a version tag (`v*` or a bare `1.2.3`-style tag). It overwrites the package version from the tag; tags containing `beta`, `alpha`, `pre`, or `rc` publish to the `beta` dist-tag instead of `latest`. `publish-prima.yml` publishes `prima-cli` when a GitHub release is published. Both go out over OIDC and with provenance — see [Publishing prima-cli](#publishing-prima-cli) and [Trusted Publishing and Provenance](#trusted-publishing-and-provenance).

package/models.json

@@ -1,8 +1,8 @@
 {
   "openrouter": {
     "model": "openai/gpt-oss-20b:nitro",
-    "visionModel": "google/gemma-4-31b-it:nitro",
-    "agenticModel": "google/gemma-4-31b-it:nitro"
+    "visionModel": "openai/gpt-5.6-luna",
+    "agenticModel": "openai/gpt-5.6-luna"
   },
   "poolside": {
     "model": "poolside/laguna-xs-2.1"
@@ -13,8 +13,8 @@
     "agenticModel": "qwen/qwen3.6-27b"
   },
   "openai": {
-    "model": "gpt-5.4-nano",
-    "visionModel": "gpt-5.4-nano",
+    "model": "gpt-5-nano",
+    "visionModel": "gpt-5.6-luna",
     "agenticModel": "gpt-5.6-luna"
   },
   "anthropic": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -30,6 +30,7 @@
     "boat/prima/src/**/*.ts",
     "boat/prima/bin/**/*.ts",
     "boat/prima/package.json",
+    "boat/prima/README.md",
     "rules/",
     "assets/sample-files/",
     "models.json"
@@ -58,7 +59,8 @@
     "lint:fix": "biome lint --write .",
     "check": "biome check .",
     "check:fix": "biome check --write .",
-    "langfuse:export": "bun run .claude/skills/explorbot-debug/langfuse-export.ts"
+    "langfuse:export": "bun run .claude/skills/explorbot-debug/langfuse-export.ts",
+    "build:prima": "bun run scripts/build-prima-npm.ts"
   },
   "keywords": [
     "cli",
@@ -97,6 +99,7 @@
     "ai": "^7.0.2",
     "axe-core": "^4.11.1",
     "bash-tool": "^1.3.15",
+    "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
     "codeceptjs": "4.0.0-rc.16",
     "commander": "^14.0.1",
@@ -121,6 +124,7 @@
     "parse5": "^8.0.0",
     "pixelmatch": "^7.2.0",
     "playwright": "^1.62",
+    "playwright-core": "^1.62",
     "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",

package/src/action-result.ts

@@ -4,7 +4,7 @@ import { ConfigParser, type HtmlConfig, outputPath } from './config.ts';
 import type { Link, WebPageState } from './state-manager.ts';
 import { LARGE_ARIA_CHANGE_THRESHOLD, compactAriaSnapshot, diffAriaSnapshots } from './utils/aria.ts';
 import { TTLCache } from './utils/cache.ts';
-import { type HtmlDiffPart, type HtmlDiffResult, htmlDiff } from './utils/html-diff.ts';
+import { type HtmlDiffPart, type HtmlDiffResult, htmlDiff, liveRegionMessages } from './utils/html-diff.ts';
 import { extractHeadings, extractLinks, extractTargetedHtml, htmlCombinedSnapshot, htmlMinimalUISnapshot, htmlTextSnapshot, minifyHtml } from './utils/html.ts';
 import { createDebug } from './utils/logger.ts';
 import { slugify } from './utils/strings.ts';
@@ -27,6 +27,7 @@ interface ActionResultData extends WebPageState {
   h3?: string | undefined;
   h4?: string | undefined;
   browserLogs?: any[];
+  networkRequests?: NetworkCall[];
   iframeSnapshots?: Array<{ src: string; html: string; id?: string }>;
   ariaSnapshot?: string | null;
   ariaSnapshotFile?: string;
@@ -41,6 +42,9 @@ export interface PageDiff {
   currentUrl: string;
   ariaChanges?: string | null;
   ariaChangeCount?: number;
+  messages?: string[];
+  requests?: NetworkCall[];
+  consoleErrors?: string[];
   htmlParts?: HtmlDiffPart[];
   iframes?: string;
 }
@@ -66,6 +70,7 @@ export class ActionResult implements ActionResultData {
   public url = '';
   public fullUrl: string | undefined = undefined;
   public browserLogs: any[] = [];
+  public networkRequests: NetworkCall[] = [];
   public iframeSnapshots: Array<{ src: string; html: string; id?: string }> = [];
   public iframeURL: string | undefined = undefined;
   readonly screenshotFile: string | undefined = undefined;
@@ -91,6 +96,7 @@ export class ActionResult implements ActionResultData {
     this.httpStatus = data.httpStatus;
     this.error = data.error ?? null;
     this.browserLogs = data.browserLogs ?? [];
+    this.networkRequests = data.networkRequests ?? [];
     this.iframeSnapshots = data.iframeSnapshots ?? [];
     this.iframeURL = data.iframeURL;
     this.notes = data.notes ?? [];
@@ -508,23 +514,30 @@ export class ActionResult implements ActionResultData {
       return result;
     }
 
-    const urlChanged = previousState ? !this.isSameUrl({ url: previousState.url }) : true;
+    const pageDiff: PageDiff = {
+      urlChanged: previousState ? !this.isSameUrl({ url: previousState.url }) : true,
+      currentUrl: this.url,
+    };
+    result.pageDiff = pageDiff;
 
-    if (!previousState) {
-      result.pageDiff = {
-        urlChanged: true,
-        currentUrl: this.url,
-      };
-      return result;
+    if (this.networkRequests.length > 0) {
+      pageDiff.requests = this.networkRequests;
+    }
+
+    const consoleErrors = this.consoleErrors();
+    if (consoleErrors.length > 0) {
+      pageDiff.consoleErrors = consoleErrors;
     }
 
+    if (!previousState) return result;
+
+    pageDiff.previousUrl = previousState.url;
+
     const diff = await this.diff(previousState);
 
-    const pageDiff: PageDiff = {
-      urlChanged,
-      previousUrl: previousState.url,
-      currentUrl: this.url,
-    };
+    if (diff.messages.length > 0) {
+      pageDiff.messages = diff.messages;
+    }
 
     if (diff.ariaChanged) {
       pageDiff.ariaChanges = diff.ariaChanged;
@@ -552,11 +565,28 @@ export class ActionResult implements ActionResultData {
       }
     }
 
-    result.pageDiff = pageDiff;
     return result;
   }
+
+  private consoleErrors(): string[] {
+    const errors: string[] = [];
+
+    for (const log of this.browserLogs) {
+      if ((log.type || log.level) !== 'error') continue;
+      const text = String(log.text || log.message || log).trim();
+      if (!text) continue;
+      if (errors.includes(text)) continue;
+      errors.push(text.slice(0, CONSOLE_ERROR_MAX_LENGTH));
+      if (errors.length === CONSOLE_ERROR_LIMIT) break;
+    }
+
+    return errors;
+  }
 }
 
+const CONSOLE_ERROR_MAX_LENGTH = 300;
+const CONSOLE_ERROR_LIMIT = 3;
+
 const HTML_PARTS_TOTAL_BUDGET = 8000;
 const HTML_PARTS_COUNT_LIMIT = 8;
 const HTML_PART_SUBTREE_BUDGET = 2000;
@@ -584,6 +614,7 @@ function collapseHtmlParts(parts: HtmlDiffPart[]): HtmlDiffPart[] {
 
 export class Diff {
   private _htmlDiffResult: HtmlDiffResult | null = null;
+  private _messages: string[] = [];
   private _ariaDiffResult: string | null = null;
   private _ariaChangeCount = 0;
   private _isSameUrl: boolean;
@@ -636,19 +667,33 @@ export class Diff {
     return this._htmlDiffResult;
   }
 
+  get messages(): string[] {
+    return this._messages;
+  }
+
   async calculate(): Promise<void> {
     if (!this.previous) return;
 
-    if (this._isSameUrl) {
-      this._htmlDiffResult = await htmlDiff(this.previous.html, this.current.html, ConfigParser.getInstance().getConfig().html);
+    if (!this._isSameUrl) {
+      this._messages = liveRegionMessages(this.previous.html, this.current.html);
+      return;
     }
 
+    this._htmlDiffResult = await htmlDiff(this.previous.html, this.current.html, ConfigParser.getInstance().getConfig().html);
+    this._messages = this._htmlDiffResult.messages;
+
     const ariaDiff = diffAriaSnapshots(this.previous.ariaSnapshot, this.current.ariaSnapshot);
     this._ariaDiffResult = ariaDiff.text;
     this._ariaChangeCount = ariaDiff.count;
   }
 }
 
+export interface NetworkCall {
+  method: string;
+  path: string;
+  status: number;
+}
+
 export interface FocusedElement {
   role: string;
   name: string;

package/src/action.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { context, trace } from '@opentelemetry/api';
 import { container, recorder } from 'codeceptjs';
 import * as codeceptjs from 'codeceptjs';
-import { ActionResult, type FocusedElement } from './action-result.js';
+import { ActionResult, type FocusedElement, type NetworkCall } from './action-result.js';
 import { clearActivity, setActivity } from './activity.ts';
 import { ConfigParser, outputPath } from './config.js';
 import type { ExplorbotConfig } from './config.js';
@@ -21,6 +21,8 @@ const debugLog = createDebug('explorbot:action');
 const CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS = 3;
 const DEFAULT_ACTION_TIMEOUT = 3000;
 const DEFAULT_PAGE_TIMEOUT = 3000;
+const MAX_NETWORK_CALLS = 10;
+const IMPORTANT_LOG_LEVELS = new Set(['info', 'error', 'warning', 'warn']);
 
 class Action {
   private actor: CodeceptJS.I;
@@ -38,6 +40,8 @@ class Action {
   private recorder?: PlaywrightRecorder;
   private recovery: RecoveryRunner;
   private mainDocumentStatus: number | undefined = undefined;
+  private networkRequests: NetworkCall[] = [];
+  private baseOrigin: string;
 
   constructor(actor: CodeceptJS.I, stateManager: StateManager, recorder?: PlaywrightRecorder, recovery?: RecoveryRunner) {
     this.actor = actor;
@@ -46,6 +50,7 @@ class Action {
     this.playwrightHelper = container.helpers('Playwright');
     this.recorder = recorder;
     this.recovery = recovery || ((fn) => fn());
+    this.baseOrigin = URL.parse(this.config.playwright?.url || '')?.origin || '';
   }
 
   async saveScreenshot(): Promise<string | undefined> {
@@ -127,9 +132,7 @@ class Action {
       const logPath = join(statesDir, logFile);
       const formattedLogs = browserLogs.map((log: any) => {
         const logTimestamp = new Date().toISOString();
-        const level = (log.type || log.level || 'LOG').toUpperCase();
-        const message = log.text || log.message || String(log);
-        return `[${logTimestamp}] ${level}: ${message}`;
+        return `[${logTimestamp}] ${log.type.toUpperCase()}: ${log.text}`;
       });
       fs.writeFileSync(logPath, `${formattedLogs.join('\n')}\n`, 'utf8');
 
@@ -157,12 +160,16 @@ class Action {
         ariaSnapshotFile = ariaFileName;
       }
 
+      const networkRequests = this.networkRequests;
+      this.networkRequests = [];
+
       const result = new ActionResult({
         html,
         title,
         httpStatus: await this.captureMainDocumentStatus(),
         url,
         browserLogs,
+        networkRequests,
         htmlFile,
         logFile,
         screenshotFile,
@@ -202,26 +209,53 @@ class Action {
     }
   }
 
-  private captureMainDocumentResponse(): () => void {
+  private captureResponses(): () => void {
     const page = this.playwrightHelper.page;
     if (!page?.on || !page?.off) return () => {};
 
     this.mainDocumentStatus = undefined;
+    this.networkRequests = [];
 
     const handler = (response: any) => {
       const request = response.request();
-      if (request.resourceType() !== 'document') return;
-      if (response.frame() !== page.mainFrame()) return;
       const status = response.status();
       if (typeof status !== 'number') return;
       if (status <= 0) return;
-      this.mainDocumentStatus = status;
+
+      if (request.resourceType() === 'document') {
+        if (response.frame() !== page.mainFrame()) return;
+        this.mainDocumentStatus = status;
+        return;
+      }
+
+      this.recordNetworkCall(request, status);
     };
 
     page.on('response', handler);
     return () => page.off('response', handler);
   }
 
+  private recordNetworkCall(request: any, status: number): void {
+    const resourceType = request.resourceType();
+    if (resourceType !== 'xhr' && resourceType !== 'fetch') return;
+
+    const url = URL.parse(request.url());
+    if (!url) return;
+    if (url.origin !== this.baseOrigin) return;
+
+    const call: NetworkCall = { method: request.method(), path: url.pathname, status };
+    if (this.networkRequests.some((r) => r.method === call.method && r.path === call.path && r.status === call.status)) return;
+
+    if (this.networkRequests.length >= MAX_NETWORK_CALLS) {
+      if (status < 400) return;
+      const succeeded = this.networkRequests.findIndex((r) => r.status < 400);
+      if (succeeded === -1) return;
+      this.networkRequests.splice(succeeded, 1);
+    }
+
+    this.networkRequests.push(call);
+  }
+
   /**
    * Capture HTML snapshots of all iframes on the page
    */
@@ -267,13 +301,7 @@ class Action {
     try {
       const logs = await (this.actor as any).grabBrowserLogs();
 
-      // Filter for important logs (info, error, warning)
-      const importantLogs = logs.filter((log: any) => {
-        const level = log.type || log.level;
-        return ['info', 'error', 'warning', 'warn'].includes(level);
-      });
-
-      return importantLogs;
+      return logs.map(toBrowserLog).filter((log: any) => IMPORTANT_LOG_LEVELS.has(log.type));
     } catch (error) {
       debugLog('Failed to capture browser logs:', error);
       return [];
@@ -292,7 +320,7 @@ class Action {
     const stepListener = attachStepLogger(executedSteps, assertionSteps);
     const groupId = this.recorder ? await this.recorder.beginAction(codeString) : null;
     this.playwrightGroupId = groupId;
-    const detachMainDocumentResponse = this.captureMainDocumentResponse();
+    const detachResponses = this.captureResponses();
     const activeSpan = Observability.getSpan();
     const tracer = trace.getTracer('ai');
     const stepSpan = activeSpan ? tracer.startSpan('codeceptjs.step', undefined, trace.setSpan(context.active(), activeSpan)) : null;
@@ -341,7 +369,7 @@ class Action {
       throw err;
     } finally {
       this.restorePageTimeout();
-      detachMainDocumentResponse();
+      detachResponses();
       if (groupId) await this.recorder!.endAction();
       detachStepLogger(stepListener);
       if (stepSpan) {
@@ -429,6 +457,12 @@ async function captureHtml(page: any, frame: any, actor: any): Promise<string> {
   throw new Error('Playwright page is unavailable for HTML capture');
 }
 
+function toBrowserLog(log: any): { type: string; text: string } {
+  const type = typeof log.type === 'function' ? log.type() : log.type || log.level || 'log';
+  const text = typeof log.text === 'function' ? log.text() : log.text || log.message || String(log);
+  return { type, text: text.replace(/\s+/g, ' ').trim() };
+}
+
 async function captureTitle(page: any, actor: any): Promise<string> {
   if (page?.title) return page.title();
   if (actor?.grabTitle) return actor.grabTitle();

package/src/ai/captain/web-mode.ts

@@ -16,7 +16,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
         researcher: ctx.explorBot.agentResearcher(),
         navigator: ctx.explorBot.agentNavigator(),
       });
-      const { see, context, visualClick, learnExperience } = agentTools;
+      const { see, context, visualClick } = agentTools;
 
       const tools: Record<string, any> = {
         navigate: tool({
@@ -124,7 +124,6 @@ export function WithWebMode<T extends Constructor>(Base: T) {
 
         ...codeceptTools,
         context,
-        learnExperience,
       };
 
       if (see) tools.see = see;

package/src/ai/captain.ts

@@ -21,7 +21,7 @@ import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { TaskAgent } from './task-agent.ts';
-import { withdrawVisionTools } from './tools.ts';
+import { createLearnExperienceTool, withdrawVisionTools } from './tools.ts';
 
 const MAX_STEPS = 15;
 
@@ -241,6 +241,14 @@ export class Captain extends CaptainBase implements Agent {
 
   private coreTools(task: Task, onDone: (summary: string) => void) {
     return {
+      learnExperience: createLearnExperienceTool({
+        getExperienceTracker: () => this.getExperienceTracker(),
+        getState: () => {
+          const state = this.explorBot.stateManager().getCurrentState();
+          if (!state) return null;
+          return ActionResult.fromState(state);
+        },
+      }),
       done: tool({
         description: 'Call when the user request is fulfilled.',
         inputSchema: z.object({

package/src/ai/conversation.ts

@@ -17,6 +17,8 @@ export function toolExecutionLabel(input: Record<string, any> | undefined): stri
   return input?.explanation || input?.assertion || input?.reason || input?.request || '';
 }
 
+export const NARRATION_TOOL = 'commentary';
+
 const AUTO_COMPACT_ARIA_CHANGES_CUTOFF = 500;
 const AUTO_COMPACT_TARGETED_HTML_CUTOFF = 500;
 
@@ -227,6 +229,7 @@ export class Conversation {
       if (!Array.isArray(message.content)) continue;
       for (const part of message.content) {
         if (part.type !== 'tool-result') continue;
+        if (part.toolName === NARRATION_TOOL) continue;
         executions.push(toToolExecution(part.toolName, toolCalls.get(part.toolCallId) || {}, part.output));
       }
     }

package/src/ai/driller.ts

@@ -30,7 +30,7 @@ import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import { drillLocatorRule } from './rules.ts';
 import { TaskAgent, isInteractive } from './task-agent.ts';
-import { createCodeceptJSTools } from './tools.ts';
+import { createCodeceptJSTools, createLearnExperienceTool } from './tools.ts';
 
 const debugLog = createDebug('explorbot:driller');
 
@@ -306,7 +306,11 @@ export class Driller extends TaskAgent implements Agent {
 
     let finished = false;
     const actionTools = this.createVerifiedActionTools(createCodeceptJSTools(this.toolDeps, test), component);
-    const tools = { ...actionTools, ...this.createDrillFlowTools(originalState, test, interactive) };
+    const learnExperience = createLearnExperienceTool({
+      getExperienceTracker: () => this.getExperienceTracker(),
+      getState: () => ActionResult.fromState(this.stateManager.getCurrentState() || originalState),
+    });
+    const tools = { ...actionTools, learnExperience, ...this.createDrillFlowTools(originalState, test, interactive) };
 
     await loop(
       async ({ stop, iteration }) => {

package/src/ai/fisherman-tools.ts

@@ -29,6 +29,28 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
 
         const captured = requestStore.findCapturedRequest(method, path);
         if (captured) {
+          if (captured.status >= 400) {
+            const rejectedCapture = {
+              status: captured.status,
+              requestBody: captured.requestBody || 'no body',
+            };
+            if (opts.spec) {
+              try {
+                const definition = extractEndpointDefinition(opts.spec, path, opts.baseEndpoint);
+                return { source: 'spec', method, path, definition, rejectedCapture };
+              } catch {
+                return { source: 'captured', method, path, usable: false, rejectedRequestBody: captured.requestBody || 'no body', status: captured.status };
+              }
+            }
+            return {
+              source: 'captured',
+              method: captured.method,
+              path: captured.path,
+              status: captured.status,
+              usable: false,
+              rejectedRequestBody: captured.requestBody || 'no body',
+            };
+          }
           return {
             source: 'captured',
             method: captured.method,
@@ -87,6 +109,7 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
             success: false,
             status: reqResult.status,
             statusText: reqResult.statusText,
+            category: responseCategory(reqResult.status),
             errorPreview: reqResult.rawResponseBody.substring(0, 300),
           };
         }
@@ -149,6 +172,16 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
   return { tools, getResult, isFinished };
 }
 
+function responseCategory(status: number): ResponseCategory {
+  if (status === 400 || status === 422) return 'validation';
+  if (status === 401 || status === 403) return 'authorization';
+  if (status === 404) return 'not_found';
+  if (status === 409) return 'conflict';
+  if (status === 408 || status === 425 || status === 429) return 'temporary';
+  if (status >= 500) return 'server';
+  return 'client';
+}
+
 function extractKeyFields(body: any, result: Record<string, any> = {}, depth = 0): Record<string, any> {
   if (!body || typeof body !== 'object' || depth > 5) return result;
 
@@ -179,3 +212,5 @@ export interface FishermanResult {
   created: Array<{ type: string; id?: string | number; title?: string }>;
   failed: Array<{ type: string; reason: string }>;
 }
+
+type ResponseCategory = 'validation' | 'authorization' | 'not_found' | 'conflict' | 'temporary' | 'server' | 'client';

package/src/ai/fisherman.ts

@@ -196,7 +196,7 @@ export class Fisherman implements Agent {
 
       AVAILABLE TOOLS:
       ${toolNames.join(', ')}.
-      Use tool names exactly as listed. Do not invent aliases, combined names, or names with channel markers such as "commentary".
+      Use tool names exactly as listed. Do not invent aliases or combined names.
       Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
 
       WORKFLOW:
@@ -208,7 +208,8 @@ export class Fisherman implements Agent {
       RULES:
       - Always call getEndpointSpec before your first request to an unfamiliar endpoint
       - Chain requests logically — create parent resources before children
-      - If a request fails, try once more with adjusted data before reporting failure
+      - Use the response category and error text to decide what failed: validation requires corrected data, authorization requires valid access, not_found requires a valid path or parent, and conflict requires resolving the conflicting state
+      - Retry temporary or server failures once. Retry other failures only when the specification or error text gives a concrete correction
       - Use realistic but unique data for each item (vary names, titles)
 
       ${dataProtectionRules}