explorbot 0.0.1 → 0.1.0

package/src/ai/experience-compactor.ts

@@ -0,0 +1,284 @@
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import dedent from 'dedent';
+import matter from 'gray-matter';
+import { z } from 'zod';
+import type { ExperienceTracker } from '../experience-tracker.js';
+import { Observability } from '../observability.js';
+import { createDebug, log, tag } from '../utils/logger.js';
+import type { Agent } from './agent.js';
+import type { Provider } from './provider.js';
+
+const debugLog = createDebug('explorbot:experience-compactor');
+
+interface ExperienceFile {
+  filePath: string;
+  data: { url?: string; title?: string; [key: string]: any };
+  content: string;
+}
+
+interface MergeGroup {
+  pattern: string;
+  files: ExperienceFile[];
+}
+
+export class ExperienceCompactor implements Agent {
+  emoji = '🗜️';
+  private provider: Provider;
+  private experienceTracker: ExperienceTracker;
+  private MAX_LENGTH = 5000;
+
+  constructor(provider: Provider, experienceTracker: ExperienceTracker) {
+    this.provider = provider;
+    this.experienceTracker = experienceTracker;
+  }
+
+  async compactExperience(experience: string): Promise<string> {
+    if (experience.length < this.MAX_LENGTH) {
+      return experience;
+    }
+
+    const prompt = this.buildCompactionPrompt(experience);
+    const model = this.provider.getModelForAgent('experience-compactor');
+    const response = await this.provider.chat(
+      [
+        { role: 'user', content: this.getSystemPrompt() },
+        { role: 'user', content: prompt },
+      ],
+      model,
+      { telemetryFunctionId: 'experience.compact' }
+    );
+    return response.text;
+  }
+
+  async compactAllExperiences(): Promise<number> {
+    return Observability.run('experience-compactor.compactAll', { tags: ['experience-compactor'] }, async () => {
+      await this.mergeSimilarExperiences();
+
+      const experienceFiles = this.experienceTracker.getAllExperience();
+      let compactedCount = 0;
+
+      for (const experience of experienceFiles) {
+        const prevContent = experience.content;
+        const frontmatter = experience.data;
+        const compactedContent = await this.compactExperienceFile(experience.filePath);
+
+        if (prevContent !== compactedContent) {
+          const stateHash = experience.filePath.split('/').pop()?.replace('.md', '') || '';
+          this.experienceTracker.writeExperienceFile(stateHash, compactedContent, frontmatter);
+          debugLog('Experience file compacted:', experience.filePath);
+          compactedCount++;
+        }
+      }
+
+      return compactedCount;
+    });
+  }
+
+  async mergeSimilarExperiences(): Promise<number> {
+    return Observability.run('experience-compactor.merge', { tags: ['experience-compactor'] }, async () => {
+      const experienceFiles = this.experienceTracker.getAllExperience();
+      if (experienceFiles.length < 2) {
+        return 0;
+      }
+
+      const mergeGroups = await this.identifyMergeGroups(experienceFiles);
+      let mergedCount = 0;
+
+      for (const group of mergeGroups) {
+        if (group.files.length < 2) {
+          continue;
+        }
+
+        await this.mergeExperienceGroup(group);
+        mergedCount += group.files.length - 1;
+      }
+
+      return mergedCount;
+    });
+  }
+
+  private async identifyMergeGroups(files: ExperienceFile[]): Promise<MergeGroup[]> {
+    const filesWithUrl = files.filter((f) => f.data.url && !f.data.url.startsWith('~'));
+    if (filesWithUrl.length < 2) {
+      return [];
+    }
+
+    const urlList = filesWithUrl.map((f) => f.data.url as string);
+    const mergeDecisions = await this.askAiForMergeDecisions(urlList);
+
+    const groups: MergeGroup[] = [];
+    const usedFiles = new Set<string>();
+
+    for (const decision of mergeDecisions) {
+      const matchingFiles = filesWithUrl.filter((f) => decision.urls.includes(f.data.url as string) && !usedFiles.has(f.filePath));
+
+      if (matchingFiles.length >= 2) {
+        groups.push({
+          pattern: decision.pattern,
+          files: matchingFiles,
+        });
+        for (const f of matchingFiles) {
+          usedFiles.add(f.filePath);
+        }
+      }
+    }
+
+    return groups;
+  }
+
+  private async askAiForMergeDecisions(urls: string[]): Promise<{ urls: string[]; pattern: string }[]> {
+    const prompt = this.buildMergePrompt(urls);
+    const model = this.provider.getModelForAgent('experience-compactor');
+
+    const schema = z.object({
+      mergeGroups: z.array(
+        z.object({
+          urls: z.array(z.string()).describe('URLs that should be merged together'),
+          pattern: z.string().describe('Regex pattern that matches all URLs in the group, wrapped in ~ delimiters'),
+        })
+      ),
+    });
+
+    try {
+      const response = await this.provider.generateObject([{ role: 'user', content: prompt }], schema, model, {
+        telemetryFunctionId: 'experience.mergeDecisions',
+      });
+      debugLog('AI merge decisions:', response.object);
+      return response.object.mergeGroups || [];
+    } catch (error) {
+      debugLog('Error getting merge decisions from AI:', error);
+      return [];
+    }
+  }
+
+  private buildMergePrompt(urls: string[]): string {
+    return dedent`
+      Analyze these experience file URLs and identify groups that represent the same page type with dynamic URL parameters.
+
+      <urls>
+      ${urls.map((u, i) => `${i + 1}. ${u}`).join('\n')}
+      </urls>
+
+      <rules>
+      - Identify URLs that represent the same page structure but with different dynamic values (IDs, slugs, etc.)
+      - Example: /item/101, /item/102, /item/105 should be grouped with pattern ~/item/\\d+~
+      - Example: /user/john, /user/jane should be grouped with pattern ~/user/[^/]+~
+      - Only group URLs that are clearly the same page type with dynamic segments
+      - Do NOT group unrelated pages
+      - Return regex patterns wrapped in ~ delimiters (e.g., ~/path/\\d+~)
+      - If no URLs should be merged, return empty mergeGroups array
+      </rules>
+
+      Return JSON with mergeGroups array. Each group should have:
+      - urls: array of URLs that should be merged
+      - pattern: regex pattern (wrapped in ~) that matches all URLs in the group
+    `;
+  }
+
+  private async mergeExperienceGroup(group: MergeGroup): Promise<void> {
+    const [targetFile, ...sourceFiles] = group.files;
+    const combinedContent = group.files.map((f) => f.content).join('\n\n---\n\n');
+
+    const targetStateHash = targetFile.filePath.split('/').pop()?.replace('.md', '') || '';
+    const newFrontmatter = {
+      ...targetFile.data,
+      url: group.pattern,
+      mergedFrom: group.files.map((f) => f.data.url),
+    };
+
+    this.experienceTracker.writeExperienceFile(targetStateHash, combinedContent, newFrontmatter);
+    log(`Merged ${group.files.length} experience files into ${targetFile.filePath}`);
+    debugLog('New URL pattern:', group.pattern);
+
+    for (const sourceFile of sourceFiles) {
+      try {
+        unlinkSync(sourceFile.filePath);
+        debugLog('Deleted merged source file:', sourceFile.filePath);
+      } catch (error) {
+        debugLog('Error deleting source file:', error);
+      }
+    }
+  }
+
+  async compactExperienceFile(filePath: string): Promise<string> {
+    try {
+      const fileContent = readFileSync(filePath, 'utf8');
+      const parsed = matter(fileContent);
+
+      if (parsed.content.length < this.MAX_LENGTH) {
+        return parsed.content;
+      }
+      debugLog('Experience file to compact:', filePath);
+
+      const text = await this.compactExperience(parsed.content);
+
+      tag('substep').log('Experience file compacted:', filePath);
+      debugLog('Experience file compacted:', text);
+
+      return text;
+    } catch (error) {
+      debugLog('Error compacting experience file:', error);
+      return '';
+    }
+  }
+
+  private getSystemPrompt(): string {
+    const customPrompt = this.provider.getSystemPromptForAgent('experience-compactor', '*');
+    return dedent`
+      You are an expert test automation engineer specializing in CodeceptJS.
+      Your task is to compact experience data from test automation attempts into clean markdown format.
+
+      ${customPrompt || ''}
+    `;
+  }
+
+  private buildCompactionPrompt(content: string): string {
+    return dedent`
+      <rules>
+      - Use markdown headers only (##, ###) - NO XML tags or wrappers in output
+      - Merge similar flows to remove duplicates
+      - Keep output under ${this.MAX_LENGTH} characters
+      - Be explicit and short - no proposals or explanations
+
+      KEEP only:
+      - Positive flows that complete a business action (create, edit, delete, navigate)
+      - Reusable interaction patterns (opening dropdowns, filling forms, using pickers)
+      - Discovery lines (> prefixed) that document UI elements appearing at each step — keep at most 5 per flow step
+      - Working CodeceptJS code for common interactions
+
+      REMOVE:
+      - All FAILED entries
+      - Edge-case and negative flows (empty values, disabled buttons, validation errors, boundary testing)
+      - Flows whose purpose is to test what happens when something goes wrong
+      - All I.amOnPage, I.grab, I.see, I.seeElement, I.dontSee calls
+      - Duplicate approaches that achieve the same goal
+      </rules>
+
+      <output_format>
+      Use this markdown structure:
+
+      ## Flows
+
+      For each unique positive flow (merge duplicates):
+      - Purpose: what was accomplished
+      \`\`\`js
+      // working code
+      \`\`\`
+
+      ## Reusable Actions
+
+      For each reusable interaction pattern not covered by flows:
+      - Purpose: what was accomplished
+      \`\`\`js
+      // working code
+      \`\`\`
+      </output_format>
+
+      <context>
+      ${content}
+      </context>
+
+      Compact this experience data following the format above.
+    `;
+  }
+}

package/src/ai/fisherman-tools.ts

@@ -0,0 +1,181 @@
+import { tool } from 'ai';
+import dedent from 'dedent';
+import { z } from 'zod';
+import type { ApiClient } from '../api/api-client.ts';
+import type { RequestStore } from '../api/request-store.ts';
+import { extractEndpointDefinition } from '../api/spec-reader.ts';
+import { tag } from '../utils/logger.ts';
+
+export function createFishermanTools(apiClient: ApiClient, requestStore: RequestStore, opts: { spec?: any; baseEndpoint?: string }) {
+  let finished = false;
+  let result: FishermanResult = { success: false, summary: '', created: [], failed: [] };
+
+  const getResult = () => result;
+  const isFinished = () => finished;
+
+  const tools = {
+    getEndpointSpec: tool({
+      description: dedent`
+        Get the request specification for an endpoint.
+        Returns the request body example from a previously captured request, or OpenAPI spec definition.
+        Call this before making a request to an endpoint you haven't used before.
+      `,
+      inputSchema: z.object({
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
+        path: z.string().describe('Endpoint path, e.g. /suites'),
+      }),
+      execute: async ({ method, path }) => {
+        tag('step').log(`Fisherman: spec lookup ${method} ${path}`);
+
+        const captured = requestStore.findCapturedRequest(method, path);
+        if (captured) {
+          return {
+            source: 'captured',
+            method: captured.method,
+            path: captured.path,
+            status: captured.status,
+            requestBody: captured.requestBody || 'no body',
+          };
+        }
+
+        if (opts.spec) {
+          try {
+            const definition = extractEndpointDefinition(opts.spec, path, opts.baseEndpoint);
+            return { source: 'spec', definition };
+          } catch (err: any) {
+            return { source: 'none', error: err.message };
+          }
+        }
+
+        return { source: 'none', error: `No spec found for ${method} ${path}` };
+      },
+    }),
+
+    request: tool({
+      description: dedent`
+        Make an HTTP request to the API.
+        Returns status, timing, and auto-extracted IDs and names from the response.
+      `,
+      inputSchema: z.object({
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
+        path: z.string().describe('API path (e.g., /suites, /suites/1)'),
+        body: z.any().optional().describe('Request body (JSON object)'),
+        queryParams: z.record(z.string(), z.string()).optional().describe('Query parameters'),
+      }),
+      execute: async (input) => {
+        tag('step').log(`Fisherman: ${input.method} ${input.path}`);
+
+        const reqResult = await apiClient.request({
+          method: input.method,
+          path: input.path,
+          body: input.body,
+          queryParams: input.queryParams,
+        });
+
+        requestStore.addMadeRequest(reqResult);
+
+        if (reqResult.error) {
+          tag('error').log(`Fisherman: ${input.method} ${input.path} > Network error: ${reqResult.error}`);
+          return { success: false, error: reqResult.error };
+        }
+
+        const statusLine = `${reqResult.status} ${reqResult.statusText}`;
+
+        if (reqResult.status >= 400) {
+          tag('error').log(`Fisherman: ${input.method} ${input.path} > ${statusLine}`);
+          return {
+            success: false,
+            status: reqResult.status,
+            statusText: reqResult.statusText,
+            errorPreview: reqResult.rawResponseBody.substring(0, 300),
+          };
+        }
+
+        const extracted = extractKeyFields(reqResult.responseBody);
+        tag('success').log(`Fisherman: ${input.method} ${input.path} > ${statusLine}`);
+        return {
+          success: true,
+          status: reqResult.status,
+          ...extracted,
+        };
+      },
+    }),
+
+    finish: tool({
+      description: 'Report completion of data preparation. Call when all requested items have been created.',
+      inputSchema: z.object({
+        summary: z.string().describe('Summary of what was created'),
+        created: z
+          .array(
+            z.object({
+              type: z.string().describe('Item type (e.g., suite, test, label)'),
+              id: z.union([z.string(), z.number()]).optional().describe('Created item ID'),
+              title: z.string().optional().describe('Created item name/title'),
+            })
+          )
+          .describe('List of successfully created items'),
+        failed: z
+          .array(
+            z.object({
+              type: z.string().describe('Item type that failed'),
+              reason: z.string().describe('Why it failed'),
+            })
+          )
+          .optional()
+          .describe('List of items that could not be created'),
+      }),
+      execute: async ({ summary, created, failed }) => {
+        tag('success').log(`Fisherman done: ${summary}`);
+        finished = true;
+        result = { success: true, summary, created, failed: failed || [] };
+        return { finished: true };
+      },
+    }),
+
+    stop: tool({
+      description: 'Abort data preparation when it cannot be completed.',
+      inputSchema: z.object({
+        reason: z.string().describe('Why preparation cannot continue'),
+      }),
+      execute: async ({ reason }) => {
+        tag('warning').log(`Fisherman stopped: ${reason}`);
+        finished = true;
+        result = { success: false, summary: reason, created: [], failed: [] };
+        return { stopped: true };
+      },
+    }),
+  };
+
+  return { tools, getResult, isFinished };
+}
+
+function extractKeyFields(body: any, result: Record<string, any> = {}, depth = 0): Record<string, any> {
+  if (!body || typeof body !== 'object' || depth > 5) return result;
+
+  if (Array.isArray(body)) {
+    if (body.length > 0) extractKeyFields(body[0], result, depth + 1);
+    return result;
+  }
+
+  for (const [key, value] of Object.entries(body)) {
+    if (value === null || value === undefined) continue;
+    if (typeof value === 'object') {
+      extractKeyFields(value, result, depth + 1);
+      continue;
+    }
+    if (key === 'id' || key === '_id' || key === 'uuid' || key.endsWith('_id')) {
+      result[key] ??= value;
+    }
+    if (key === 'name' || key === 'title' || key === 'status') {
+      result[key] ??= String(value).slice(0, 100);
+    }
+  }
+  return result;
+}
+
+export interface FishermanResult {
+  success: boolean;
+  summary: string;
+  created: Array<{ type: string; id?: string | number; title?: string }>;
+  failed: Array<{ type: string; reason: string }>;
+}

package/src/ai/fisherman.ts

@@ -0,0 +1,223 @@
+import dedent from 'dedent';
+import type { ApiClient } from '../api/api-client.ts';
+import type { RequestStore } from '../api/request-store.ts';
+import { listAllEndpoints } from '../api/spec-reader.ts';
+import { createDebug, tag } from '../utils/logger.ts';
+
+const debugLog = createDebug('explorbot:fisherman');
+import { loop } from '../utils/loop.ts';
+import type { Agent } from './agent.ts';
+import { type FishermanResult, createFishermanTools } from './fisherman-tools.ts';
+import type { Provider } from './provider.ts';
+
+const MAX_ITERATIONS = 15;
+const MAX_TOOL_ROUNDTRIPS = 5;
+
+export class Fisherman implements Agent {
+  emoji = '🎣';
+  private provider: Provider;
+  private apiClient: ApiClient;
+  private requestStore: RequestStore;
+  private specLoader: () => Promise<any | null>;
+  private cookieProvider: () => Promise<Record<string, string>>;
+  private configHeaders: Record<string, string>;
+  private sessionName?: string;
+  private baseEndpoint: string;
+  private spec: any | null = null;
+  private mode: 'replicate' | 'achieve' | 'disabled' = 'disabled';
+  private hasApiConfig: boolean;
+
+  constructor(provider: Provider, apiClient: ApiClient, requestStore: RequestStore, specLoader: () => Promise<any | null>, baseEndpoint: string, cookieProvider: () => Promise<Record<string, string>>, configHeaders: Record<string, string> = {}, hasApiConfig = false) {
+    this.provider = provider;
+    this.apiClient = apiClient;
+    this.requestStore = requestStore;
+    this.specLoader = specLoader;
+    this.baseEndpoint = baseEndpoint;
+    this.cookieProvider = cookieProvider;
+    this.configHeaders = configHeaders;
+    this.hasApiConfig = hasApiConfig;
+    this.mode = hasApiConfig ? 'achieve' : 'replicate';
+  }
+
+  isAvailable(): boolean {
+    return this.mode !== 'disabled';
+  }
+
+  getMode(): string {
+    return this.mode;
+  }
+
+  async ensureReady(scopeUrl?: string): Promise<void> {
+    await this.detectMode(scopeUrl);
+    this.spec ??= await this.specLoader();
+    debugLog(`ensureReady: mode=${this.mode}, scope=${scopeUrl}`);
+  }
+
+  getEndpointList(scopeUrl?: string): string {
+    return this.buildEndpointList(scopeUrl);
+  }
+
+  async prepareData(instructions: string, scopeUrl?: string, sessionName?: string): Promise<FishermanResult> {
+    this.sessionName = sessionName;
+    tag('info').log(`Fisherman [${this.mode}]: preparing data — ${instructions}`);
+
+    await this.ensureReady(scopeUrl);
+
+    if (this.mode === 'disabled') {
+      debugLog('disabled — no data for scope');
+      return { success: false, summary: 'No API data available for this scope', created: [], failed: [] };
+    }
+
+    const endpointList = this.buildEndpointList(scopeUrl);
+    debugLog(`endpoints:\n${endpointList || '(none)'}`);
+
+    if (!endpointList) {
+      tag('warning').log('Fisherman: no endpoints available');
+      this.mode = 'disabled';
+      return { success: false, summary: 'No API endpoints available', created: [], failed: [] };
+    }
+
+    await this.refreshAuth();
+    debugLog(`auth headers: ${Object.keys(this.apiClient.getHeaders()).join(', ')}`);
+
+    const { tools, getResult, isFinished } = createFishermanTools(this.apiClient, this.requestStore, {
+      spec: this.spec,
+      baseEndpoint: this.baseEndpoint,
+    });
+
+    const conversation = this.provider.startConversation(this.buildSystemPrompt(endpointList, scopeUrl), 'fisherman');
+    conversation.addUserText(this.buildTaskPrompt(instructions));
+
+    await loop(
+      async ({ stop, iteration }) => {
+        debugLog(`iteration ${iteration}`);
+        const invokeResult = await this.provider.invokeConversation(conversation, tools, {
+          maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
+          toolChoice: 'required',
+          agentName: 'fisherman',
+        });
+        debugLog(`iteration ${iteration} done, text: ${invokeResult?.response?.text?.slice(0, 200) || '(none)'}`);
+
+        if (isFinished()) {
+          stop();
+          return;
+        }
+
+        if (iteration >= MAX_ITERATIONS) {
+          tag('warning').log('Fisherman: max iterations reached');
+          stop();
+        }
+      },
+      {
+        maxAttempts: MAX_ITERATIONS,
+        observability: {
+          name: `fisherman: ${instructions.slice(0, 50)}`,
+          agent: 'fisherman',
+          sessionId: this.sessionName,
+        },
+        catch: async ({ error, stop }) => {
+          debugLog(`error: ${error.message}`);
+          tag('warning').log(`Fisherman error: ${error.message}`);
+          stop();
+        },
+      }
+    );
+
+    const result = getResult();
+    tag('info').log(`Fisherman result: ${result.summary}`);
+    return result;
+  }
+
+  private async detectMode(scopeUrl?: string): Promise<void> {
+    if (this.hasApiConfig) {
+      this.mode = 'achieve';
+      debugLog('achieve mode — api config present');
+      return;
+    }
+
+    this.requestStore.loadFromDisk();
+    const allRequests = this.requestStore.getCapturedRequests();
+    debugLog(`total stored requests: ${allRequests.length}, scope: ${scopeUrl}`);
+
+    if (allRequests.length > 0) {
+      this.mode = 'replicate';
+      return;
+    }
+
+    this.mode = 'disabled';
+  }
+
+  private async refreshAuth(): Promise<void> {
+    const cookies = await this.cookieProvider();
+    if (Object.keys(cookies).length > 0) {
+      this.apiClient.setHeaders(cookies);
+    }
+
+    const xhrHeaders = this.requestStore.extractAuthHeaders();
+    if (Object.keys(xhrHeaders).length > 0) {
+      this.apiClient.setHeaders(xhrHeaders);
+    }
+
+    if (Object.keys(this.configHeaders).length > 0) {
+      this.apiClient.setHeaders(this.configHeaders);
+    }
+  }
+
+  private buildEndpointList(scopeUrl?: string): string {
+    if (this.mode === 'achieve' && this.spec) {
+      const specEndpoints = listAllEndpoints(this.spec, this.baseEndpoint);
+      if (specEndpoints) return specEndpoints;
+    }
+
+    let writeRequests = this.requestStore.getWriteRequestsForScope(scopeUrl || '/');
+    if (writeRequests.length === 0) {
+      writeRequests = this.requestStore.getWriteRequestsForScope('/');
+    }
+
+    const seen = new Set<string>();
+    const lines: string[] = [];
+
+    for (const req of writeRequests) {
+      const key = `${req.method} ${req.path}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      lines.push(key);
+    }
+
+    return lines.join('\n');
+  }
+
+  private buildSystemPrompt(endpointList: string, scopeUrl?: string): string {
+    const scopeBlock = scopeUrl ? `\n\nSCOPE: You are operating within ${scopeUrl}.\nAll created items must belong to this scope.` : '';
+
+    return dedent`
+      You are Fisherman — a data preparation agent. You create test data by making API requests.
+
+      AVAILABLE ENDPOINTS:
+      ${endpointList}
+      ${scopeBlock}
+
+      WORKFLOW:
+      1. Call getEndpointSpec to see the request body example for the endpoint
+      2. Make requests — the response automatically extracts IDs, names, and status fields
+      3. Use extracted IDs to chain requests (e.g., create suite, use its id to create tests in it)
+      4. Call finish with a summary and IDs of all created items
+
+      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 realistic but unique data for each item (vary names, titles)
+    `;
+  }
+
+  private buildTaskPrompt(instructions: string): string {
+    return dedent`
+      Prepare the following test data:
+
+      ${instructions}
+
+      Execute the necessary API requests to create this data. When done, call finish with the summary.
+    `;
+  }
+}