testronaut 1.2.4 → 1.3.0

package/tools/domControl.js

@@ -1,3 +1,35 @@
+/**
+ * domControl.js
+ * --------------
+ * Purpose:
+ *   Centralized DOM-normalization helpers for Testronaut.
+ *   These functions take a Cheerio instance and aggressively strip,
+ *   normalize, and compress HTML so it’s cheaper and clearer for LLMs.
+ *
+ * Responsibilities:
+ *   - Remove non-content tags (scripts, styles, iframes, etc.) and noisy attributes.
+ *   - Collapse overly long lists/sections into truncated markers.
+ *   - Reduce repeated div blocks to a representative sample.
+ *   - Strip obfuscated/utility CSS classes that don’t help reasoning.
+ *   - Minify whitespace in text nodes without breaking semantics.
+ *
+ * Related tests:
+ *   Located in `tests/toolsTests/domControl.test.js`
+ *
+ * Used by:
+ *   - tools/chromeBrowser.js (get_dom) before sending DOM to the LLM
+ *   - Any future DOM-inspection tools that need a compact, semantic HTML view
+ */
+
+/**
+ * Remove tags and attributes that are unlikely to help LLM reasoning.
+ * - Strips: script, style, meta, link, noscript, iframe, canvas, svg
+ * - Keeps only a safe whitelist of attributes on remaining elements.
+ * - Removes HTML comments.
+ *
+ * @param {$} $ - Cheerio root
+ * @returns {$} same Cheerio instance for chaining
+ */
 export const removeNonContentTags = async ($) => {
   $('script, style, meta, link, noscript, iframe, canvas, svg').remove();
   
@@ -34,6 +66,19 @@ export const removeNonContentTags = async ($) => {
   return $;
 }
 
+/**
+ * Collapse very long lists and container sections.
+ * - For <ul>/<ol>, keeps the first `limit` <li> children and appends a
+ *   sentinel <li data-collapsed="true">[...truncated]</li>.
+ * - For <div>/<section>, keeps the first `limit` child elements and appends
+ *   a sentinel <div data-collapsed="true">[...truncated]</div>.
+ *
+ * This is meant to cut down giant feeds/tables while preserving structure.
+ *
+ * @param {$} $ - Cheerio root
+ * @param {number} [limit=10] - Max children to preserve per container
+ * @returns {$} same Cheerio instance for chaining
+ */
 export const collapseLongContent = async ($, limit = 10) => {
   $('ul, ol').each((_, el) => {
     const $el = $(el);
@@ -56,6 +101,18 @@ export const collapseLongContent = async ($, limit = 10) => {
   });
 }
 
+/**
+ * Extract logical sections of the page into named chunks.
+ * - Returns an object keyed by region: header, nav, main, footer, aside, body.
+ * - Each key maps to the inner HTML of that section (or '' if missing).
+ * - If `focus` is a non-empty array, only the requested keys are returned.
+ *
+ * This is a structural pre-step for “header/nav/main/…” focus slicing.
+ *
+ * @param {$} $ - Cheerio root
+ * @param {string[]} [focus] - Optional list of section keys to keep
+ * @returns {Record<string,string>} map of sectionName -> html
+ */
 export const chunkBySection = async ($, focus) => {
   const chunks = {
     header: $('header').html() || '',
@@ -85,6 +142,18 @@ export const chunkBySection = async ($, focus) => {
 
 }
 
+/**
+ * Reduce repeated sibling <div> blocks that share the same class name.
+ * - For each parent <body> or <div>, group child divs by `class`.
+ * - If a group exceeds `maxAllowed`, remove the extras and append a
+ *   sentinel <div data-collapsed="true" data-class="...">[...truncated]</div>.
+ *
+ * This keeps a few representative cards/rows and collapses the rest.
+ *
+ * @param {$} $ - Cheerio root
+ * @param {number} [maxAllowed=3] - Max sibling divs per class to keep
+ * @returns {$} same Cheerio instance for chaining
+ */
 export function reduceRepeatedDivs($, maxAllowed = 3) {
   $('body, div').each((_, parentEl) => {
     const $parent = $(parentEl);
@@ -117,8 +186,17 @@ export function reduceRepeatedDivs($, maxAllowed = 3) {
 }
 
 /**
- * Remove obfuscated or hashed class names from a DOM string.
- * Criteria: class names with high entropy (random letters/numbers), or very short length
+ * Remove obfuscated or hashed class names from elements.
+ * Criteria for stripping:
+ *   - Very short classes (len <= 2).
+ *   - Lowercase+numeric hashes like "a1b2c3".
+ *   - Mixed-case hashes with digits like "AbCdE1".
+ *
+ * The goal is to keep semantic class names (e.g. "btn-primary") and drop
+ * ones that look like auto-generated hashes.
+ *
+ * @param {$} $ - Cheerio root
+ * @returns {$} same Cheerio instance for chaining
  */
 export function removeObfuscatedClassNames($) {
   $('[class]').each((_, el) => {
@@ -141,7 +219,16 @@ export function removeObfuscatedClassNames($) {
 }
 
 /**
- * Remove known auto-generated or utility classes (e.g., Tailwind/MUI/CSS-in-JS)
+ * Remove known auto-generated / utility CSS classes (Tailwind, MUI, etc.).
+ * - Matches a broad set of patterns for spacing, layout, color, breakpoint
+ *   variants, and other low-signal utility styles.
+ * - Preserves any remaining classes that don’t match those patterns.
+ *
+ * This keeps semantic-ish classes (e.g., "btn-primary", "modal-root")
+ * while stripping the utility noise that doesn’t help the LLM.
+ *
+ * @param {$} $ - Cheerio root
+ * @returns {$} same Cheerio instance for chaining
  */
 export function removeAutoGeneratedClasses($) {
   // Regex patterns for utility classes, internal prefixes, and other noise
@@ -168,3 +255,42 @@ export function removeAutoGeneratedClasses($) {
 
   return $;
 }
+
+/**
+ * Minify DOM by collapsing whitespace in text nodes.
+ * - Collapses all runs of whitespace to a single space.
+ * - Preserves whitespace in <pre>, <code>, <textarea> (where formatting matters).
+ * - Keeps at least one space for purely-whitespace nodes to avoid jamming
+ *   words from adjacent nodes together.
+ *
+ * This is intended as a low-risk token saver before sending DOM to the LLM.
+ *
+ * @param {$} $ - Cheerio root
+ * @returns {$} same Cheerio instance for chaining
+ */
+export function minifyDomWhitespace($) {
+  const PRESERVE_SELECTOR = 'pre, code, textarea';
+
+  $('*').contents().each(function () {
+    if (this.type !== 'text') return;
+
+    // Skip any text node living inside pre/code/textarea
+    if ($(this).closest(PRESERVE_SELECTOR).length) return;
+
+    const orig = this.data || '';
+    if (!orig) return;
+
+    // Collapse all whitespace to single spaces
+    const collapsed = orig.replace(/\s+/g, ' ');
+
+    if (!orig.trim()) {
+      // Pure whitespace → keep a single space so adjacent words don't concatenate
+      this.data = ' ';
+    } else {
+      // Normal text → trim ends, keep single internal spaces
+      this.data = collapsed.trim();
+    }
+  });
+
+  return $;
+}

package/tools/tokenControl.js

@@ -35,6 +35,7 @@ import { wait } from './turnLoopUtils.js';
  */
 const DEFAULT_LIMITS = [
   // ── OpenAI (newer first) ────────────────────────────────────────────────
+  { test: /^gpt-5.1(-|$)/i,             tpm: 120000 },
   { test: /^gpt-5(-|$)/i,               tpm:  90000 },
   { test: /^gpt-5-mini(-|$)/i,          tpm: 240000 },
   { test: /^gpt-5-nano(-|$)/i,          tpm: 600000 },
@@ -71,6 +72,13 @@ const warnedModels = new Set();
  *  - o200k_base for modern, long-context families (OpenAI 4o/4.1/5, Gemini 2.5, O*)
  *  - cl100k_base as a broad fallback
  */
+/**
+ * Resolve the best-effort tokenizer for a model.
+ * Falls back to o200k_base for modern long-context models and cl100k_base otherwise.
+ *
+ * @param {string} model - Model identifier used to pick an encoding.
+ * @returns {import('@dqbd/tiktoken').Tiktoken | null} tokenizer or null on failure
+ */
 function getTokenizer(model) {
   try {
     return encoding_for_model(model);
@@ -228,6 +236,7 @@ export const tokenUseCoolOff = async (totalTokensUsed, turnTimestamps, model) =>
  * Record tokens for the current turn in the rolling window.
  * @param {Array<[number,number]>} turnTimestamps
  * @param {number} tokensUsed
+ * @returns {void}
  */
 export const recordTokenUsage = (turnTimestamps, tokensUsed) => {
   const now = Date.now();
@@ -272,8 +281,11 @@ const getDynamicBackoffMs = async (turnTimestamps, tokenLimit) => {
 };
 
 
-// Test-only helper to clear internal state between tests
+/**
+ * Test-only helper to clear internal state between runs.
+ * @returns {void}
+ */
 export function __resetTokenControlForTests() {
   liveLimits.clear();
   warnedModels.clear();
-}
+}

package/tools/toolSchema.js

@@ -285,6 +285,107 @@ const toolsSchema = [
         required: []
       }
     }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'set_ground_control_state',
+      description: 'Update stable mission facts for Ground Control: app URL, current page role, login status, and constraints. Use this when you learn something that should remain true across future turns and should not be forgotten.',
+      parameters: {
+        type: 'object',
+        properties: {
+          app: {
+            type: 'object',
+            description: 'App/URL related state. Only send fields you are certain about.',
+            properties: {
+              baseUrl: {
+                type: 'string',
+                description: 'Canonical base URL of the app under test, e.g. "https://demo.testronaut.app".'
+              },
+              currentUrl: {
+                type: 'string',
+                description: 'Current page URL after navigation.'
+              },
+              routeRole: {
+                type: 'string',
+                description: 'Short label for the current page role, e.g. "login", "chat", "dashboard".'
+              }
+            },
+            additionalProperties: false
+          },
+          session: {
+            type: 'object',
+            description: 'User/session related facts.',
+            properties: {
+              loggedIn: {
+                type: 'boolean',
+                description: 'Whether the user is currently logged in.'
+              },
+              userLabel: {
+                type: 'string',
+                description: 'Short label for the user account, e.g. "Demo user", "Buzz Aldrin".'
+              },
+              tenant: {
+                type: 'string',
+                description: 'Tenant or workspace name, if applicable.'
+              }
+            },
+            additionalProperties: false
+          },
+          navigation: {
+            type: 'object',
+            description: 'Navigation-related state.',
+            properties: {
+              currentLabel: {
+                type: 'string',
+                description: 'Short human label for the current page, e.g. "Main chat page".'
+              }
+            },
+            additionalProperties: false
+          },
+          constraints: {
+            type: 'object',
+            description: 'Mission or environment constraints.',
+            properties: {
+              stayWithinBaseUrl: {
+                type: 'boolean',
+                description: 'If true, do not navigate outside the app base URL unless explicitly instructed.'
+              }
+            },
+            additionalProperties: false
+          }
+        },
+        additionalProperties: false
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'record_mission_telemetry',
+      description: 'Record a small, durable observation for the mission log: breadcrumbs, assertions, issues, or general notes for Ground Control.',
+      parameters: {
+        type: 'object',
+        properties: {
+          kind: {
+            type: 'string',
+            enum: ['breadcrumb', 'assertion', 'issue', 'note'],
+            description: 'Type of observation: navigation breadcrumb, assertion, discovered issue, or general note.'
+          },
+          text: {
+            type: 'string',
+            description: 'Short description of the observation in 1–2 sentences.'
+          },
+          status: {
+            type: 'string',
+            enum: ['passed', 'failed', 'n/a'],
+            description: 'Optional status for assertions or issues.'
+          }
+        },
+        required: ['kind', 'text'],
+        additionalProperties: false
+      }
+    }
   }
 ];
 

package/tools/turnLoopUtils.js

@@ -20,7 +20,6 @@ export const wait = (ms) => new Promise(res => setTimeout(res, ms));
 export function validateAndInsertMissingToolResponses(messages, options = {}) {
   const { insertPlaceholders = true } = options;
   const missingResponses = [];
-
   for (let i = 0; i < messages.length; i++) {
     const msg = messages[i];
     if (msg.role === 'assistant' && msg.tool_calls?.length) {