explorbot 0.3.5 → 0.4.1

package/docs/workflow/knowledge.md

@@ -45,7 +45,48 @@ While exploring, use the `/learn` command.
 
 ### API Testing
 
-[API testing](../api-testing/basics.md) shares the same `knowledge/` directory. `npx explorbot api know <endpoint> "<description>"` adds endpoint-scoped notes, stored with an `endpoint:` frontmatter field instead of `url:`.
+[API testing](../api-testing/basics.md) shares the same `knowledge/` directory. `npx explorbot api know <endpoint> "<description>"` adds endpoint-scoped notes, stored with an `endpoint:` frontmatter field instead of `url:`. Chief reads them when planning an endpoint and Curler reads them when running its tests, so auth headers and payload rules reach both.
+
+## Per-Session Knowledge
+
+`--knowledge` passes facts to a single run. Nothing is written to `knowledge/`, so credentials and one-off test data stay out of the repository.
+
+```bash
+npx explorbot explore /pay --knowledge 'My credit card is 4111 1111 1111 1111'
+```
+
+Plain text applies to every page. Add frontmatter to scope it, with the same URL patterns knowledge files use:
+
+```bash
+npx explorbot explore / --knowledge '---
+url: /pay
+---
+Use the sandbox card 4111 1111 1111 1111 with any future expiry'
+```
+
+Repeat the flag for several facts:
+
+```bash
+npx explorbot explore / \
+  --knowledge '---
+url: /login
+---
+Log in as admin@example.com / secret123' \
+  --knowledge 'Dismiss the cookie banner before anything else'
+```
+
+Everything a knowledge file supports works here: `${env.VAR}` interpolation, and page automation fields such as `wait` and `waitForElement`.
+
+The flag works on every command of `explorbot`, `explorbot api`, `explorbot docs` and `prima`, and can go anywhere on the line. Scope API knowledge with `endpoint:` instead of `url:`:
+
+```bash
+npx explorbot api explore /orders --knowledge '---
+endpoint: /orders/*
+---
+Send X-Api-Key: ${env.API_KEY} on every request'
+```
+
+For runs driven from the environment — config-free, or on the global configuration — `EXPLORBOT_KNOWLEDGE` does the same job for the length of one run. See [Agentic usage](./agentic-usage.md).
 
 ## URL Patterns
 
@@ -81,10 +122,13 @@ Notes:
 
 | Field | Purpose |
 |-------|---------|
-| `url` | URL pattern to match (optional, defaults to `*`) |
+| `url` | Page URL pattern to match |
+| `endpoint` | API endpoint pattern to match |
 | `title` | Human-readable title (optional) |
 | Custom fields | Any additional metadata for agents |
 
+`url` scopes a file to browser pages and `endpoint` scopes it to API endpoints. A file with neither applies to both.
+
 ## Variables
 
 Knowledge files support variable interpolation with `${namespace.key}` syntax. Explorbot resolves variables when it loads the knowledge.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -77,7 +77,7 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^4.0",
     "@ai-sdk/google": "^4.0.18",
-    "@ai-sdk/groq": "^4.0",
+    "@ai-sdk/groq": "^4.0.34",
     "@ai-sdk/mistral": "^4.0.13",
     "@ai-sdk/openai": "^4.0",
     "@ai-sdk/otel": "^1.0.2",

package/rules/planner/styles/normal.md

@@ -1,7 +1,7 @@
 Study the page and figure out its business purpose. What is this page FOR? What would a user come here to do?
 
 Based on the page type, propose tests for COMPLETE user workflows:
-- If this is a data page (lists, tables): test CRUD operations end-to-end (create item → verify in list, edit item → verify changes saved, delete item → verify removed)
+- If this is a data page (lists, tables): test create, edit and delete as separate tests, each preparing the item it acts on
 - If the page has inputs to fill in: test the full commit flow, not just that the controls render
 - If this has filters and search: test filtering AND verify results change, not just "filter tab clicked"
 - If this has modals/dropdowns: test the ACTION inside them, not just opening/closing them

package/src/action-result.ts

@@ -35,7 +35,6 @@ interface ActionResultData extends WebPageState {
   focusedElement?: FocusedElement | null;
   iframeURL?: string;
   links?: Link[];
-  overlayHtml?: string;
 }
 
 export interface PageDiff {
@@ -49,6 +48,7 @@ export interface PageDiff {
   consoleErrors?: string[];
   htmlParts?: HtmlDiffPart[];
   iframes?: string;
+  areaOfInterest?: string;
 }
 
 export interface ToolResultMetadata {
@@ -89,6 +89,7 @@ export class ActionResult implements ActionResultData {
   public links: Link[] = [];
   public verifications?: Record<string, boolean>;
   public overlay: Overlay = new Overlay();
+  private _diffCache: { previousId: number | undefined; diff: Diff } | null = null;
 
   constructor(data: ActionResultData) {
     this.id = data.id;
@@ -168,6 +169,7 @@ export class ActionResult implements ActionResultData {
   set html(value: string) {
     this._html = value;
     this.snapshotCache.clear();
+    this._diffCache = null;
   }
 
   get screenshot(): Buffer | undefined {
@@ -260,6 +262,11 @@ export class ActionResult implements ActionResultData {
 
   isRelevantExperienceRecord(record: WebPageState, options?: { includeDescendantExperience?: boolean }): boolean {
     if (!record.url || !this.url) return false;
+    if (record.region && this.overlay.name !== record.region) return false;
+    if (record.root) {
+      if (!this.overlay.present) return false;
+      if (this.overlay.root && this.overlay.root !== record.root) return false;
+    }
     if (this.isMatchedBy(record)) return true;
     if (!options?.includeDescendantExperience) return false;
     const cur = extractStatePath(this.url);
@@ -476,29 +483,18 @@ export class ActionResult implements ActionResultData {
   }
 
   getStateHash(): string {
-    const parts: string[] = [];
-
-    parts.push(this.relativeUrl || this.url || '/');
-
-    this.extractHeadings(this.html);
-
-    if (this.h1) parts.push(`h1_${this.h1}`);
-    if (this.h2) parts.push(`h2_${this.h2}`);
-
-    let stateString = slugify(parts.map((part) => part.substring(0, 100)).join('_'));
-
-    if (stateString.length > 200) {
-      stateString = stateString.substring(0, 200);
-      if (stateString.endsWith('_')) {
-        stateString = stateString.slice(0, -1);
-      }
-    }
+    return this.computeStateHash(true);
+  }
 
-    return stateString;
+  get baseHash(): string {
+    return this.computeStateHash(false);
   }
 
   async diff(previousState: ActionResult | null): Promise<Diff> {
-    return Diff.create(this, previousState);
+    if (this._diffCache && this._diffCache.previousId === previousState?.id) return this._diffCache.diff;
+    const diff = await Diff.create(this, previousState);
+    this._diffCache = { previousId: previousState?.id, diff };
+    return diff;
   }
 
   async toToolResult(previousState: ActionResult | null, locator: string): Promise<ToolResultMetadata> {
@@ -549,7 +545,18 @@ export class ActionResult implements ActionResultData {
       pageDiff.ariaChangeCount = diff.ariaChangeCount;
     }
 
-    if (diff.htmlParts.length > 0) {
+    if (this.overlay.present && (!previousState.overlay.present || previousState.overlay.name !== this.overlay.name)) {
+      pageDiff.areaOfInterest = this.overlay.describe();
+    }
+
+    if (pageDiff.areaOfInterest && this.overlay.html && this.overlay.root) {
+      const htmlConfig = ConfigParser.getInstance().getConfig().html;
+      let subtree = await minifyHtml(htmlCombinedSnapshot(this.overlay.html, htmlConfig?.combined));
+      if (subtree.length > HTML_PART_SUBTREE_BUDGET) {
+        subtree = `${subtree.slice(0, HTML_PART_SUBTREE_BUDGET)}...<!-- truncated -->`;
+      }
+      pageDiff.htmlParts = [{ container: this.overlay.root, subtree, rawSize: subtree.length, added: [], removed: [] }];
+    } else if (diff.isSameUrl() && diff.htmlParts.length > 0) {
       const collapsed = collapseHtmlParts(await diff.cleanedHtmlParts());
       if (collapsed.length > 0) {
         pageDiff.htmlParts = collapsed;
@@ -565,6 +572,29 @@ export class ActionResult implements ActionResultData {
     return result;
   }
 
+  private computeStateHash(includeRegion: boolean): string {
+    const parts: string[] = [];
+
+    parts.push(this.relativeUrl || this.url || '/');
+
+    this.extractHeadings(this.html);
+
+    if (this.h1) parts.push(`h1_${this.h1}`);
+    if (this.h2) parts.push(`h2_${this.h2}`);
+    if (includeRegion && this.overlay.present && this.overlay.name) parts.push(`region_${this.overlay.name}`);
+
+    let stateString = slugify(parts.map((part) => part.substring(0, 100)).join('_'));
+
+    if (stateString.length > 200) {
+      stateString = stateString.substring(0, 200);
+      if (stateString.endsWith('_')) {
+        stateString = stateString.slice(0, -1);
+      }
+    }
+
+    return stateString;
+  }
+
   private consoleErrors(): string[] {
     const errors: string[] = [];
 
@@ -681,15 +711,24 @@ export class Diff {
     return this._messages;
   }
 
+  get similarity(): number {
+    return this._htmlDiffResult?.similarity ?? 0;
+  }
+
+  get pageSize(): number {
+    return this._htmlDiffResult?.pageSize ?? 0;
+  }
+
   async calculate(): Promise<void> {
     if (!this.previous) return;
 
+    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);

package/src/action.ts

@@ -11,9 +11,9 @@ import { Observability } from './observability.ts';
 import type { PlaywrightRecorder } from './playwright-recorder.ts';
 import type { StateManager } from './state-manager.js';
 import { browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from './utils/browser-errors.ts';
-import { captureHtmlForSnapshot, getVisibleOverlayHtmlExtractorSource, htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
+import { captureHtmlForSnapshot, htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
-import { Overlay } from './utils/overlay.js';
+import { Overlay, OverlayPage } from './utils/overlay.js';
 import { sleep, waitForPageReadiness } from './utils/page-readiness.ts';
 import { safeFilename } from './utils/strings.ts';
 import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from './utils/web-sandbox.ts';
@@ -146,13 +146,11 @@ class Action {
       let ariaSnapshot: string | null = null;
       let ariaSnapshotFile: string | undefined = undefined;
       let focusedElement: FocusedElement | null = null;
-      let overlayHtml = '';
 
       try {
         const page = this.playwrightHelper.page;
         ariaSnapshot = await page.locator('body').ariaSnapshot();
         focusedElement = await page.evaluate(readFocusedElement);
-        if (!frame) overlayHtml = await this.captureOverlayHtml();
       } catch (err) {
         debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
       }
@@ -181,9 +179,9 @@ class Action {
         ariaSnapshot,
         ariaSnapshotFile,
         focusedElement,
-        overlayHtml: overlayHtml || undefined,
         iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
       });
+      if (!frame) await this.detectRegionOfInterest(result).catch((err: Error) => debugLog('Region detection failed:', err.message));
       this.stateManager.updateState(result, codeBlock);
       return result;
     } catch (err) {
@@ -195,14 +193,64 @@ class Action {
     }
   }
 
-  private async captureOverlayHtml(): Promise<string> {
-    return this.playwrightHelper.page.evaluate(
-      ({ extractorSource, config }: { extractorSource: string; config: any }) => {
-        const extract = new Function(`return ${extractorSource}`)() as (config: any) => string;
-        return extract(config);
-      },
-      { extractorSource: getVisibleOverlayHtmlExtractorSource(), config: Overlay.captureConfig() }
-    );
+  private async detectRegionOfInterest(result: ActionResult): Promise<void> {
+    const previousState = this.stateManager.getCurrentState();
+    if (!previousState) return;
+    const previous = ActionResult.fromState(previousState);
+    const previousOverlay = previous.overlay;
+    const sameUrl = !!previous.url && result.isSameUrl({ url: previous.url });
+    const overlayPage = new OverlayPage(this.playwrightHelper.page);
+
+    if (result.overlay.detected && previousOverlay.detected && previousOverlay.root && previousOverlay.type === result.overlay.type && previousOverlay.name === result.overlay.name) {
+      result.overlay = previousOverlay;
+      return;
+    }
+
+    if (!previous.html) return;
+
+    if (previous.html === result.html) {
+      if (sameUrl && previousOverlay.present && previousOverlay.xpath && !result.overlay.detected) result.overlay = previousOverlay;
+      return;
+    }
+
+    let carried: Overlay | null = null;
+    if (sameUrl && previousOverlay.present && previousOverlay.xpath) {
+      if (await overlayPage.isStillOpen(previousOverlay)) {
+        carried = previousOverlay;
+      } else {
+        debugLog(`Region closed: ${previousOverlay.name || previousOverlay.type}`);
+        if (!result.overlay.detected) {
+          const parent = previousOverlay.parent;
+          if (parent?.xpath) {
+            const restored = new Overlay(parent);
+            if (await overlayPage.isStillOpen(restored)) result.overlay = restored;
+          }
+          return;
+        }
+      }
+    }
+
+    const diff = await result.diff(previous);
+    const detected = await overlayPage.detectRegion({
+      parts: diff.htmlParts,
+      pageSize: diff.pageSize,
+      similarity: diff.similarity,
+      sameUrl,
+      previousHtml: previous.html,
+    });
+
+    if (result.overlay.detected) {
+      if (detected) result.overlay = result.overlay.withGeometry(detected);
+      return;
+    }
+
+    if (detected) {
+      result.overlay = detected;
+      if (carried) result.overlay = detected.withParent(carried);
+      return;
+    }
+
+    if (carried) result.overlay = carried;
   }
 
   private async captureMainDocumentStatus(): Promise<number | undefined> {
@@ -381,6 +429,13 @@ class Action {
         await recorder.reset();
         await recorder.start();
       }
+      if (executedSteps.length > 0) {
+        codeString = executedSteps.map((step) => step.command).join('\n');
+      }
+      if (!isFatalBrowserError(err)) {
+        const captured = await this.captureOnce({ codeBlock: codeString }).catch(() => null);
+        if (captured && !captured.error) this.actionResult = captured;
+      }
       this.assertionSteps = [];
       throw err;
     } finally {
@@ -491,11 +546,29 @@ const ASSERTION_STEP_NAMES = new Set(['see', 'dontSee', 'seeElement', 'dontSeeEl
 type StepListener = (step: any, error?: any) => void;
 
 export const attachStepLogger = (target: ExecutedStep[], assertionsTarget?: Array<{ name: string; args: any[] }>): (() => void) => {
+  const recorded = new WeakMap<object, ExecutedStep>();
+  let batchFailed = false;
   const listener: StepListener = (step, error) => {
     if (!step?.toCode) return;
     if (step.name?.startsWith('grab')) return;
+
+    const existing = recorded.get(step);
+    if (existing) {
+      if (!error && !existing.success) {
+        existing.success = true;
+        existing.error = undefined;
+        batchFailed = target.some((entry) => !entry.success);
+      }
+      return;
+    }
+    if (batchFailed) return;
+
     const executed: ExecutedStep = { command: step.toCode(), success: !error };
-    if (error) executed.error = errorToString(error);
+    if (error) {
+      executed.error = errorToString(error);
+      batchFailed = true;
+    }
+    recorded.set(step, executed);
     target.push(executed);
     if (assertionsTarget && ASSERTION_STEP_NAMES.has(step.name)) {
       assertionsTarget.push({ name: step.name, args: step.args || [] });

package/src/ai/captain.ts

@@ -160,7 +160,7 @@ export class Captain extends CaptainBase implements Agent {
     const headingsBlock = headingLines.join('\n');
 
     let pageSummary = '';
-    const cachedResearch = Researcher.getCachedResearch(state);
+    const cachedResearch = Researcher.getCachedResearch(actionResult);
     if (cachedResearch) {
       pageSummary = `<page_summary>\n${this.explorBot.agentResearcher().extractBrief(cachedResearch)}\n</page_summary>`;
     }

package/src/ai/driller.ts

@@ -6,23 +6,9 @@ import { setActivity } from '../activity.ts';
 import { Observability } from '../observability.ts';
 import { Plan, Test, TestResult } from '../test-plan.ts';
 import { collectInteractiveNodes } from '../utils/aria.ts';
-import {
-  EXPLORBOT_ATTRS,
-  HTML_COMPOSITE_AREA_HINTS,
-  HTML_COMPOSITE_TARGET_ROLES,
-  HTML_EXTRACTION_LIMITS,
-  HTML_FORM_CONTROL_ROLES,
-  HTML_FORM_CONTROL_TAGS,
-  HTML_INTERACTIVE_ROLES,
-  HTML_SELECTORS,
-  HTML_VISIBILITY_LIMITS,
-  getComponentScopeHtmlExtractorSource,
-  getVisibleOverlayHtmlExtractorSource,
-  inferHtmlRole,
-} from '../utils/html.ts';
+import { EXPLORBOT_ATTRS, HTML_COMPOSITE_AREA_HINTS, HTML_COMPOSITE_TARGET_ROLES, HTML_EXTRACTION_LIMITS, HTML_FORM_CONTROL_ROLES, HTML_FORM_CONTROL_TAGS, HTML_INTERACTIVE_ROLES, HTML_SELECTORS, getComponentScopeHtmlExtractorSource, inferHtmlRole } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop, pause } from '../utils/loop.ts';
-import { OVERLAY_SELECTORS } from '../utils/overlay.ts';
 import { annotatePageElements } from '../utils/web-annotate.ts';
 import { eidxInContainer } from '../utils/web-eidx.ts';
 import { WebElement } from '../utils/web-element.ts';
@@ -648,8 +634,11 @@ export class Driller extends TaskAgent implements Agent {
   private async detectNestedOverlayContext(component: ComponentInfo, result: any): Promise<string | null> {
     if (!result?.pageDiff?.ariaChanges || result.pageDiff.urlChanged) return null;
 
-    const overlayHtml = await this.getVisibleOverlayHtml();
-    if (!overlayHtml) return null;
+    const parts = result.pageDiff.htmlParts ?? [];
+    let appeared = parts.filter((part: any) => part.added?.length > 0);
+    if (result.pageDiff.areaOfInterest) appeared = parts;
+    const appearedHtml = appeared.map((part: any) => part.subtree).join('\n');
+    if (!appearedHtml) return null;
 
     const state = this.stateManager.getCurrentState();
     if (!state) return null;
@@ -661,7 +650,7 @@ export class Driller extends TaskAgent implements Agent {
       Keep the recorded code reusable and include the parent-opening action when the nested element requires the overlay to be open.
 
       <overlay_html>
-      ${overlayHtml}
+      ${appearedHtml}
       </overlay_html>
 
       <current_page_aria>
@@ -671,27 +660,6 @@ export class Driller extends TaskAgent implements Agent {
     `;
   }
 
-  private async getVisibleOverlayHtml(): Promise<string> {
-    return this.explorer.withPage((page) =>
-      page.evaluate(
-        ({ extractorSource, config }) => {
-          const extract = new Function(`return ${extractorSource}`)() as (config: any) => string;
-          return extract(config);
-        },
-        {
-          extractorSource: getVisibleOverlayHtmlExtractorSource(),
-          config: {
-            interactiveContentSelector: HTML_SELECTORS.interactiveContent,
-            limits: HTML_EXTRACTION_LIMITS,
-            overlaySelectors: OVERLAY_SELECTORS.semanticOverlays,
-            overlaySemanticSelector: OVERLAY_SELECTORS.overlaySemanticSelector,
-            visibilityLimits: HTML_VISIBILITY_LIMITS,
-          },
-        }
-      )
-    );
-  }
-
   private async getComponentScopeHtml(component: ComponentInfo, originalState: ActionResult): Promise<string> {
     const scopedHtml = await this.explorer.withPage((page) =>
       page.evaluate(

package/src/ai/fisherman-tools.ts

@@ -2,16 +2,28 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import type { ApiClient } from '../api/api-client.ts';
+import type { RequestResult } from '../api/request-result.ts';
 import type { RequestStore } from '../api/request-store.ts';
 import { extractEndpointDefinition } from '../api/spec-reader.ts';
 import { tag } from '../utils/logger.ts';
+import { RequestMap } from '../utils/request-map.ts';
+import { isDynamicSegment } from '../utils/url-matcher.ts';
 
 export function createFishermanTools(apiClient: ApiClient, requestStore: RequestStore, opts: { spec?: any; baseEndpoint?: string }) {
   let finished = false;
-  let result: FishermanResult = { success: false, summary: '', created: [], failed: [] };
+  let result: FishermanResult | null = null;
+  const ledgerStart = requestStore.getMadeRequests().length;
 
-  const getResult = () => result;
+  const runRequests = () => requestStore.getMadeRequests().slice(ledgerStart);
+  const successfulWrites = () => runRequests().filter((r) => r.isWrite && !r.error && r.status >= 200 && r.status < 400);
+  const getResult = () => result ?? synthesizeResult(runRequests(), successfulWrites(), false);
   const isFinished = () => finished;
+  const finishFromText = (text?: string) => {
+    finished = true;
+    const synthesized = synthesizeResult(runRequests(), successfulWrites(), true);
+    if (text && synthesized.success) synthesized.summary = text;
+    result = synthesized;
+  };
 
   const tools = {
     getEndpointSpec: tool({
@@ -76,7 +88,7 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
     request: tool({
       description: dedent`
         Make an HTTP request to the API.
-        Returns status, timing, and auto-extracted IDs and names from the response.
+        Returns status, plus IDs and names auto-extracted from the response under 'extracted'.
       `,
       inputSchema: z.object({
         method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
@@ -119,7 +131,7 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
         return {
           success: true,
           status: reqResult.status,
-          ...extracted,
+          extracted,
         };
       },
     }),
@@ -148,9 +160,32 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
           .describe('List of items that could not be created'),
       }),
       execute: async ({ summary, created, failed }) => {
+        const writes = successfulWrites();
+        if (writes.length === 0) {
+          tag('warning').log('Fisherman: finish rejected — no successful write request in this run');
+          return { finished: false, error: 'No successful write request was made in this run, so nothing was created. Keep working, or call stop if the data cannot be prepared.' };
+        }
+
+        const createdRequests = new RequestMap(writes);
+
+        const verified: FishermanResult['created'] = [];
+        for (const item of created) {
+          if (item.id === undefined) {
+            verified.push(item);
+            continue;
+          }
+          const request = createdRequests.get(item.id);
+          if (!request) {
+            tag('warning').log(`Fisherman: dropped unverified created item ${item.type} (id: ${item.id})`);
+            continue;
+          }
+          verified.push({ ...item, request: request.toEndpoint() });
+        }
+        if (verified.length === 0) verified.push(...writes.map(toCreatedItem));
+
         tag('success').log(`Fisherman done: ${summary}`);
         finished = true;
-        result = { success: true, summary, created, failed: failed || [] };
+        result = { success: true, summary, created: verified, failed: failed || [] };
         return { finished: true };
       },
     }),
@@ -169,7 +204,21 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
     }),
   };
 
-  return { tools, getResult, isFinished };
+  return { tools, getResult, isFinished, finishFromText };
+}
+
+function synthesizeResult(made: RequestResult[], writes: RequestResult[], declaredDone: boolean): FishermanResult {
+  const failures = made.filter((r) => r.status >= 400 || r.error);
+  let summary = `Stopped before finishing: ${made.length} requests, ${writes.length} successful writes, ${failures.length} failed`;
+  const lastFailure = failures[failures.length - 1];
+  if (lastFailure) summary += `; last failure: ${lastFailure.toSummary()}`;
+  return { success: declaredDone && writes.length > 0, summary, created: writes.map(toCreatedItem), failed: [] };
+}
+
+function toCreatedItem(write: RequestResult): FishermanResult['created'][number] {
+  const { id, title } = write.extractIdAndTitle();
+  const segments = write.path.split('/').filter((s) => s && !isDynamicSegment(s));
+  return { type: segments[segments.length - 1] || 'item', id, title, request: write.toEndpoint() };
 }
 
 function responseCategory(status: number): ResponseCategory {
@@ -209,7 +258,7 @@ function extractKeyFields(body: any, result: Record<string, any> = {}, depth = 0
 export interface FishermanResult {
   success: boolean;
   summary: string;
-  created: Array<{ type: string; id?: string | number; title?: string }>;
+  created: Array<{ type: string; id?: string | number; title?: string; request?: string }>;
   failed: Array<{ type: string; reason: string }>;
 }