testronaut 1.3.1 → 1.3.3

package/README.md

@@ -154,6 +154,27 @@ await runMissions({
   postMission: logoutMission,
 }, "Contact Form Flow");
 ```
+
+---
+
+## 🧰 Developer Mode (Staging API)
+
+Use the staging API base URL:
+```bash
+npx testronaut --dev
+```
+
+If the staging deployment is protected by Vercel, pass the bypass secret:
+```bash
+npx testronaut --dev --vercel-bypass=YOUR_SECRET login
+```
+
+You can also set the bypass secret via environment variables:
+```bash
+export VERCEL_AUTOMATION_BYPASS_SECRET=YOUR_SECRET
+# or
+export TESTRONAUT_VERCEL_BYPASS=YOUR_SECRET
+```
 ---
 
 ## 📋 Reports
@@ -178,6 +199,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

@@ -13,6 +13,7 @@
  *   --model <id> / --model=<id>         → sets TESTRONAUT_MODEL env (wins over config file)
  *   --turns <n> / --turns=<n>           → sets TESTRONAUT_TURNS env (wins over config file)
  *   --init                               → scaffolds project + optional Playwright browsers
+ *   --dev                                → use staging API base URL
  *   --help                               → prints help
  *
  * Notable helpers (defined below):
@@ -47,6 +48,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';
@@ -54,11 +56,72 @@ process.env.PLAYWRIGHT_BROWSERS_PATH = process.env.PLAYWRIGHT_BROWSERS_PATH || '
 const TMP_DIR = path.resolve('./missions/tmp');
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-// const apiBase = `http://localhost:3002` //
-const apiBase = 'http://api.testronaut.app'; // Replace with your actual API base URL
+const DEFAULT_API_BASE = 'http://api.testronaut.app';
+const DEV_API_BASE = 'https://staging.api.testronaut.app';
 
+let args = process.argv.slice(2);
 
-const args = process.argv.slice(2);
+// Look for --dev / --developer / --developer-mode / --staging
+const devFlagIndex = args.findIndex(a =>
+  a === '--dev' ||
+  a === '--developer' ||
+  a === '--developer-mode' ||
+  a === '--staging'
+);
+let apiBase = process.env.TESTRONAUT_API_BASE || DEFAULT_API_BASE;
+if (devFlagIndex >= 0) {
+  apiBase = DEV_API_BASE;
+  console.log(`🧪 Developer mode: using ${apiBase}`);
+  args.splice(devFlagIndex, 1);
+}
+
+function parseVercelBypassArgs(argsList) {
+  const nextArgs = [...argsList];
+  let secret;
+  let invalid = false;
+  const idx = nextArgs.findIndex(a =>
+    a === '--vercel-bypass' ||
+    a.startsWith('--vercel-bypass=') ||
+    a === '--vercel_bypass' ||
+    a.startsWith('--vercel_bypass=')
+  );
+  if (idx >= 0) {
+    const rawArg = nextArgs[idx];
+    const hasInline = rawArg.includes('=');
+    if (hasInline) {
+      secret = rawArg.split('=')[1];
+    } else if (nextArgs[idx + 1]) {
+      secret = nextArgs[idx + 1];
+    }
+
+    if (!secret) invalid = true;
+
+    // Remove flag & value so they aren’t treated as filenames
+    const consume = hasInline ? 1 : (secret ? 2 : 1);
+    nextArgs.splice(idx, consume);
+  }
+  return { secret, args: nextArgs, invalid };
+}
+
+const vercelBypassResult = parseVercelBypassArgs(args);
+if (vercelBypassResult.invalid) {
+  console.warn('⚠️ Invalid --vercel-bypass value. Provide a non-empty secret.');
+}
+args = vercelBypassResult.args;
+const vercelBypassOverride = vercelBypassResult.secret;
+
+const vercelBypassSecret =
+  vercelBypassOverride ||
+  process.env.VERCEL_AUTOMATION_BYPASS_SECRET ||
+  process.env.TESTRONAUT_VERCEL_BYPASS;
+function createVercelBypassHeader(secret) {
+  return secret ? { 'x-vercel-protection-bypass': secret } : {};
+}
+const vercelBypassHeader = createVercelBypassHeader(vercelBypassSecret);
+
+function buildApiHeaders(extra = {}) {
+  return { ...extra, ...vercelBypassHeader };
+}
 
 /**
  * Read a JSONL steps file into an array of objects.
@@ -132,6 +195,8 @@ export const __test__ = {
   findLatestReportPair,
   mergeDuplicateTurns,
   readJsonlSteps,
+  parseVercelBypassArgs,
+  createVercelBypassHeader,
 };
 
 // Look for --model=<id> or --model <id>
@@ -153,6 +218,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='));
@@ -208,8 +315,6 @@ if (retryFlagIndex >= 0) {
   args.splice(retryFlagIndex, retryOverride ? 2 : 1);
 }
 
-const missionsDir = path.resolve(process.cwd(), 'missions');
-
 const allResults = [];
 const runId = `run_${Date.now()}`;
 const startTime = new Date();
@@ -228,6 +333,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)
+  --dev                     Use the staging API base URL
+  --vercel-bypass=<secret>  Send Vercel protection bypass header for protected deployments
   --help                    Show this help message
   --retry_limit=<n>         Override agent turn retry limits (minimum 1, maximum 10)
 
@@ -302,14 +410,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') {
@@ -331,9 +441,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);
   }
 }
@@ -549,13 +658,13 @@ async function handleLogin() {
   try {
     const response = await fetch(`${apiBase}/api/user/cli`, {  // Replace with your actual URL
       method: 'POST',
-      headers: {
+      headers: buildApiHeaders({
         'Content-Type': 'application/x-www-form-urlencoded',
-      },
+      }),
       body: formData.toString(),
     });
 
-    const data = await response.json();
+    const data = await parseJsonSafe(response, 'login');
 
     if (data.error) {
       console.error('❌ Authentication failed:', data.error);
@@ -616,7 +725,7 @@ async function uploadReport() {
   try {
     const res = await fetch(`${apiBase}/api/user/cli/${sessionToken}`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: buildApiHeaders({ 'Content-Type': 'application/json' }),
       body: reportJson,
     });
     const data = await res.json();
@@ -692,7 +801,7 @@ async function uploadReport() {
       // console.log(` the fetch url is: ${apiBase}/api/user/cli/${sessionToken}/uploads/start`);
       const startRes = await fetch(`${apiBase}/api/user/cli/${sessionToken}/uploads/start`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: buildApiHeaders({ 'Content-Type': 'application/json' }),
         body: JSON.stringify({ reportId: savedReportId, stepIndex, fileName: path.basename(filePath), mime, size: stat.size, sha1: hash }),
       });
       const start = await parseJsonSafe(startRes, 'uploads/start');
@@ -714,7 +823,7 @@ async function uploadReport() {
       // console.log(`     finalizing upload…`);
       const finishRes = await fetch(`${apiBase}/api/user/cli/${sessionToken}/uploads/finish`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: buildApiHeaders({ 'Content-Type': 'application/json' }),
         body: JSON.stringify({ 
           reportId: savedReportId, 
           stepIndex, 

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, retryLimit) {
-  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;
 
@@ -155,8 +161,9 @@ Use Ground Control as your persistent mission memory about:
           steps,
           stepsArchive,
           missionName,
-          retryLimit,
+          retryLimit, 
           groundControl,
+          resourceGuard: opts.resourceGuard,
           onStep: (s) => {
             // Append each step as a JSON line
             try {

package/core/config.js

@@ -82,6 +82,97 @@ export function getRetryLimit(cfg, fallback = 2) {
   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 };
+}

package/core/turnLoop.js

@@ -63,6 +63,50 @@ console.log(`🧠 Using LLM → provider: ${PROVIDER_ID}, model: ${MODEL_ID}`);
 
 const llm = getLLM(PROVIDER_ID);
 
+// Track resource/download coverage across turns (guard against partial loops).
+function ensureDocProgress(agentMemory, cfg) {
+  if (!cfg?.enabled) return null;
+  if (!agentMemory.docProgress) {
+    agentMemory.docProgress = {
+      items: [],
+      downloaded: new Set(),
+      lastSummary: '',
+      lastScriptCount: 0,
+      patterns: cfg,
+    };
+  } else {
+    agentMemory.docProgress.patterns = cfg;
+  }
+  return agentMemory.docProgress;
+}
+
+// Parse injected <pre data-testronaut-doc-list> summary into structured items.
+function parseDocListFromDom(html) {
+  try {
+    const match = html.match(/<pre[^>]*data-testronaut-doc-list[^>]*>([\s\S]*?)<\/pre>/i);
+    if (!match) return { items: [], scriptDocs: 0 };
+    const text = match[1];
+    const lines = text.split('\n').map(l => l.trim()).filter(Boolean).slice(1);
+    const items = lines.map(l => {
+      const m = l.match(/-\s*\[(.*?)\]\s*(.*?)\s+(\/document\/\d+[^\s]*)?/i);
+      return {
+        id: m?.[1] || '',
+        title: m?.[2] || l.replace(/^-/, '').trim(),
+        href: m?.[3] || '',
+      };
+    }).filter(it => it.id || it.title || it.href);
+    return { items, scriptDocs: items.length };
+  } catch {
+    return { items: [], scriptDocs: 0 };
+  }
+}
+
+// Extract numeric document IDs from common /document/<id> URLs.
+function extractDocIdFromUrl(url = '') {
+  const m = url.match(/\/document\/(\d+)/i);
+  return m ? m[1] : '';
+}
+
 // Rolling token counters used for self-throttling
 let totalTokensUsed = 0;
 let turnTimestamps = [];
@@ -174,11 +218,17 @@ export const turnLoop = async (
   ctx = {} // { steps, missionName, groundControl }
 ) => {
   const { steps = [], missionName, groundControl = createEmptyGroundControl(), retryLimit: retryLimitRaw } = ctx;
+  const resourceGuardCfg = ctx.resourceGuard || {
+    enabled: true,
+    hrefIncludes: ['/document/', '/file/', '/download', '/attachment/'],
+    dataTypes: ['document', 'file', 'item', 'row'],
+  };
   const stepsArchive = ctx.stepsArchive || steps;
   const retryLimitClamped = Math.min(10, Math.max(1, Number.isFinite(retryLimitRaw) ? retryLimitRaw : DEFAULT_TURN_RETRY_LIMIT)); // retries allowed (excludes initial)
   const maxAttempts = retryLimitClamped + 1; // includes initial attempt
   ctx.groundControl = groundControl;
   let agentMemory = { lastMenuExpanded: false };
+  ensureDocProgress(agentMemory, resourceGuardCfg);
   let turnRetries = 0;
   let stepSeq = ctx._stepSeq || 0;
   
@@ -373,6 +423,20 @@ export const turnLoop = async (
               : `📥 Downloaded "${maybeJson.fileName}" (${formatBytes(maybeJson.bytes)}) via ${maybeJson.mode}`;
             step.events.push(msgLine);
             console.log(msgLine);
+
+            if (resourceGuardCfg.enabled && (maybeJson._testronaut_file_event === 'download' || maybeJson._testronaut_file_event === 'upload')) {
+              const prog = ensureDocProgress(agentMemory, resourceGuardCfg);
+              if (prog) {
+                const id = extractDocIdFromUrl(maybeJson.url || maybeJson.selector || maybeJson.fileName);
+                if (id) prog.downloaded.add(id);
+                // also try title match
+                if (maybeJson.fileName) {
+                  const byTitle = prog.items.find(i => maybeJson.fileName.includes(i.title));
+                  if (byTitle?.id) prog.downloaded.add(byTitle.id);
+                }
+                step.events.push(`📊 Resource progress: ${prog.downloaded.size}/${prog.items.length || prog.lastScriptCount}`);
+              }
+            }
           }
         } catch {
           // non-JSON results ignored
@@ -413,6 +477,35 @@ export const turnLoop = async (
           contentForModel = result;
         }
 
+        // Keep doc list progress updated when we fetch DOM
+        if (!errorMessage && resourceGuardCfg.enabled) {
+          const prog = ensureDocProgress(agentMemory, resourceGuardCfg);
+          if (prog) {
+            if (fnName === 'get_dom') {
+              const { items, scriptDocs } = parseDocListFromDom(result);
+              if (items.length) {
+                prog.items = items;
+                prog.lastScriptCount = scriptDocs || items.length;
+                prog.lastSummary = `docs:${items.length}`;
+                step.events.push(`📊 Detected document list (${items.length} items)`);
+              }
+            } else if (fnName === 'list_local_files') {
+              try {
+                const parsed = JSON.parse(result);
+                const files = parsed?.files || [];
+                if (Array.isArray(files) && files.length) {
+                  prog.items = files.map(f => ({ id: f, title: f, href: f }));
+                  prog.lastScriptCount = files.length;
+                  prog.lastSummary = `files:${files.length}`;
+                  step.events.push(`📊 Detected local files (${files.length} items)`);
+                }
+              } catch {
+                // ignore parse errors
+              }
+            }
+          }
+        }
+
         toolResponses.push({
           role: 'tool',
           tool_call_id: call.id,
@@ -465,6 +558,24 @@ export const turnLoop = async (
     // ─────────────────────────────────────────────
     const finalResponse = finalResponseHandler(msg);
     if (finalResponse !== null) {
+      const prog = ensureDocProgress(agentMemory, resourceGuardCfg);
+      if (prog?.items.length && prog.downloaded.size < prog.items.length) {
+        const remaining = prog.items
+          .filter(i => !prog.downloaded.has(i.id))
+          .map(i => i.title || i.id)
+          .slice(0, 10);
+        const remainText = remaining.length ? remaining.join('; ') : 'unknown items';
+        const guardMsg = `Auto-guard: downloaded ${prog.downloaded.size}/${prog.items.length}. Remaining: ${remainText}`;
+        console.log(`[guard] ${guardMsg}`);
+        step.events.push(guardMsg);
+        step.result = '🟡 In Progress';
+        recordStep(step);
+        // Nudge model to continue
+        messages.push({ role: 'assistant', content: guardMsg });
+        // Continue loop without exiting
+        turnRetries = 0;
+        continue;
+      }
       step.events.push(finalResponse.finalMessage);
       step.result = finalResponse.success ? '✅ Mission Success' : '❌ Mission Failure';
       recordStep(step);
@@ -488,3 +599,10 @@ export const turnLoop = async (
 
   return { success: false, steps: stepsArchive };
 };
+
+// Expose small helper bundle for unit tests (no production use).
+export const __docProgressInternals = {
+  ensureDocProgress,
+  parseDocListFromDom,
+  extractDocIdFromUrl,
+};

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "testronaut",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "main": "./runner/testronaut.js",
   "bin": {
-    "testronaut": "./bin/cli.js"
+    "testronaut": "bin/cli.js"
   },
   "exports": {
     ".": "./runner/testronaut.js",
@@ -24,6 +24,7 @@
     "@google/generative-ai": "^0.24.1",
     "cheerio": "^1.1.0",
     "dotenv": "^17.2.0",
+    "fast-glob": "^3.3.3",
     "inquirer": "^12.9.1",
     "node-fetch": "^3.3.2",
     "openai": "^5.10.2",