explorbot 0.0.5 → 0.1.1

package/src/ai/pilot.ts

@@ -256,9 +256,18 @@ export class Pilot implements Agent {
 
         Plan the test execution for this scenario.
 
-        FIRST: Call precondition() to create fresh data that this test will act on.
-        Ask: "What will this test edit/delete/use?" — create THAT item via precondition.
-        Do not describe what's already on the page — create new disposable items for the test.
+        FIRST: Decide if precondition() is needed.
+
+        Call precondition() WHEN:
+        - The scenario edits/deletes/modifies an item, and you want a DISPOSABLE item to act on safely
+        - The scenario needs specific data clearly NOT on the current page (e.g., items with specific statuses for filtering)
+
+        SKIP precondition() WHEN:
+        - The scenario is "Create X" — the test itself creates the item
+        - The current page already shows the item the test will act on (check <state> and <page_summary>)
+        - The scenario tests navigation, UI behavior, or viewing — no data mutation needed
+
+        If needed, call precondition() now. If not, proceed directly to planning.
 
         THEN: Based on the page elements and current state, outline:
         1. Which elements to interact with and in what order
@@ -701,6 +710,8 @@ export class Pilot implements Agent {
       - Click succeeded but ariaDiff shows elements unrelated to tester's intention (e.g., clicked "Edit" but dropdown appeared) → wrong button or unexpected behavior. Instruct Tester to Escape and try a different approach.
       - form(I.type()) succeeded → I.type() sends keys to whatever is focused, no guarantee it's the right field. Instruct Tester to verify with see() that text appeared in the correct field. If targetedHtml shows a button/link, text went to wrong element — click the correct field first and retry.
       - ariaDiff shows 5+ elements removed/added after clicking content → page entered a different mode (editor, panel, modal). Instruct Tester to call context() to see current state before guessing selectors.
+      - Dropdown/select opened but contains NO options, or a list/table is empty when items were expected → data doesn't exist yet. Call precondition() to create the missing items (labels, categories, etc.), then instruct Tester to retry.
+      - Tester tries to select/filter/assign something but the option list is empty or expected value is not present → missing auxiliary data. Call precondition() to create it.
 
       Detecting logically wrong successes — review "executed", "element", and "skipped" fields:
       - Click SUCCESS but "executed" command differs from "explanation" intent → wrong element was clicked. The intended element wasn't found and a different one was clicked instead.
@@ -750,23 +761,36 @@ export class Pilot implements Agent {
       YOUR tools (Pilot-only):
       - precondition(description) — create FRESH test data via API that the test will act on. Do NOT request users.
 
-      PRECONDITIONS — what to create:
+      PRECONDITIONS — when and what to create:
       Preconditions create NEW disposable items that the test will modify, delete, or interact with.
-      Do NOT describe what already exists on the page — describe what NEW data the test needs to act on.
 
       Ask yourself: "What object will this test change/delete/use? Create THAT."
 
-      Examples:
+      When to call precondition():
+      - Scenario edits/deletes/modifies an item → create a disposable target
+      - Scenario needs auxiliary data (labels, categories, statuses to filter by)
+      - Tester failed because required data is missing (empty dropdown, no items to select)
+
+      When to SKIP precondition():
+      - Scenario is "Create X" — the test itself creates the item, no precondition needed
+      - Current page already shows the exact data needed (check <state> h1/title and <page_summary>)
+      - Scenario tests navigation, search UI, or viewing — no data mutation involved
+
+      Examples — when to create:
       - "Edit test description" → precondition("1 test") — the test will edit this item
       - "Delete a comment" → precondition("1 comment") — the test will delete this item
       - "Assign a label to item" → precondition("1 item and 1 label named Bug") — test assigns the label
       - "Filter by status" → precondition("3 items: 2 with status Open, 1 with status Closed")
-      - "Move item between lists" → precondition("1 item in list A")
 
-      WRONG: precondition("1 test suite named Updated Suite with existing tests") — this describes the page, not what to create
+      Examples — when to skip:
+      - "Create a new blog post" → SKIP, the test creates it
+      - "Edit blog post" while on a blog post page → SKIP, data already exists
+      - "View dashboard" → SKIP, no data mutation
+
+      WRONG: precondition("1 test suite named Updated Suite with existing tests") — describes the page, not what to create
       RIGHT: precondition("1 test") — create a fresh test that the scenario will edit
 
-      Call precondition() for EVERY item the scenario will act on. Keep descriptions short and specific.
+      Keep descriptions short and specific.
 
       Response format:
       PROGRESS: <1 sentence assessment>

package/src/ai/planner/subpages.ts

@@ -1,5 +1,6 @@
 import dedent from 'dedent';
 import { z } from 'zod';
+import { ConfigParser } from '../../config.ts';
 import { normalizeUrl } from '../../state-manager.ts';
 import type { StateManager } from '../../state-manager.ts';
 import type { Plan } from '../../test-plan.ts';
@@ -9,9 +10,9 @@ import type { Constructor } from '../researcher/mixin.ts';
 
 const planRegistry: Map<string, PlanRecord> = new Map();
 
-export function registerPlan(url: string, plan: Plan, feature?: string): void {
+export function registerPlan(url: string, plan: Plan, feature?: string, stateHash?: string): void {
   const key = buildKey(url, feature);
-  planRegistry.set(key, { plan, feature, url });
+  planRegistry.set(key, { plan, feature, url, stateHash });
 }
 
 export function getRegisteredPlan(url: string, feature?: string): PlanRecord | undefined {
@@ -37,7 +38,30 @@ function buildKey(url: string, feature?: string): string {
   return normalized;
 }
 
-function isTemplateMatch(urlA: string, urlB: string): boolean {
+export function isDynamicSegment(segment: string): boolean {
+  try {
+    const configRegex = ConfigParser.getInstance().getConfig().dynamicPageRegex;
+    if (configRegex) return new RegExp(configRegex, 'i').test(segment);
+  } catch {
+    /* config not loaded yet */
+  }
+
+  // numeric: /users/123
+  if (/^\d+$/.test(segment)) return true;
+  // UUID: /items/550e8400-e29b-41d4-a716-446655440000
+  if (/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(segment)) return true;
+  // ULID: /items/01ARZ3NDEKTSV4RRFFQ69G5FAV
+  if (/^[0-9A-HJKMNP-TV-Z]{26}$/.test(segment)) return true;
+  // hex ID (4+ chars): /suite/70dae98a
+  if (/^[a-f0-9]{4,}$/i.test(segment)) return true;
+  // hex-prefixed slug (8+ hex before dash): /suite/95ef0c94-mobile
+  if (/^[a-f0-9]{8,}-/i.test(segment)) return true;
+  // short mixed alphanumeric (digits + letters, ≤8 chars, no dash): /item/x7f2
+  if (segment.length <= 8 && !segment.includes('-') && /\d/.test(segment) && /[a-z]/i.test(segment)) return true;
+  return false;
+}
+
+export function isTemplateMatch(urlA: string, urlB: string): boolean {
   const partsA = normalizeUrl(urlA).split('/');
   const partsB = normalizeUrl(urlB).split('/');
   if (partsA.length !== partsB.length) return false;
@@ -47,12 +71,18 @@ function isTemplateMatch(urlA: string, urlB: string): boolean {
     if (partsA[i] === partsB[i]) continue;
     diffCount++;
     if (diffCount > 1) return false;
-    const isNumericOrShortId = /^\d+$|^[a-f0-9]{4,}$/i;
-    if (!isNumericOrShortId.test(partsA[i]) && !isNumericOrShortId.test(partsB[i])) return false;
+    if (!isDynamicSegment(partsA[i]) && !isDynamicSegment(partsB[i])) return false;
   }
   return diffCount === 1;
 }
 
+export function getPlannedByStateHash(hash: string): PlanRecord | null {
+  for (const record of planRegistry.values()) {
+    if (record.stateHash === hash) return record;
+  }
+  return null;
+}
+
 const SubPagePickSchema = z.object({
   url: z.string().nullable(),
   reason: z.string(),
@@ -71,7 +101,7 @@ export function WithSubPages<T extends Constructor>(Base: T) {
       for (const page of visited) {
         const pagePath = normalizeUrl(page.url);
         if (!pagePath.startsWith(currentPath) || pagePath === currentPath) continue;
-        if (isPagePlanned(page.url)) continue;
+        if (this.findSimilarPlan(page.url)) continue;
         if (candidates.some((c) => normalizeUrl(c.url) === pagePath)) continue;
 
         candidates.push({
@@ -136,6 +166,6 @@ export function WithSubPages<T extends Constructor>(Base: T) {
   };
 }
 
-type PlanRecord = { plan: Plan; feature?: string; url: string };
+type PlanRecord = { plan: Plan; feature?: string; url: string; stateHash?: string };
 
 type SubPageCandidate = { url: string; title?: string; h1?: string; visitCount: number };

package/src/ai/planner.ts

@@ -18,10 +18,12 @@ import { Conversation } from './conversation.ts';
 import type { Fisherman } from './fisherman.ts';
 import { getActiveStyle, getStyles } from './planner/styles.ts';
 import { WithSessionDedup } from './planner/session-dedup.ts';
-import { WithSubPages, getRegisteredPlan, registerPlan } from './planner/subpages.ts';
+import { WithSubPages, getPlannedByStateHash, getRegisteredPlan, registerPlan } from './planner/subpages.ts';
+import { findSimilarStateHash } from './researcher/cache.ts';
 import type { Provider } from './provider.js';
 import { hasFocusedSection } from './researcher/focus.ts';
 import { POSSIBLE_SECTIONS, Researcher } from './researcher.ts';
+import { Suite } from '../suite.ts';
 import { fileUploadRule, protectionRule } from './rules.ts';
 
 const debugLog = createDebug('explorbot:planner');
@@ -57,6 +59,7 @@ export class Planner extends PlannerBase implements Agent {
   currentPlan: Plan | null = null;
   freshStart = false;
   private lastStyleName = '';
+  private lastSuite: Suite | null = null;
   researcher: Researcher;
   private fisherman: Fisherman | null = null;
 
@@ -127,13 +130,25 @@ export class Planner extends PlannerBase implements Agent {
     debugLog('Planning:', state?.url);
     if (!state) throw new Error('No state found');
 
-    if (!this.freshStart && !feature && !this.currentPlan && state.url) {
+    if (!feature && !this.currentPlan && state.url) {
       const similar = this.findSimilarPlan(state.url);
       if (similar) {
         tag('info').log(`Similar page already planned: ${similar.url} (${similar.plan.tests.length} tests)`);
         this.registerPlanInSession(similar.plan);
         return similar.plan;
       }
+
+      const actionResult = ActionResult.fromState(state);
+      const combinedHtml = await actionResult.combinedHtml();
+      const similarHash = await findSimilarStateHash(combinedHtml);
+      if (similarHash) {
+        const planned = getPlannedByStateHash(similarHash);
+        if (planned) {
+          tag('info').log(`Page content similar to already-planned: ${planned.url} — skipping`);
+          this.registerPlanInSession(planned.plan);
+          return planned.plan;
+        }
+      }
     }
 
     if (!this.freshStart && !this.currentPlan && state.url) {
@@ -188,14 +203,14 @@ export class Planner extends PlannerBase implements Agent {
       this.currentPlan.url = state.url;
       if (parentPlan) this.currentPlan.parentPlan = parentPlan;
       const allPreviousScenarios = this.getPreviousSessionScenarios();
+      const existingTestScenarios = this.getExistingTestFileScenarios(state.url);
+      for (const s of existingTestScenarios) allPreviousScenarios.add(s);
       for (const t of tests) {
         if (allPreviousScenarios.has(t.scenario.toLowerCase())) continue;
         t.style = this.lastStyleName;
         t.startUrl = state.url;
         this.currentPlan.addTest(t);
       }
-      const summary = `Scenarios:\n${this.currentPlan.tests.map((t) => `- [${t.priority}] ${t.scenario}`).join('\n')}`;
-      tag('multiline').log(summary);
     } else {
       tag('step').log(`Expanding plan: "${this.currentPlan.title}"`);
       this.currentPlan.nextIteration();
@@ -206,24 +221,19 @@ export class Planner extends PlannerBase implements Agent {
       }
     }
 
-    this.moveExecutedTestsToEnd();
     const availableStyles = Object.keys(getStyles()).join(', ');
     tag('success').log(`Planning complete! ${this.currentPlan.tests.length} tests in plan: ${this.currentPlan.title}`);
     tag('info').log(`Planning style: ${this.lastStyleName} (available: ${availableStyles})`);
 
-    if (state.url) registerPlan(state.url, this.currentPlan, feature);
+    if (state.url) registerPlan(state.url, this.currentPlan, feature, state.hash);
 
     this.registerPlanInSession(this.currentPlan);
 
     return this.currentPlan;
   }
 
-  private moveExecutedTestsToEnd(): void {
-    if (!this.currentPlan) return;
-    const pending = this.currentPlan.tests.filter((t) => t.result === null);
-    const executed = this.currentPlan.tests.filter((t) => t.result !== null);
-    this.currentPlan.tests = [...pending, ...executed];
-    this.currentPlan.notifyChange();
+  getSuite(): Suite | null {
+    return this.lastSuite;
   }
 
   private addNewTests(tests: Test[], defaultStartUrl: string): Test[] {
@@ -249,6 +259,17 @@ export class Planner extends PlannerBase implements Agent {
     return added;
   }
 
+  private getExistingTestFileScenarios(currentUrl?: string): Set<string> {
+    if (!currentUrl) return new Set<string>();
+    try {
+      this.lastSuite = new Suite(currentUrl);
+      return this.lastSuite.getActiveScenarioTitles();
+    } catch (err: any) {
+      debugLog('Failed to load existing test files: %s', err.message);
+      return new Set<string>();
+    }
+  }
+
   private cleanExperienceFlows(text: string): string | null {
     const seenTitles = new Set<string>();
     let result = text;
@@ -408,6 +429,17 @@ export class Planner extends PlannerBase implements Agent {
       }
     }
 
+    if (this.lastSuite && this.lastSuite.automatedTestCount > 0) {
+      const automatedNames = this.lastSuite.getAutomatedTestNames();
+      conversation.addUserText(dedent`
+        <existing_automated_tests>
+        The following ${automatedNames.length} tests are already implemented and automated for this URL.
+        Do not propose tests that duplicate these:
+        ${automatedNames.map((n) => `- ${n}`).join('\n')}
+        </existing_automated_tests>
+      `);
+    }
+
     if (this.currentPlan) {
       tag('step').log('Analyzing current plan to expand testing');