testronaut 1.3.0 → 1.3.2

package/README.md

@@ -178,6 +178,8 @@ Each includes:
 - **LLMs** for reasoning, DOM parsing, and tool use  
 - **Token throttling** + adaptive cooldowns  
 - **Extensible architecture** for custom tools and workflows  
+- **DOM trimming controls** to cap list sizes (env `TESTRONAUT_DOM_LIST_LIMIT` or config `dom.listItemLimit`; use `all` cautiously—it can spike token use)
+- **Resource guard** to ensure full list/table downloads (config `resourceGuard` or env `TESTRONAUT_RESOURCE_*`)
 
 ---
 

package/bin/cli.js

@@ -29,7 +29,7 @@
  * Test strategy:
  *   To test pure helpers without running the whole CLI, we export a tiny test bundle:
  *     export const __test__ = { guessMimeType, safeJoin, findLatestReportPair, pkgManagerForCwd }
- *   See tests in tests/cliTests/cli.helpers.test.js
+ *   See tests in tests/toolsTests/cli.helpers.test.js
  */
 
 import fs from 'fs';
@@ -47,6 +47,7 @@ import { promisify } from 'util';
 const exec = promisify(execCmd);
 import url from 'url';
 import { ensureBrowsers } from '../tools/playwrightSetup.js';
+import { discoverMissionFiles } from '../core/missionDiscovery.js';
 
 // Keep PW browsers inside the project to avoid global cache skew
 process.env.PLAYWRIGHT_BROWSERS_PATH = process.env.PLAYWRIGHT_BROWSERS_PATH || '0';
@@ -60,6 +61,11 @@ const apiBase = 'http://api.testronaut.app'; // Replace with your actual API bas
 
 const args = process.argv.slice(2);
 
+/**
+ * Read a JSONL steps file into an array of objects.
+ * @param {string} p
+ * @returns {object[]|null}
+ */
 function readJsonlSteps(p) {
   if (!p || !fs.existsSync(p)) return null;
   const lines = fs.readFileSync(p, 'utf8').split(/\r?\n/).filter(Boolean);
@@ -73,21 +79,27 @@ function readJsonlSteps(p) {
 /**
  * Merge duplicate turns without losing information.
  * Strategy:
- *  - Keep the latest **non-empty** version for a given turn if both exist
+ *  - Keep the latest **non-empty** version for a given (turn,retry) pair
  *  - If both are non-empty, keep the later one (last write wins)
  *  - Preserve original order by line index as a tiebreaker
+ *
+ * @param {Array} steps
+ * @returns {Array}
  */
 function mergeDuplicateTurns(steps) {
   const out = [];
-  const byTurn = new Map(); // turn -> index in out
+  const byKey = new Map(); // composite key -> index in out
   for (const s of steps) {
     const turn = Number.isFinite(s.turn) ? s.turn : out.length;
+    const attempt = Number.isFinite(s.retryAttempt) ? s.retryAttempt : 1;
     const hasEvents = Array.isArray(s.events) && s.events.length > 0;
-    if (!byTurn.has(turn)) {
+    const key = `${turn}::${attempt}`;
+
+    if (!byKey.has(key)) {
       out.push(s);
-      byTurn.set(turn, out.length - 1);
+      byKey.set(key, out.length - 1);
     } else {
-      const idx = byTurn.get(turn);
+      const idx = byKey.get(key);
       const existing = out[idx];
       const existingHasEvents = Array.isArray(existing.events) && existing.events.length > 0;
       // Prefer the one with events; if both have events, prefer the newer (s)
@@ -101,11 +113,28 @@ function mergeDuplicateTurns(steps) {
       }
     }
   }
-  // stable sort by `turn` ascending, then by original order via array index already preserved
-  out.sort((a, b) => (a.turn ?? 0) - (b.turn ?? 0));
+  // stable sort by `turn` then `retryAttempt`, then by original order
+  out.sort((a, b) => {
+    const ta = a.turn ?? 0;
+    const tb = b.turn ?? 0;
+    if (ta !== tb) return ta - tb;
+    const ra = Number.isFinite(a.retryAttempt) ? a.retryAttempt : 1;
+    const rb = Number.isFinite(b.retryAttempt) ? b.retryAttempt : 1;
+    if (ra !== rb) return ra - rb;
+    return 0;
+  });
   return out;
 }
 
+// Expose a small bundle for unit tests (helper-only; not the CLI flow)
+export const __test__ = {
+  guessMimeType,
+  safeJoin,
+  findLatestReportPair,
+  mergeDuplicateTurns,
+  readJsonlSteps,
+};
+
 // Look for --model=<id> or --model <id>
 let modelOverride;
 const modelFlagIndex = args.findIndex(a => a === '--model' || a.startsWith('--model='));
@@ -125,6 +154,48 @@ if (modelFlagIndex >= 0) {
   args.splice(modelFlagIndex, modelOverride ? 2 : 1);
 }
 
+// Look for --debug / --debug=<bool> / --no-debug
+// Normalize CLI boolean strings into true/false/null for optional flags.
+const parseBool = (v) => {
+  const lower = String(v ?? '').trim().toLowerCase();
+  if (!lower) return null;
+  if (['1', 'true', 'yes', 'on'].includes(lower)) return true;
+  if (['0', 'false', 'no', 'off'].includes(lower)) return false;
+  return null;
+};
+__test__.parseBool = parseBool;
+
+let debugOverride;
+let debugConsumesNext = false;
+const debugFlagIndex = args.findIndex(a =>
+  a === '--debug' ||
+  a.startsWith('--debug=') ||
+  a === '--no-debug'
+);
+if (debugFlagIndex >= 0) {
+  const rawArg = args[debugFlagIndex];
+  if (rawArg.includes('=')) {
+    debugOverride = parseBool(rawArg.split('=')[1]);
+  } else if (rawArg === '--no-debug') {
+    debugOverride = false;
+  } else if (args[debugFlagIndex + 1] && !args[debugFlagIndex + 1].startsWith('-')) {
+    debugOverride = parseBool(args[debugFlagIndex + 1]);
+    debugConsumesNext = true;
+  } else {
+    debugOverride = true; // bare --debug enables it
+  }
+
+  if (debugOverride !== null) {
+    process.env.TESTRONAUT_DEBUG = debugOverride ? '1' : '0';
+    console.log(`🛠️ Debug mode ${debugOverride ? 'enabled' : 'disabled'} (TESTRONAUT_DEBUG=${process.env.TESTRONAUT_DEBUG})`);
+  } else {
+    console.warn('⚠️ Invalid --debug value. Use true/false, 1/0, yes/no.');
+  }
+
+  const consume = 1 + (debugConsumesNext && debugOverride !== null ? 1 : 0);
+  args.splice(debugFlagIndex, consume);
+}
+
 // Look for --turns=<n> or --turns <n>
 let turnsOverride;
 const turnsFlagIndex = args.findIndex(a => a === '--turns' || a.startsWith('--turns='));
@@ -149,7 +220,36 @@ if (turnsFlagIndex >= 0) {
   args.splice(turnsFlagIndex, turnsOverride ? 2 : 1);
 }
 
-const missionsDir = path.resolve(process.cwd(), 'missions');
+// Look for --retry_limit / --retry-limit
+let retryOverride;
+const retryFlagIndex = args.findIndex(a =>
+  a === '--retry_limit' ||
+  a.startsWith('--retry_limit=') ||
+  a === '--retry-limit' ||
+  a.startsWith('--retry-limit=')
+);
+if (retryFlagIndex >= 0) {
+  const rawArg = args[retryFlagIndex];
+  if (rawArg.includes('=')) {
+    retryOverride = rawArg.split('=')[1];
+  } else if (args[retryFlagIndex + 1]) {
+    retryOverride = args[retryFlagIndex + 1];
+  }
+
+  if (retryOverride) {
+    const n = Number(retryOverride.trim());
+    if (Number.isFinite(n)) {
+      const clamped = Math.min(10, Math.max(1, n));
+      process.env.TESTRONAUT_RETRY_LIMIT = String(clamped);
+      console.log(`🔁 Retry limit override: ${process.env.TESTRONAUT_RETRY_LIMIT} (allowed 1-10)`);
+    } else {
+      console.warn(`⚠️ Invalid --retry_limit value "${retryOverride}". Ignoring.`);
+    }
+  }
+
+  // Remove flag & value so they aren’t treated as filenames
+  args.splice(retryFlagIndex, retryOverride ? 2 : 1);
+}
 
 const allResults = [];
 const runId = `run_${Date.now()}`;
@@ -169,7 +269,9 @@ Usage:
 Options:
   --init                    Scaffold project folders and a welcome mission
   --turns=<n>               Override max turns for this run (e.g., --turns=30)
+  --debug[=<bool>]          Enable verbose debug logs (or set TESTRONAUT_DEBUG=1)
   --help                    Show this help message
+  --retry_limit=<n>         Override agent turn retry limits (minimum 1, maximum 10)
 
 Examples:
   npx testronaut
@@ -242,14 +344,16 @@ if (args.includes('serve') || args.includes('view')) {
   await new Promise(() => {}); // ✅ never resolves; Ctrl+C will terminate
 }
 
-if (!fs.existsSync(missionsDir)) {
-  console.error('❌ No `missions` directory found.');
+const { root: missionsRoot, files: discoveredMissions } = await discoverMissionFiles({ cwd: process.cwd() });
+
+if (!fs.existsSync(missionsRoot)) {
+  console.error(`❌ Missions directory not found: ${path.relative(process.cwd(), missionsRoot)}`);
   process.exit(1);
 }
 
 const runFile = async (filePath) => {
   try {
-    const modulePath = path.resolve(missionsDir, filePath);
+    const modulePath = path.resolve(missionsRoot, filePath);
     const missionsModule = await import(`file://${modulePath}`);
 
     if (typeof missionsModule.executeMission === 'function') {
@@ -271,9 +375,8 @@ if (args.length > 0) {
     await runFile(file);
   }
 } else {
-  // Run all *.mission.js files
-  const files = fs.readdirSync(missionsDir).filter(f => f.endsWith('.mission.js'));
-  for (const file of files) {
+  // Run missions discovered from config (or default behavior)
+  for (const file of discoveredMissions) {
     await runFile(file);
   }
 }
@@ -720,6 +823,11 @@ function safeJoin(root, relUrlPath) {
   return resolved;
 }
 
+/**
+ * Best-effort cross-platform URL opener.
+ * @param {string} targetUrl
+ * @returns {Promise<void>}
+ */
 async function openInBrowser(targetUrl) {
   const platform = process.platform;
   const quoted = `"${targetUrl}"`;
@@ -848,4 +956,4 @@ try {
   }
 } catch (err) {
   console.warn(`⚠️ Could not remove tmp folder: ${err.message}`);
-}
+}

package/bin/init.js

@@ -139,6 +139,8 @@ export async function initializeTestronautProject() {
     config.outputDir = config.outputDir || defaults.outputDir;
     config.projectName = config.projectName || defaults.projectName;
     config.maxTurns = config.maxTurns ?? defaults.maxTurns;
+    config.dom = { ...defaults.dom, ...(config.dom || {}) };
+    config.resourceGuard = { ...defaults.resourceGuard, ...(config.resourceGuard || {}) };
 
     // ─────────────────────────────────────────────
     // STEP 4: Persist config and scaffold .env (first run only)

package/bin/initHelpers.js

@@ -52,6 +52,14 @@ export function defaultConfig(rootBasename) {
     outputDir: 'missions/mission_reports',
     projectName: rootBasename,
     maxTurns: 20,
+    dom: {
+      listItemLimit: 3,
+    },
+    resourceGuard: {
+      enabled: true,
+      hrefIncludes: ['/document/', '/file/', '/download', '/attachment/'],
+      dataTypes: ['document', 'file', 'item', 'row'],
+    },
   };
 }
 

package/core/agent.js

@@ -35,10 +35,16 @@ import path from 'path';
  * @param {Array<{goal:any, submissionType?:string, submissionName?:string, label?:string}>} goals
  * @param {string} missionName
  * @param {number} [maxTurns=20] - upper bound for turnLoop per goal
+ * @param {number} [retryLimit]
+ * @param {{ domListLimit?: number|typeof Infinity, debug?: boolean, resourceGuard?: { enabled:boolean, hrefIncludes:string[], dataTypes:string[] } }} [opts]
  * @returns {Promise<Array<{missionName:string, submissionType:string, submissionName:string|null, status:'passed'|'failed', steps:any[], startTime:number, endTime:number}>>}
  */
-export async function runAgent(goals, missionName, maxTurns = 20) {
-  const browser = new ChromeBrowser();
+export async function runAgent(goals, missionName, maxTurns = 20, retryLimit, opts = {}) {
+  const browser = new ChromeBrowser({
+    domListLimit: opts.domListLimit,
+    debug: opts.debug,
+    resourceGuard: opts.resourceGuard,
+  });
   await browser.start();
   let result;
 
@@ -52,6 +58,7 @@ export async function runAgent(goals, missionName, maxTurns = 20) {
 
     for (const goal of goals) {
       const steps = [];
+      const stepsArchive = [];
       // Unique-ish JSONL file for this mission’s steps
       const stepFile = path.join(
         tmpDir,
@@ -152,34 +159,35 @@ Use Ground Control as your persistent mission memory about:
         null, // currentStep
         {
           steps,
+          stepsArchive,
           missionName,
+          retryLimit, 
           groundControl,
+          resourceGuard: opts.resourceGuard,
           onStep: (s) => {
             // Append each step as a JSON line
             try {
               fs.appendFileSync(stepFile, JSON.stringify(s) + '\n');
               // Keep memory in check: retain only the last ~20 steps in RAM
               if (steps.length > 20) steps.splice(0, steps.length - 20);
+              stepsArchive.push(s);
             } catch {} // best-effort; don’t crash the agent
           }
         }
       );
 
       function dedupeSteps(steps) {
-        const seen = new Set();
-        const out = [];
-        for (const s of steps) {
-          const first = s?.events?.[0] || '';
-          const key = `${s.turn}::${s.summary}::${first}`;
-          if (!seen.has(key)) {
-            seen.add(key);
-            out.push(s);
+        const copy = [...steps];
+        copy.sort((a, b) => {
+          if (Number.isFinite(a?._seq) && Number.isFinite(b?._seq)) {
+            return a._seq - b._seq;
           }
-        }
-        return out;
+          return (a?.turn ?? 0) - (b?.turn ?? 0);
+        });
+        return copy;
       }
 
-      const compact = dedupeSteps(steps);
+      const compact = dedupeSteps(stepsArchive.length ? stepsArchive : steps);
 
       // Snapshot steps (avoid retaining references to mutable arrays)
       missionResults.push({

package/core/config.js

@@ -52,6 +52,127 @@ export function getMaxTurns(cfg, fallback = 20) {
   return n;
 }
 
+/**
+ * Resolve retry limit per turn (attempts - 1) with clamping.
+ * Priority: env TESTRONAUT_RETRY_LIMIT → config.retryLimit → fallback
+ *
+ * @param {object} cfg
+ * @param {number} [fallback=2]
+ * @returns {{ value:number, source:'env'|'config'|'default', clamped:boolean }}
+ */
+export function getRetryLimit(cfg, fallback = 2) {
+  const clampRetry = (n) => {
+    const clamped = Math.min(10, Math.max(1, n));
+    return { value: clamped, clamped: clamped !== n };
+  };
+
+  const envVal = Number(process.env.TESTRONAUT_RETRY_LIMIT);
+  if (Number.isFinite(envVal)) {
+    const { value, clamped } = clampRetry(envVal);
+    return { value, source: 'env', clamped };
+  }
+
+  const cfgVal = Number(cfg?.retryLimit);
+  if (Number.isFinite(cfgVal)) {
+    const { value, clamped } = clampRetry(cfgVal);
+    return { value, source: 'config', clamped };
+  }
+
+  const { value, clamped } = clampRetry(fallback);
+  return { value, source: 'default', clamped };
+}
+
+/**
+ * Resolve how many list-like items to keep in DOM snapshots.
+ * - Accepts numbers (clamped 0-100), or the strings "all"/"none".
+ * - Priority: env TESTRONAUT_DOM_LIST_LIMIT → config.dom.listItemLimit/listLimit/domListLimit → fallback.
+ *
+ * @param {object} cfg
+ * @param {number} [fallback=3]
+ * @returns {{ value:number|typeof Infinity, mode:'number'|'all'|'none', source:'env'|'config'|'default', clamped:boolean }}
+ */
+export function getDomListLimit(cfg, fallback = 3) {
+  const clampList = (n) => {
+    const clamped = Math.min(100, Math.max(0, n));
+    return { value: clamped, clamped: clamped !== n };
+  };
+
+  const parseRaw = (raw) => {
+    if (raw === undefined || raw === null) return null;
+
+    if (typeof raw === 'string') {
+      const lower = raw.trim().toLowerCase();
+      if (!lower) return null;
+      if (lower === 'all') return { value: Infinity, mode: 'all', clamped: false };
+      if (lower === 'none') return { value: 0, mode: 'none', clamped: false };
+      const num = Number(lower);
+      if (!Number.isFinite(num)) return null;
+      const { value, clamped } = clampList(num);
+      return { value, mode: value === 0 ? 'none' : 'number', clamped };
+    }
+
+    if (typeof raw === 'number' && Number.isFinite(raw)) {
+      const { value, clamped } = clampList(raw);
+      return { value, mode: value === 0 ? 'none' : 'number', clamped };
+    }
+
+    return null;
+  };
+
+  const envParsed = parseRaw(process.env.TESTRONAUT_DOM_LIST_LIMIT);
+  if (envParsed) return { ...envParsed, source: 'env' };
+
+  const cfgRaw = cfg?.dom?.listItemLimit ?? cfg?.dom?.listLimit ?? cfg?.domListLimit;
+  const cfgParsed = parseRaw(cfgRaw);
+  if (cfgParsed) return { ...cfgParsed, source: 'config' };
+
+  const fbParsed = parseRaw(fallback);
+  return { ...fbParsed, source: 'default' };
+}
+
+/**
+ * Resolve resource guard settings for generic list/table harvesting.
+ * - Patterns are used to detect resource anchors/data attributes.
+ * - Enabled can be toggled via config.resourceGuard.enabled or TESTRONAUT_RESOURCE_GUARD.
+ */
+export function getResourceGuardConfig(cfg) {
+  const parseBool = (raw) => {
+    if (raw === undefined || raw === null) return null;
+    const lower = String(raw).trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(lower)) return true;
+    if (['0', 'false', 'no', 'off'].includes(lower)) return false;
+    return null;
+  };
+
+  const defaultHrefPatterns = ['/document/', '/file/', '/download', '/attachment/'];
+  const defaultDataTypes = ['document', 'file', 'item', 'row'];
+
+  const envEnabled = parseBool(process.env.TESTRONAUT_RESOURCE_GUARD);
+  const cfgEnabled = parseBool(cfg?.resourceGuard?.enabled);
+  const enabled = envEnabled ?? cfgEnabled ?? true;
+
+  const parseList = (raw) => {
+    if (Array.isArray(raw)) return raw.map(String).map(s => s.trim()).filter(Boolean);
+    if (typeof raw === 'string') {
+      return raw.split(',').map(s => s.trim()).filter(Boolean);
+    }
+    return [];
+  };
+
+  const hrefIncludes = parseList(process.env.TESTRONAUT_RESOURCE_HREF_PATTERNS)
+    || [];
+  const dataTypes = parseList(process.env.TESTRONAUT_RESOURCE_DATA_TYPES)
+    || [];
+
+  const cfgHref = parseList(cfg?.resourceGuard?.hrefIncludes);
+  const cfgTypes = parseList(cfg?.resourceGuard?.dataTypes);
+
+  const finalHref = (hrefIncludes.length ? hrefIncludes : cfgHref.length ? cfgHref : defaultHrefPatterns).map(s => s.toLowerCase());
+  const finalTypes = (dataTypes.length ? dataTypes : cfgTypes.length ? cfgTypes : defaultDataTypes).map(s => s.toLowerCase());
+
+  return { enabled, hrefIncludes: finalHref, dataTypes: finalTypes };
+}
+
 /**
  * Baseline limits for mission runs. Adjust here for global defaults.
  *

package/core/missionDiscovery.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import path from 'path';
+import fg from 'fast-glob';
+import { loadConfig } from './config.js';
+
+const DEFAULT_ROOT = 'missions';
+const DEFAULT_INCLUDE = ['**/*.mission.js', '**/*.mission.ts'];
+
+/**
+ * Discover mission files based on testronaut-config.json.
+ * - When no missions block exists, preserve legacy behavior:
+ *   read the ./missions folder (non-recursive) for *.mission.js files.
+ * - When missions is defined, apply root/include/exclude globs relative to root.
+ *
+ * @param {object} opts
+ * @param {string} [opts.cwd=process.cwd()] - project root for config + resolution
+ * @returns {Promise<{ root:string, files:string[] }>} root is absolute; files are relative to root
+ */
+export async function discoverMissionFiles({ cwd = process.cwd() } = {}) {
+  const defaultRoot = path.resolve(cwd, DEFAULT_ROOT);
+  const cfg = await loadConfig(cwd);
+  const missionsCfg = cfg?.missions;
+
+  // Legacy behavior: no missions block → non-recursive *.mission.js in ./missions
+  if (!missionsCfg) {
+    if (!fs.existsSync(defaultRoot)) {
+      return { root: defaultRoot, files: [] };
+    }
+    const files = fs.readdirSync(defaultRoot)
+      .filter(f => f.endsWith('.mission.js'))
+      .sort();
+    return { root: defaultRoot, files };
+  }
+
+  const root = path.resolve(cwd, missionsCfg.root || DEFAULT_ROOT);
+  if (!fs.existsSync(root)) {
+    return { root, files: [] };
+  }
+
+  const include = Array.isArray(missionsCfg.include) && missionsCfg.include.length
+    ? missionsCfg.include
+    : DEFAULT_INCLUDE;
+  const exclude = Array.isArray(missionsCfg.exclude) ? missionsCfg.exclude : [];
+
+  const matches = await fg(include, {
+    cwd: root,
+    ignore: exclude,
+    onlyFiles: true,
+  });
+
+  const unique = Array.from(new Set(matches));
+  unique.sort();
+
+  return { root, files: unique };
+}