testronaut 1.9.4 → 1.10.0

package/README.md

@@ -191,6 +191,31 @@ Run a specific mission:
 testronaut login.mission.js
 ```
 
+Reuse cookies, local storage, and IndexedDB authentication state across an ordered set of mission files:
+
+```bash
+testronaut --session=shared-auth checkout.mission.js account.mission.js
+```
+
+Each mission still receives a fresh browser context. The default
+`--session=isolated` mode does not carry authentication forward. Shared-auth
+suites can wrap a reusable login prerequisite in `launchProtocol()` so later
+mission files probe the restored authenticated page without an LLM call:
+
+```js
+import { launchProtocol, runMissions } from 'testronaut';
+
+const login = launchProtocol('Visit the app and log in.', {
+  id: 'authenticated:test-user',
+  probe: { url: process.env.URL, selector: '#dashboard' },
+});
+
+await runMissions({ preMission: login, mission: 'Test the dashboard.' }, 'dashboard');
+```
+
+Unwrapped `preMission` values remain fully compatible and always run normally.
+Place logout last in a shared-auth suite.
+
 Preview or inspect without launching a browser:
 ```bash
 testronaut list
@@ -371,7 +396,7 @@ 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)
+- **DOM trimming controls** to cap list/table sizes (`TESTRONAUT_DOM_LIST_LIMIT`) and automatic post-action snapshots (`TESTRONAUT_AUTO_DOM_LIMIT` or `dom.automaticLimit`)
 - **Resource guard** to ensure full list/table downloads (config `resourceGuard` or env `TESTRONAUT_RESOURCE_*`)
 
 ---

package/TODO.md

@@ -9,6 +9,17 @@
 - [ ] Treat `--json` output as a stable automation contract with documented schemas and tests for every supported command.
 - [ ] If authentication ever moves outside project config, continue reading existing `sessionToken` values and provide an opt-in migration path before deprecating legacy storage.
 
+## Session and Reporting Follow-Ups
+
+- [ ] Evaluate a true shared browser-context mode for suites that require session storage or in-memory application state; define page reset, crash recovery, and concurrency behavior first.
+- [ ] Add optional shared-auth checkpoints/reset controls for suites that intentionally change users or tenants.
+- [ ] Refresh short-lived Testronaut API session tokens during long runs once the API and credential-storage contract is defined.
+- [ ] Store new CLI authentication outside project config, prefer environment credentials in CI, and migrate legacy project `sessionToken` values without breaking existing projects.
+- [ ] Add structured post-run self-critique fields after the versioned report schema is available.
+- [ ] Separate mission totals from phase totals and add an explicit `phase` field without losing compatibility with `submissionType`.
+- [ ] Design an optional mission scope/side-effect policy that agents can enforce and reports can display.
+- [ ] Evaluate semantic DOM diffs/chunks after configurable limits, selector scoping, and table trimming have production data.
+
 ## Automated MFA Follow-Ups
 
 - [ ] Add an integration smoke test against a local or staging API fixture for `get_mfa_code`.

package/bin/cli.js

@@ -62,6 +62,8 @@ import { matchesTagFilter, normalizeTagMatch, normalizeTags } from '../core/tags
 process.env.PLAYWRIGHT_BROWSERS_PATH = process.env.PLAYWRIGHT_BROWSERS_PATH || '0';
 
 const TMP_DIR = path.resolve('./missions/tmp');
+const runId = `run_${Date.now()}`;
+const startTime = new Date();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_VERSION = JSON.parse(
   fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf8')
@@ -89,6 +91,28 @@ const uploadScreenshots = !args.includes('--no-upload-screenshots');
 args = args.filter(arg => arg !== '--no-upload-screenshots');
 process.env.TESTRONAUT_SCREENSHOTS = screenshotsEnabled ? '1' : '0';
 
+let sessionMode = 'isolated';
+const sessionFlagIndex = args.findIndex(a => a === '--session' || a.startsWith('--session='));
+if (sessionFlagIndex >= 0) {
+  const raw = args[sessionFlagIndex];
+  const inline = raw.includes('=');
+  const value = inline ? raw.slice(raw.indexOf('=') + 1) : args[sessionFlagIndex + 1];
+  if (!['isolated', 'shared-auth'].includes(value)) {
+    console.error('❌ --session must be "isolated" or "shared-auth".');
+    process.exit(1);
+  }
+  sessionMode = value;
+  args.splice(sessionFlagIndex, inline ? 1 : 2);
+}
+if (sessionMode === 'shared-auth') {
+  const storageStatePath = path.join(TMP_DIR, `${runId}-storage-state.json`);
+  process.env.TESTRONAUT_STORAGE_STATE_PATH = storageStatePath;
+  process.once('exit', () => {
+    try { fs.unlinkSync(storageStatePath); } catch {}
+  });
+}
+process.env.TESTRONAUT_SESSION_MODE = sessionMode;
+
 // Detect how the CLI was invoked so help text matches the actual command
 function detectCliName(npmCommand = process.env.npm_command, argv1 = process.argv[1]) {
   // npx sets npm_command to 'exec'
@@ -486,7 +510,8 @@ __test__.parseTagArgs = parseTagArgs;
 let modelOverride;
 const modelFlagIndex = args.findIndex(a => a === '--model' || a.startsWith('--model='));
 if (modelFlagIndex >= 0) {
-  if (args[modelFlagIndex].includes('=')) {
+  const inline = args[modelFlagIndex].includes('=');
+  if (inline) {
     modelOverride = args[modelFlagIndex].split('=')[1];
   } else if (args[modelFlagIndex + 1]) {
     modelOverride = args[modelFlagIndex + 1];
@@ -498,7 +523,7 @@ if (modelFlagIndex >= 0) {
   }
 
   // Remove flag & value from args so they don't look like mission filenames
-  args.splice(modelFlagIndex, modelOverride ? 2 : 1);
+  args.splice(modelFlagIndex, inline ? 1 : (modelOverride ? 2 : 1));
 }
 
 // Look for --provider=<id> or --provider <id>
@@ -601,7 +626,8 @@ if (debugFlagIndex >= 0) {
 let turnsOverride;
 const turnsFlagIndex = args.findIndex(a => a === '--turns' || a.startsWith('--turns='));
 if (turnsFlagIndex >= 0) {
-  if (args[turnsFlagIndex].includes('=')) {
+  const inline = args[turnsFlagIndex].includes('=');
+  if (inline) {
     turnsOverride = args[turnsFlagIndex].split('=')[1];
   } else if (args[turnsFlagIndex + 1]) {
     turnsOverride = args[turnsFlagIndex + 1];
@@ -618,7 +644,7 @@ if (turnsFlagIndex >= 0) {
   }
 
   // Remove flag & value so they aren’t treated as filenames
-  args.splice(turnsFlagIndex, turnsOverride ? 2 : 1);
+  args.splice(turnsFlagIndex, inline ? 1 : (turnsOverride ? 2 : 1));
 }
 
 // Look for --retry_limit / --retry-limit
@@ -631,7 +657,8 @@ const retryFlagIndex = args.findIndex(a =>
 );
 if (retryFlagIndex >= 0) {
   const rawArg = args[retryFlagIndex];
-  if (rawArg.includes('=')) {
+  const inline = rawArg.includes('=');
+  if (inline) {
     retryOverride = rawArg.split('=')[1];
   } else if (args[retryFlagIndex + 1]) {
     retryOverride = args[retryFlagIndex + 1];
@@ -649,7 +676,7 @@ if (retryFlagIndex >= 0) {
   }
 
   // Remove flag & value so they aren’t treated as filenames
-  args.splice(retryFlagIndex, retryOverride ? 2 : 1);
+  args.splice(retryFlagIndex, inline ? 1 : (retryOverride ? 2 : 1));
 }
 
 // Look for --human-input / --no-human-input / --disable-human-input
@@ -697,7 +724,8 @@ const humanInputTimeoutFlagIndex = args.findIndex(a =>
 );
 if (humanInputTimeoutFlagIndex >= 0) {
   const rawArg = args[humanInputTimeoutFlagIndex];
-  if (rawArg.includes('=')) {
+  const inline = rawArg.includes('=');
+  if (inline) {
     humanInputTimeoutOverride = rawArg.split('=')[1];
   } else if (args[humanInputTimeoutFlagIndex + 1]) {
     humanInputTimeoutOverride = args[humanInputTimeoutFlagIndex + 1];
@@ -713,12 +741,10 @@ if (humanInputTimeoutFlagIndex >= 0) {
     }
   }
 
-  args.splice(humanInputTimeoutFlagIndex, humanInputTimeoutOverride ? 2 : 1);
+  args.splice(humanInputTimeoutFlagIndex, inline ? 1 : (humanInputTimeoutOverride ? 2 : 1));
 }
 
 const allResults = [];
-const runId = `run_${Date.now()}`;
-const startTime = new Date();
 
 const HELP_TEXT = `
 🧑‍🚀 testronaut - Autonomous Agent Mission Runner
@@ -738,6 +764,8 @@ Options:
   --turns=<n>               Override max turns for this run (e.g., --turns=30)
   --debug[=<bool>]          Enable verbose debug logs (or set TESTRONAUT_DEBUG=1)
   --provider=<id>           Override LLM provider (openai, gemini, or anthropic)
+  --model=<id>              Override the provider model for this run
+  --session=<mode>          Browser auth reuse: isolated (default) or shared-auth
   -o, --options key=value   Set run options, such as mfa=github-test-mfa or inbox=github-staging
   --dev                     Use the staging API base URL
   --vercel-bypass=<secret>  Send Vercel protection bypass header for protected deployments
@@ -849,13 +877,16 @@ if (args.length === 1 && args[0] === 'list') {
     return;
   }
   const listedMissions = [];
+  const listTags = cliTags ?? normalizeTags(tagConfig?.tags, { allowUntagged: true });
+  const listTagMatch = normalizeTagMatch(cliTagMatch ?? tagConfig?.tagMatch);
   if (!jsonOutput) console.log(`Missions in ${path.relative(process.cwd(), missionsRoot) || '.'}:`);
   for (const file of discoveredMissions) {
     try {
       const mission = await loadMissionModule(path.resolve(missionsRoot, file));
       const tags = normalizeTags(mission.tags);
-      listedMissions.push({ file, tags });
-      if (!jsonOutput) console.log(`  ${file}${tags.length ? `  [${tags.join(', ')}]` : ''}`);
+      const selected = matchesTagFilter(tags, listTags, listTagMatch);
+      listedMissions.push({ file, tags, selected });
+      if (!jsonOutput) console.log(`  ${selected ? '✓' : '·'} ${file}${tags.length ? `  [${tags.join(', ')}]` : ''}`);
     } catch (error) {
       console.log(`  ${file}  [could not load: ${error.message}]`);
       process.exitCode = 1;
@@ -907,7 +938,7 @@ if (dryRun) {
       invalid = true;
     }
   }
-  writeOutput({ dryRun: true, outputDir, provider: resolveProviderModel({ cwd: process.cwd() }), screenshots: screenshotsEnabled, missions });
+  writeOutput({ dryRun: true, outputDir, provider: resolveProviderModel({ cwd: process.cwd() }), session: { mode: sessionMode }, screenshots: screenshotsEnabled, missions });
   if (invalid) process.exitCode = 1;
   return;
 }
@@ -1008,6 +1039,7 @@ const report = {
     provider: llmProvider,
     model: llmModel,
   },
+  session: { mode: sessionMode },
   summary: {
     totalMissions: flatMissions.length,
     passed: flatMissions.filter(m => m.status === 'passed').length,

package/bin/initHelpers.js

@@ -60,6 +60,7 @@ export function defaultConfig(rootBasename) {
     addTags: [],
     dom: {
       listItemLimit: 3,
+      automaticLimit: 15000,
     },
     resourceGuard: {
       enabled: true,

package/core/agent.js

@@ -25,9 +25,10 @@
 import 'dotenv/config';
 import { ChromeBrowser } from '../tools/chromeBrowser.js';
 import { turnLoop } from './turnLoop.js';
-import { createEmptyGroundControl, summarizeGroundControlForPrompt } from '../tools/contextControl.js';
+import { applyGroundControlUpdate, createEmptyGroundControl, summarizeGroundControlForPrompt } from '../tools/contextControl.js';
 import fs from 'fs';
 import path from 'path';
+import { hasCompletedLaunchProtocol, markLaunchProtocolCompleted } from './launchProtocol.js';
 
 /**
  * Execute goals with a browser agent.
@@ -36,7 +37,7 @@ import path from 'path';
  * @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[] }, humanInput?: { enabled:boolean, timeoutSeconds:number } }} [opts]
+ * @param {{ domListLimit?: number|typeof Infinity, automaticDomLimit?: number, storageStatePath?: string, debug?: boolean, resourceGuard?: { enabled:boolean, hrefIncludes:string[], dataTypes:string[] }, humanInput?: { enabled:boolean, timeoutSeconds:number } }} [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, opts = {}) {
@@ -44,6 +45,7 @@ export async function runAgent(goals, missionName, maxTurns = 20, retryLimit, op
     domListLimit: opts.domListLimit,
     debug: opts.debug,
     resourceGuard: opts.resourceGuard,
+    storageStatePath: opts.storageStatePath,
   });
   await browser.start();
   let result;
@@ -57,6 +59,7 @@ export async function runAgent(goals, missionName, maxTurns = 20, retryLimit, op
     const groundControl = createEmptyGroundControl();
 
     for (const goal of goals) {
+      const telemetryStart = groundControl.telemetry.length;
       const steps = [];
       const stepsArchive = [];
       // Unique-ish JSONL file for this mission’s steps
@@ -67,6 +70,69 @@ export async function runAgent(goals, missionName, maxTurns = 20, retryLimit, op
       // Start clean
       fs.writeFileSync(stepFile, '');
 
+      let protocolResult = null;
+      const protocol = goal.launchProtocol;
+      const sharedAuth = process.env.TESTRONAUT_SESSION_MODE === 'shared-auth';
+      if (protocol && sharedAuth && hasCompletedLaunchProtocol(protocol.id)) {
+        let probeResult;
+        try {
+          probeResult = await browser.probe(protocol.probe);
+        } catch (error) {
+          probeResult = { passed: false, reason: error?.message || String(error) };
+        }
+
+        if (probeResult.passed) {
+          const currentUrl = probeResult.url || protocol.probe.url || null;
+          applyGroundControlUpdate(groundControl, {
+            app: {
+              baseUrl: protocol.probe.url || currentUrl,
+              currentUrl,
+              routeRole: 'authenticated',
+            },
+            session: { loggedIn: true },
+            navigation: { currentLabel: `Launch protocol ${protocol.id} verified` },
+            constraints: { stayWithinBaseUrl: true },
+          });
+          const now = Date.now();
+          const step = {
+            turn: 0,
+            events: [`📡 Launch protocol probe passed: ${protocol.id}`],
+            result: '✅ Mission Success',
+            summary: `Reused launch protocol ${protocol.id}`,
+            missionName,
+            tokensUsed: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+          };
+          fs.appendFileSync(stepFile, JSON.stringify(step) + '\n');
+          missionResults.push({
+            missionName,
+            submissionType: goal.submissionType || goal.label,
+            submissionName: goal.submissionName || null,
+            status: 'passed',
+            steps: [step],
+            stepFile,
+            startTime: now,
+            endTime: now,
+            telemetry: [],
+            launchProtocol: { id: protocol.id, status: 'reused', probe: 'passed' },
+          });
+          continue;
+        }
+        protocolResult = {
+          id: protocol.id,
+          status: 'executed',
+          probe: 'failed',
+          reason: probeResult.reason,
+        };
+      } else if (protocol) {
+        protocolResult = {
+          id: protocol.id,
+          status: 'executed',
+          probe: sharedAuth ? 'not-needed' : 'disabled',
+        };
+      }
+
       // Ensure user message is a string (functions/objects → toString fallback)
       const userContent =
         typeof goal.goal === 'string'
@@ -197,6 +263,7 @@ Email invitation and magic links:
           groundControl,
           resourceGuard: opts.resourceGuard,
           humanInput: opts.humanInput,
+          automaticDomLimit: opts.automaticDomLimit,
           onStep: (s) => {
             // Append each step as a JSON line
             try {
@@ -232,8 +299,14 @@ Email invitation and magic links:
         stepFile, // full history is in this JSONL (one step per line)
         startTime: Date.now() - 1, // TODO: wire actual timings if needed
         endTime: Date.now(),
+        telemetry: JSON.parse(JSON.stringify(groundControl.telemetry.slice(telemetryStart))),
+        ...(protocolResult ? { launchProtocol: protocolResult } : {}),
       });
 
+      if (protocol && result?.success) {
+        markLaunchProtocolCompleted(protocol.id);
+      }
+
       if (!result?.success) {
         console.log('🛑 Agent stopped due to failed goal.\n');
         return missionResults;

package/core/config.js

@@ -130,6 +130,22 @@ export function getDomListLimit(cfg, fallback = 3) {
   return { ...fbParsed, source: 'default' };
 }
 
+/** Resolve the character limit for automatic DOM snapshots injected after actions. */
+export function getAutomaticDomLimit(cfg, fallback = 15000) {
+  const parse = raw => {
+    if (raw === undefined || raw === null || String(raw).trim() === '') return null;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) return null;
+    const clamped = Math.min(100000, Math.max(1000, Math.trunc(value)));
+    return { value: clamped, clamped: clamped !== value };
+  };
+  const env = parse(process.env.TESTRONAUT_AUTO_DOM_LIMIT);
+  if (env) return { ...env, source: 'env' };
+  const configured = parse(cfg?.dom?.automaticLimit ?? cfg?.automaticDomLimit);
+  if (configured) return { ...configured, source: 'config' };
+  return { ...parse(fallback), source: 'default' };
+}
+
 /**
  * Resolve resource guard settings for generic list/table harvesting.
  * - Patterns are used to detect resource anchors/data attributes.

package/core/launchProtocol.js

@@ -0,0 +1,42 @@
+const completedProtocols = new Set();
+
+/**
+ * Add optional shared-session reuse metadata to an ordinary mission goal.
+ * The wrapped goal remains string-coercible for backward compatibility.
+ */
+export function launchProtocol(goal, { id, probe } = {}) {
+  const protocolId = String(id || '').trim();
+  if (!protocolId) throw new Error('launchProtocol requires a non-empty id.');
+  if (!probe || (!probe.selector && !probe.text)) {
+    throw new Error('launchProtocol requires a probe selector or text value.');
+  }
+
+  return Object.freeze({
+    __testronautLaunchProtocol: true,
+    goal,
+    protocol: Object.freeze({
+      id: protocolId,
+      probe: Object.freeze({ ...probe }),
+    }),
+    toString() {
+      return typeof goal === 'string' ? goal : goal?.toString?.() ?? String(goal);
+    },
+  });
+}
+
+export function unwrapLaunchProtocol(value) {
+  if (!value?.__testronautLaunchProtocol) return { goal: value, protocol: null };
+  return { goal: value.goal, protocol: value.protocol };
+}
+
+export function hasCompletedLaunchProtocol(id) {
+  return completedProtocols.has(id);
+}
+
+export function markLaunchProtocolCompleted(id) {
+  completedProtocols.add(id);
+}
+
+export function resetLaunchProtocols() {
+  completedProtocols.clear();
+}

package/core/turnLoop.js

@@ -190,7 +190,7 @@ function formatBytes(n) {
  * @param {object} agentMemory - Memory object storing recent agent state.
  * @param {{skipIfLastTool?: string[]}} opts - Optional tool skip conditions.
  */
-const pushDOMAssistant = async (browser, messages, agentMemory, { skipIfLastTool } = {}) => {
+const pushDOMAssistant = async (browser, messages, agentMemory, { skipIfLastTool, limit = 15000 } = {}) => {
   // Avoid redundant DOM pushes immediately following tools that already include DOM context.
   if (skipIfLastTool && skipIfLastTool.includes(messages.at(-1)?.name)) {
     console.log(`[skip] Skipping DOM push after redundant tool: ${messages.at(-1)?.name}`);
@@ -198,7 +198,7 @@ const pushDOMAssistant = async (browser, messages, agentMemory, { skipIfLastTool
   }
 
   const domCallId = `get_dom_${Date.now()}`;
-  const automaticDomLimit = 15000;
+  const automaticDomLimit = limit;
 
   // Inject a synthetic assistant tool call
   messages.push({
@@ -437,6 +437,8 @@ export const turnLoop = async (
       const tokensUsed = usage.total_tokens || 0;
       console.log(`📊 Token Usage This Turn → Total: ${tokensUsed}`);
       step.tokensUsed = tokensUsed;
+      step.inputTokens = usage.input_tokens ?? usage.prompt_tokens ?? usage.providerRaw?.input_tokens ?? usage.providerRaw?.prompt_tokens;
+      step.outputTokens = usage.output_tokens ?? usage.completion_tokens ?? usage.providerRaw?.output_tokens ?? usage.providerRaw?.completion_tokens;
       recordTokenUsage(turnTimestamps, tokensUsed);
       ({ turnTimestamps, totalTokensUsed } = pruneOldTokenUsage(turnTimestamps));
       console.log(`📈 Running Total Tokens Used (Rolling 60s): ${totalTokensUsed}`);
@@ -466,7 +468,7 @@ export const turnLoop = async (
         const args = JSON.parse(call.function.arguments || '{}');
         const safeArgs = redactArgs(fnName, args);
         console.log(`[model] → ${fnName}`, safeArgs);
-        step.events.push(`[model] → ${fnName} ${safeArgs}`);
+        step.events.push(`[model] → ${fnName} ${JSON.stringify(safeArgs)}`);
 
         let result;
         let errorMessage = null;
@@ -824,6 +826,7 @@ export const turnLoop = async (
         step.events.push(`[auto] → Injecting DOM after ${domRefreshSource}...`);
         const domRefresh = await pushDOMAssistant(browser, messages, agentMemory, {
           skipIfLastTool: ['get_dom', 'check_text'],
+          limit: ctx.automaticDomLimit,
         });
         if (domRefresh?.injected) {
           console.log(`[auto] → DOM size after ${domRefreshSource}: ${domRefresh.domLength} chars`);
@@ -884,6 +887,7 @@ export const turnLoop = async (
     // ─────────────────────────────────────────────
     await pushDOMAssistant(browser, messages, agentMemory, {
       skipIfLastTool: ['get_dom', 'check_text'],
+      limit: ctx.automaticDomLimit,
     });
     console.log(`[auto] → Injected DOM for next reasoning step`);
     step.events.push(`[auto] → Injected DOM for next reasoning step`);

package/llm/anthropic/anthropicProvider.js

@@ -112,6 +112,8 @@ export class AnthropicProvider {
 
     const usage = {
       total_tokens: (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0),
+      input_tokens: response.usage?.input_tokens,
+      output_tokens: response.usage?.output_tokens,
       providerRaw: response.usage,
     };
     return { message: fromAnthropicMessage(response), usage };

package/llm/gemini/geminiProvider.js

@@ -219,6 +219,8 @@ export class GeminiProvider {
     const usageMeta = res?.response?.usageMetadata;
     const usage = {
       total_tokens: usageMeta?.totalTokenCount,
+      input_tokens: usageMeta?.promptTokenCount,
+      output_tokens: usageMeta?.candidatesTokenCount,
       providerRaw: usageMeta,
     };
 

package/llm/openAI/openaiProvider.js

@@ -63,6 +63,8 @@ export class OpenAIProvider {
     const message = res.choices?.[0]?.message ?? { role: 'assistant', content: '' };
     const usage = {
       total_tokens: res.usage?.total_tokens,
+      input_tokens: res.usage?.prompt_tokens,
+      output_tokens: res.usage?.completion_tokens,
       providerRaw: res.usage,
     };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testronaut",
-  "version": "1.9.4",
+  "version": "1.10.0",
   "main": "./runner/testronaut.js",
   "bin": {
     "testronaut": "bin/cli.js"

package/runner/testronaut.js

@@ -29,8 +29,11 @@ import 'dotenv/config';
 import fs from 'fs';
 import path from 'path';
 import { redactPasswordInText } from '../core/redaction.js';
-import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getResourceGuardConfig, getHumanInputConfig } from '../core/config.js';
+import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getAutomaticDomLimit, getResourceGuardConfig, getHumanInputConfig } from '../core/config.js';
 import { normalizeTags } from '../core/tags.js';
+import { launchProtocol, unwrapLaunchProtocol } from '../core/launchProtocol.js';
+
+export { launchProtocol };
 
 // Check process env for debug toggles (shared helper for tests and CLI).
 const isDebugEnabled = () => {
@@ -55,6 +58,7 @@ export async function runMissions({ preMission, mission, postMission, tags = []
   const retryInfo = getRetryLimit(cfg);
   const retryLimit = retryInfo.value;
   const domListLimitInfo = getDomListLimit(cfg);
+  const automaticDomLimitInfo = getAutomaticDomLimit(cfg);
   const resourceGuard = getResourceGuardConfig(cfg);
   const humanInput = getHumanInputConfig(cfg);
   const debugEnabled = isDebugEnabled();
@@ -99,6 +103,7 @@ export async function runMissions({ preMission, mission, postMission, tags = []
       source: domListLimitInfo?.source,
       clamped: domListLimitInfo?.clamped,
     });
+    console.log('[debug] Automatic DOM limit', automaticDomLimitInfo);
     console.log('[debug] Resource guard', {
       enabled: resourceGuard.enabled,
       hrefIncludes: resourceGuard.hrefIncludes,
@@ -161,12 +166,16 @@ export async function runMissions({ preMission, mission, postMission, tags = []
 
   if (pre.length) {
     goals.push(
-      ...pre.map((fn, i) => ({
-        goal: fn,
-        label: 'pre-mission',          // legacy label (kept for logs)
-        submissionType: 'premission',  // normalized
-        submissionName: pickName('premission', fn, i),
-      }))
+      ...pre.map((fn, i) => {
+        const { goal, protocol } = unwrapLaunchProtocol(fn);
+        return {
+          goal,
+          launchProtocol: protocol,
+          label: 'pre-mission',          // legacy label (kept for logs)
+          submissionType: 'premission',  // normalized
+          submissionName: pickName('premission', goal, i),
+        };
+      })
     );
   }
 
@@ -210,7 +219,14 @@ export async function runMissions({ preMission, mission, postMission, tags = []
     missionName,
     maxTurns,
     retryLimit,
-    { domListLimit: domListLimitInfo?.value, debug: debugEnabled, resourceGuard, humanInput }
+    {
+      domListLimit: domListLimitInfo?.value,
+      automaticDomLimit: automaticDomLimitInfo.value,
+      storageStatePath: process.env.TESTRONAUT_STORAGE_STATE_PATH,
+      debug: debugEnabled,
+      resourceGuard,
+      humanInput,
+    }
   );
   if (!success) {
     console.log(`❌ Aborting after failed goal.`);

package/tests/binTests/cli.integration.test.js

@@ -37,10 +37,22 @@ describe('CLI inspection commands', () => {
     const result = run(makeProject(), ['list', '--json']);
     expect(result.status).toBe(0);
     expect(JSON.parse(result.stdout).missions).toEqual([
-      { file: 'login.mission.js', tags: ['authentication', 'smoke'] },
+      { file: 'login.mission.js', tags: ['authentication', 'smoke'], selected: true },
     ]);
   });
 
+  it('applies tag filters to list output', () => {
+    const result = run(makeProject(), ['list', '--tag=checkout', '--json']);
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout).missions[0].selected).toBe(false);
+  });
+
+  it('does not discard a following inline flag', () => {
+    const result = run(makeProject(), ['--model=gpt-5.6', '--turns=30', '--dry-run', '--json']);
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout).missions[0].file).toBe('missions/login.mission.js');
+  });
+
   it('reports effective config without exposing the session token', () => {
     const result = run(makeProject(), ['config', '--json']);
     expect(result.status).toBe(0);
@@ -74,4 +86,17 @@ describe('CLI inspection commands', () => {
     expect(result.status).toBe(0);
     expect(JSON.parse(result.stdout).missions[0].missionName).toBe('https://example.test');
   });
+
+  it('records shared-auth session mode in the report', () => {
+    const cwd = makeProject();
+    fs.writeFileSync(path.join(cwd, 'missions', 'login.mission.js'), [
+      'export const tags = ["authentication"];',
+      'export async function executeMission() {',
+      '  return { missionName: "login", submissionType: "mission", status: "passed", steps: [] };',
+      '}',
+    ].join('\n'));
+    const result = run(cwd, ['--session=shared-auth', '--json', '--quiet']);
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout).session).toEqual({ mode: 'shared-auth' });
+  });
 });

package/tests/coreTests/agent.test.js

@@ -6,6 +6,7 @@ vi.mock('../../tools/chromeBrowser.js', () => {
   function ChromeBrowser() {}
   ChromeBrowser.prototype.start = async function () {};
   ChromeBrowser.prototype.close = async function () {};
+  ChromeBrowser.prototype.probe = async function () { return { passed: true }; };
   return { ChromeBrowser };
 });
 
@@ -17,6 +18,7 @@ vi.mock('../../core/turnLoop.js', () => ({
 import { ChromeBrowser } from '../../tools/chromeBrowser.js';
 import { turnLoop } from '../../core/turnLoop.js';
 import { runAgent } from '../../core/agent.js';
+import { resetLaunchProtocols } from '../../core/launchProtocol.js';
 
 let startSpy, closeSpy;
 
@@ -26,6 +28,8 @@ describe('core/agent.runAgent', () => {
     startSpy = vi.spyOn(ChromeBrowser.prototype, 'start').mockResolvedValue();
     closeSpy = vi.spyOn(ChromeBrowser.prototype, 'close').mockResolvedValue();
     vi.clearAllMocks();
+    resetLaunchProtocols();
+    delete process.env.TESTRONAUT_SESSION_MODE;
   });
 
   afterEach(() => {
@@ -104,6 +108,63 @@ describe('core/agent.runAgent', () => {
     expect(res2[0].steps[0].result).toBe('SUCCESS: step2');
   });
 
+  it('attaches telemetry recorded during each goal to that result', async () => {
+    turnLoop.mockImplementationOnce(async (browser, messages, maxTurns, ct, rc, cs, ctx) => {
+      ctx.groundControl.telemetry.push({ kind: 'note', text: 'durable observation' });
+      return { success: true };
+    });
+    const [result] = await runAgent([{ goal: 'Observe' }], 'Telemetry', 3);
+    expect(result.telemetry).toEqual([{ kind: 'note', text: 'durable observation' }]);
+  });
+
+  it('reuses a completed launch protocol after a passing shared-auth probe', async () => {
+    process.env.TESTRONAUT_SESSION_MODE = 'shared-auth';
+    const probeSpy = vi.spyOn(ChromeBrowser.prototype, 'probe').mockResolvedValue({
+      passed: true,
+      url: 'https://example.test/dashboard',
+    });
+    const goal = {
+      goal: 'Log in',
+      submissionType: 'premission',
+      launchProtocol: { id: 'authenticated:user', probe: { selector: '#dashboard' } },
+    };
+    turnLoop.mockResolvedValueOnce({ success: true });
+    await runAgent([goal], 'First', 3);
+    turnLoop.mockResolvedValueOnce({ success: true });
+    const [reused] = await runAgent([
+      goal,
+      { goal: 'Use the current dashboard', submissionType: 'mission' },
+    ], 'Second', 3);
+
+    expect(turnLoop).toHaveBeenCalledTimes(2);
+    expect(probeSpy).toHaveBeenCalledWith({ selector: '#dashboard' });
+    expect(reused.launchProtocol).toEqual({ id: 'authenticated:user', status: 'reused', probe: 'passed' });
+    expect(reused.steps[0].tokensUsed).toBe(0);
+    const mainMessages = turnLoop.mock.calls[1][1];
+    expect(mainMessages[0].content).toContain('https://example.test/dashboard');
+    expect(mainMessages[0].content).toContain('"loggedIn": true');
+    probeSpy.mockRestore();
+  });
+
+  it('falls back to the original preMission when a reuse probe fails', async () => {
+    process.env.TESTRONAUT_SESSION_MODE = 'shared-auth';
+    const goal = {
+      goal: 'Log in',
+      submissionType: 'premission',
+      launchProtocol: { id: 'authenticated:user', probe: { selector: '#dashboard' } },
+    };
+    turnLoop.mockResolvedValue({ success: true });
+    await runAgent([goal], 'First', 3);
+    const probeSpy = vi.spyOn(ChromeBrowser.prototype, 'probe').mockResolvedValueOnce({ passed: false, reason: 'signed out' });
+    const [executed] = await runAgent([goal], 'Second', 3);
+
+    expect(turnLoop).toHaveBeenCalledTimes(2);
+    expect(executed.launchProtocol).toEqual({
+      id: 'authenticated:user', status: 'executed', probe: 'failed', reason: 'signed out',
+    });
+    probeSpy.mockRestore();
+  });
+
   it('includes missionName and submission metadata in results', async () => {
     turnLoop.mockResolvedValueOnce({ success: true });
 

package/tests/coreTests/config.test.js

@@ -13,6 +13,7 @@ import {
   resolveTurnLimits,
   enforceTurnBudget,
   getDomListLimit,
+  getAutomaticDomLimit,
   getResourceGuardConfig,
   getHumanInputConfig,
 } from '../../core/config.js';
@@ -21,6 +22,15 @@ describe('core/config', () => {
   beforeEach(() => {
     vi.resetAllMocks();
     delete process.env.STRICT_LIMITS;
+    delete process.env.TESTRONAUT_AUTO_DOM_LIMIT;
+  });
+
+  describe('getAutomaticDomLimit', () => {
+    it('uses config and clamps unsafe values', () => {
+      expect(getAutomaticDomLimit({ dom: { automaticLimit: 9000 } })).toMatchObject({ value: 9000, source: 'config' });
+      process.env.TESTRONAUT_AUTO_DOM_LIMIT = '250000';
+      expect(getAutomaticDomLimit({})).toMatchObject({ value: 100000, source: 'env', clamped: true });
+    });
   });
 
   describe('loadConfig', () => {

package/tests/coreTests/launchProtocol.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import {
+  launchProtocol,
+  unwrapLaunchProtocol,
+  hasCompletedLaunchProtocol,
+  markLaunchProtocolCompleted,
+  resetLaunchProtocols,
+} from '../../core/launchProtocol.js';
+
+describe('launchProtocol', () => {
+  beforeEach(() => resetLaunchProtocols());
+
+  it('wraps ordinary mission text without changing string coercion', () => {
+    const wrapped = launchProtocol('Log in', {
+      id: 'authenticated:user',
+      probe: { url: 'https://example.test', selector: '#dashboard' },
+    });
+    expect(String(wrapped)).toBe('Log in');
+    expect(unwrapLaunchProtocol(wrapped)).toEqual({
+      goal: 'Log in',
+      protocol: {
+        id: 'authenticated:user',
+        probe: { url: 'https://example.test', selector: '#dashboard' },
+      },
+    });
+  });
+
+  it('tracks completed protocol ids for one process run', () => {
+    expect(hasCompletedLaunchProtocol('auth')).toBe(false);
+    markLaunchProtocolCompleted('auth');
+    expect(hasCompletedLaunchProtocol('auth')).toBe(true);
+  });
+
+  it('rejects incomplete metadata', () => {
+    expect(() => launchProtocol('x', { probe: { selector: '#ready' } })).toThrow(/id/);
+    expect(() => launchProtocol('x', { id: 'ready', probe: {} })).toThrow(/selector or text/);
+  });
+});

package/tests/runnerTests/testronaut.test.js

@@ -11,15 +11,16 @@ vi.mock('../../core/config.js', () => ({
   enforceTurnBudget: vi.fn(),
   getRetryLimit: vi.fn(),
   getDomListLimit: vi.fn(),
+  getAutomaticDomLimit: vi.fn(),
   getResourceGuardConfig: vi.fn(),
   getHumanInputConfig: vi.fn(),
 }));
 
 import { runAgent } from '../../core/agent.js';
-import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getResourceGuardConfig, getHumanInputConfig } from '../../core/config.js';
+import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getAutomaticDomLimit, getResourceGuardConfig, getHumanInputConfig } from '../../core/config.js';
 
 // Adjust the import path if your file lives elsewhere
-import { runMissions, __test__ as testronautInternals } from '../../runner/testronaut.js';
+import { runMissions, launchProtocol, __test__ as testronautInternals } from '../../runner/testronaut.js';
 
 describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
   const OLD_ENV = { ...process.env };
@@ -29,6 +30,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     // Default retry limit unless overridden in a test
     getRetryLimit.mockReturnValue({ value: 2, source: 'default', clamped: false });
     getDomListLimit.mockReturnValue({ value: 3, mode: 'number', source: 'default', clamped: false });
+    getAutomaticDomLimit.mockReturnValue({ value: 15000, source: 'default', clamped: false });
     getResourceGuardConfig.mockReturnValue({ enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] });
     getHumanInputConfig.mockReturnValue({ enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false });
   });
@@ -58,13 +60,38 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
       expect.stringContaining('Clamping to 200')
     );
     expect(runAgent).toHaveBeenCalledWith(
-      expect.any(Array), 'Budgeted Run', 200, 2, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } }
+      expect.any(Array), 'Budgeted Run', 200, 2, { domListLimit: 3, automaticDomLimit: 15000, storageStatePath: undefined, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } }
     );
 
     warn.mockRestore();
     log.mockRestore();
   });
 
+  it('unwraps launch protocols while preserving preMission authoring', async () => {
+    loadConfig.mockResolvedValue({ maxTurns: 20 });
+    enforceTurnBudget.mockReturnValue({
+      effectiveMax: 20,
+      limits: { softMaxTurns: 50, hardMaxTurns: 200, hardMinTurns: 5 },
+      notes: [],
+    });
+    runAgent.mockResolvedValue([{ steps: [{ result: 'SUCCESS' }], status: 'passed' }]);
+    const protocol = launchProtocol('Log in', {
+      id: 'authenticated:user',
+      probe: { url: 'https://example.test', selector: '#dashboard' },
+    });
+
+    await runMissions({ preMission: protocol, mission: 'Test dashboard' }, 'Protocol mission');
+    const goals = runAgent.mock.calls[0][0];
+    expect(goals[0]).toMatchObject({
+      goal: 'Log in',
+      submissionType: 'premission',
+      launchProtocol: {
+        id: 'authenticated:user',
+        probe: { url: 'https://example.test', selector: '#dashboard' },
+      },
+    });
+  });
+
   it('does not warn when no notes are returned', async () => {
     loadConfig.mockResolvedValue({ maxTurns: 20 });
     enforceTurnBudget.mockReturnValue({
@@ -85,7 +112,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     await runMissions({ mission: 'No warnings' }, 'Clean');
 
     expect(warn).not.toHaveBeenCalled();
-    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Clean', 20, 3, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Clean', 20, 3, { domListLimit: 3, automaticDomLimit: 15000, storageStatePath: undefined, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
 
     warn.mockRestore();
     log.mockRestore();
@@ -213,7 +240,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     expect(goals[1].submissionName).toMatch(/^My Mission/);
 
     // Effective max turns and retry limit passed through
-    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'My Mission', 15, 2, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'My Mission', 15, 2, { domListLimit: 3, automaticDomLimit: 15000, storageStatePath: undefined, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
 
     log.mockRestore();
   });
@@ -252,7 +279,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
 
     await runMissions({ mission: 'Debug' }, 'Debug Mission');
 
-    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Debug Mission', 20, 2, { domListLimit: 3, debug: true, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Debug Mission', 20, 2, { domListLimit: 3, automaticDomLimit: 15000, storageStatePath: undefined, debug: true, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
 
     log.mockRestore();
   });

package/tests/toolsTests/chromeBrowserProbe.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChromeBrowser } from '../../tools/chromeBrowser.js';
+
+function makeBrowser({ visible = true, content = 'Mission Tasks' } = {}) {
+  const locator = {
+    first: () => locator,
+    waitFor: vi.fn(() => visible ? Promise.resolve() : Promise.reject(new Error('not visible'))),
+    textContent: vi.fn().mockResolvedValue(content),
+  };
+  const browser = Object.create(ChromeBrowser.prototype);
+  browser.page = {
+    goto: vi.fn().mockResolvedValue(undefined),
+    waitForLoadState: vi.fn().mockResolvedValue(undefined),
+    locator: vi.fn(() => locator),
+    url: vi.fn(() => 'https://example.test/dashboard'),
+  };
+  return { browser, locator };
+}
+
+describe('ChromeBrowser.probe', () => {
+  it('passes after navigating when selector and text match', async () => {
+    const { browser } = makeBrowser();
+    await expect(browser.probe({
+      url: 'https://example.test',
+      selector: '#dashboard',
+      text: 'Mission Tasks',
+    })).resolves.toMatchObject({ passed: true });
+    expect(browser.page.goto).toHaveBeenCalledWith('https://example.test', expect.any(Object));
+  });
+
+  it('fails without invoking an agent when the selector is not visible', async () => {
+    const { browser } = makeBrowser({ visible: false });
+    await expect(browser.probe({ selector: '#dashboard' })).resolves.toMatchObject({
+      passed: false,
+      reason: 'selector not visible: #dashboard',
+    });
+  });
+});

package/tests/toolsTests/domControl.test.js

@@ -16,6 +16,7 @@ import {
   collapseLongContent,
   chunkBySection,
   reduceRepeatedDivs,
+  reduceTableRows,
   removeObfuscatedClassNames,
   removeAutoGeneratedClasses,
   minifyDomWhitespace,
@@ -232,6 +233,17 @@ describe('domControl helpers', () => {
     });
   });
 
+  describe('reduceTableRows', () => {
+    it('keeps headers, trims body rows, and adds a marker', () => {
+      const $ = cheerio.load('<table><thead><tr><th>Name</th></tr></thead><tbody><tr><td>A</td></tr><tr><td>B</td></tr><tr><td>C</td></tr></tbody></table>');
+      reduceTableRows($, 2);
+      expect($('thead tr')).toHaveLength(1);
+      expect($('tbody > tr')).toHaveLength(3);
+      expect($('tbody > tr').eq(1).text()).toBe('B');
+      expect($('tbody > tr').eq(2).attr('data-collapsed')).toBe('true');
+    });
+  });
+
   describe('removeObfuscatedClassNames', () => {
     it('removes short and hashed-looking class names', () => {
       const html = `

package/tests/toolsTests/toolSchema.test.js

@@ -5,6 +5,11 @@ describe('tools/toolSchema', () => {
   it('does not advertise the unimplemented get_dom_chunk tool', () => {
     expect(toolsSchema.map(tool => tool.function.name)).not.toContain('get_dom_chunk');
   });
+
+  it('allows get_dom calls to be scoped by selector', () => {
+    const entry = toolsSchema.find(tool => tool.function.name === 'get_dom');
+    expect(entry.function.parameters.properties.selector.type).toBe('string');
+  });
   it('includes resource_progress tool with empty params', () => {
     const entry = toolsSchema.find(t => t.function?.name === 'resource_progress');
     expect(entry?.type).toBe('function');

package/tools/chromeBrowser.js

@@ -14,6 +14,7 @@ import * as cheerio from 'cheerio';
 import { 
   chunkBySection, 
   reduceRepeatedDivs, 
+  reduceTableRows,
   removeAutoGeneratedClasses, 
   removeNonContentTags,
   removeObfuscatedClassNames, 
@@ -57,6 +58,7 @@ export class ChromeBrowser {
     this.domListLimit = options.domListLimit;
     this.debugEnabled = !!options.debug;
     this._domLimitLogged = false;
+    this.storageStatePath = options.storageStatePath;
 
     const defaultResourceGuard = {
       enabled: true,
@@ -601,9 +603,12 @@ export class ChromeBrowser {
 
     ensureDir(FILES_DIR); // ⬅️ make sure missions/files exists
 
-    this.context = await this.browser.newContext({
-      acceptDownloads: true // ⬅️ important for Playwright download handling
-    });
+    const contextOptions = { acceptDownloads: true };
+    if (this.storageStatePath && fs.existsSync(this.storageStatePath)) {
+      contextOptions.storageState = this.storageStatePath;
+      this._debugLog('Restoring shared authentication state', { path: this.storageStatePath });
+    }
+    this.context = await this.browser.newContext(contextOptions);
     // this.context = await this.browser.newContext();
     const first = await this.context.newPage();
     const id = this._addAndFocus(first);
@@ -636,6 +641,26 @@ export class ChromeBrowser {
     return `navigated to ${this.page.url()}`;
   }
 
+  async probe({ url, selector, text, timeout = 5000 } = {}) {
+    if (url) {
+      await this.page.goto(url, { timeout: 30_000, waitUntil: 'domcontentloaded' });
+      await this.page.waitForLoadState('domcontentloaded').catch(() => {});
+    }
+
+    let locator = this.page.locator(selector || 'body').first();
+    if (selector) {
+      const visible = await locator.waitFor({ state: 'visible', timeout }).then(() => true).catch(() => false);
+      if (!visible) return { passed: false, reason: `selector not visible: ${selector}`, url: this.page.url() };
+    }
+    if (text) {
+      const content = await locator.textContent({ timeout }).catch(() => '');
+      if (!String(content || '').includes(String(text))) {
+        return { passed: false, reason: `text not found: ${text}`, url: this.page.url() };
+      }
+    }
+    return { passed: true, url: this.page.url() };
+  }
+
   async navigateEmailLink({ url, allowedHosts = [] }) {
     const destination = new URL(url);
     if (destination.protocol !== 'https:' || destination.username || destination.password) {
@@ -859,7 +884,7 @@ export class ChromeBrowser {
 
 
   async get_dom(
-    { limit = 100000, exclude = true, focus = [], loadState = 'networkidle', timeout = 10000 } = {},
+    { limit = 100000, exclude = true, selector, focus = [], loadState = 'networkidle', timeout = 10000 } = {},
     agentMemory = {}
   ) {
     const matchesHrefPattern = (href = '') => {
@@ -985,9 +1010,21 @@ export class ChromeBrowser {
     // --- 4) Optional DOM reduction/cleanup (your existing steps) ---
     let $ = cheerio.load(html);
 
+    if (selector) {
+      let selection;
+      try {
+        selection = $(selector);
+      } catch (error) {
+        throw new Error(`Invalid get_dom selector "${selector}": ${error.message}`);
+      }
+      if (!selection.length) return `[get_dom: no elements matched selector "${selector}"]`;
+      $ = cheerio.load(selection.toString());
+    }
+
     if (exclude) {
       $ = await removeNonContentTags($);
       $ = await reduceRepeatedDivs($, listLimit);
+      reduceTableRows($, listLimit);
       // If you later re-enable:
       // $ = await removeObfuscatedClassNames($);
       // $ = await removeAutoGeneratedClasses($);
@@ -1386,7 +1423,15 @@ export class ChromeBrowser {
 
 
   async close() {
-    await this.browser?.close();
+    try {
+      if (this.storageStatePath && this.context) {
+        ensureDir(path.dirname(this.storageStatePath));
+        await this.context.storageState({ path: this.storageStatePath, indexedDB: true });
+        this._debugLog('Saved shared authentication state', { path: this.storageStatePath });
+      }
+    } finally {
+      await this.browser?.close();
+    }
   }
 }
 

package/tools/domControl.js

@@ -123,7 +123,7 @@ export const chunkBySection = async ($, focus) => {
     footer: $('footer').html() || '',
     aside: $('aside').html() || '',
     body: $('body').html() || ''
-  };
+};
 
   if (Array.isArray(focus) && focus.length > 0) {
     return Object.fromEntries(
@@ -144,6 +144,25 @@ export const chunkBySection = async ($, focus) => {
 
 }
 
+/** Keep table headers and only the first N body rows in each table. */
+export function reduceTableRows($, maxAllowed = 3) {
+  let limit = maxAllowed === Infinity ? Infinity : Number(maxAllowed);
+  if (limit === Infinity) return;
+  limit = Number.isFinite(limit) ? Math.max(0, limit) : 3;
+
+  $('table').each((_, table) => {
+    const $table = $(table);
+    const rows = $table.find('tbody > tr');
+    const candidates = rows.length ? rows : $table.children('tr');
+    if (candidates.length <= limit) return;
+    candidates.slice(limit).remove();
+    const colspan = Math.max(1, $table.find('tr').first().children('th, td').length);
+    const marker = `<tr data-collapsed="true"><td colspan="${colspan}">[...truncated]</td></tr>`;
+    if (rows.length) $table.children('tbody').first().append(marker);
+    else $table.append(marker);
+  });
+}
+
 /**
  * Reduce repeated sibling <div> blocks that share the same class name.
  * - For each parent <body> or <div>, group child divs by `class`.

package/tools/generateHtmlReport.js

@@ -102,7 +102,7 @@ export function generateHtmlReport(report, outputPath) {
             ${humanInput}
             ${planSpan}
             <span class="step-result ${ok ? 'ok' : 'bad'}" ${resultTooltip ? `title="${esc(resultTooltip)}"` : ''}>${esc(resultRaw)}</span>
-            <span class="tokens">tokens: ${esc(step.tokensUsed ?? '—')} / total: ${esc(step.totalTokensUsed ?? '—')}</span>
+            <span class="tokens">tokens: ${esc(step.tokensUsed ?? '—')} (in: ${esc(step.inputTokens ?? '—')}, out: ${esc(step.outputTokens ?? '—')}) / rolling: ${esc(step.totalTokensUsed ?? '—')}</span>
           </summary>
           <pre class="events">${esc(events.join('\n')) || '(no events)'}</pre>
           ${imgTag}

package/tools/toolSchema.js

@@ -83,6 +83,10 @@ const toolsSchema = [
             default: true,
             description: 'Whether to exclude noisy tags like script/style/etc.',
           },
+          selector: {
+            type: 'string',
+            description: 'Optional CSS selector that scopes the returned DOM to matching elements.',
+          },
         },
       },
     },