testronaut 2.1.1 → 2.1.3

package/TODO.md

@@ -12,6 +12,7 @@
 ## Browser Automation Follow-Ups
 
 - [x] Make `click_text` match exact text, prefer the innermost visible element, and fail quickly instead of clicking an ancestor or partial match.
+- [ ] Complete `press_key` turn-loop integration: classify it as fire-and-forget, automatically inject the updated DOM after successful key presses, and test that Enter/Escape state changes are available to the next reasoning turn without an explicit `get_dom` call.
 - [ ] Replace framework/vendor-specific DOM class stripping with a framework-agnostic classifier that removes generated hashes, styling utilities, variants, and arbitrary selectors while preserving semantic component classes. Reconsider broad prefix rules such as `/^cl-/`, cap retained class count and length, and add representative fixtures for Tailwind, MUI, Ant Design, Chakra, Clerk, CSS Modules, and CSS-in-JS.
 
 ## Session and Reporting Follow-Ups
@@ -27,9 +28,18 @@
 
 ## Optimization and Rate-Limit Follow-Ups
 
+- [ ] Reduce redundant screenshot capture in focused missions without weakening evidence: clarify or enforce when starting, transition, and final screenshots materially differ, and measure the effect on turns, tokens, and report usefulness.
 - [ ] Run a history-informed model-routing benchmark before expanding cross-provider routing. Give Jev versioned, per-model/per-mission-class reliability, token, latency, and price observations from prior runs; require a configurable reliability floor; compare against the best fixed-model-plus-guardrails control with blocked repetitions; keep selection at the mission boundary; record the evidence and reason for every choice; and define cold-start, stale-data, low-confidence, and provider-failure fallbacks. Do not retry a failed mission on another provider in the benchmark because that would confound routing quality with retry recovery.
 - [ ] Add an opt-in CLI/config policy that reroutes an imminent throttled LLM request to a compatible model as an alternative to the default backoff behavior. Keep backoff as the default; use observed TPM/RPM headroom and projected request tokens; constrain failover to explicitly configured provider/model families; preserve tool/history compatibility; prevent routing loops; fall back safely when the alternate model is unavailable; and record the original model, routed model, trigger, token usage, latency, and outcome in reports.
 
+## OpenAI Provider Follow-Ups
+
+- [ ] Migrate the OpenAI adapter from Chat Completions to the Responses API in a dedicated change. Preserve Testronaut's provider-neutral message and tool-call contract, add response-ID/reasoning-state handling, normalize usage and raw headers, and cover multi-turn tool continuation with unit and API smoke tests. Once migrated, remove the GPT-5.6 Chat Completions compatibility override that sets `reasoning_effort` to `none` for function-tool requests.
+- [ ] Add active context budgeting after its behavior is designed and tested. Use model context/output metadata to reserve response and reasoning capacity, then apply explicit history compaction or summarization rules. Do not silently truncate mission instructions, current DOM state, or unmatched tool calls.
+- [ ] Learn effective OpenAI TPM/RPM limits from successful response headers and rate-limit errors. Prefer observed project/model limits over inferring a named account tier; retain the environment override and conservative startup values.
+- [ ] Persist provider-observed rate limits in a separate, expiring local cache keyed by provider, API project/account, endpoint/region, model, and traffic type. Never rewrite user config or infer a named usage tier from a TPM value; expose configured, cached, and live sources distinctly and discard stale observations.
+- [ ] After dynamic rate limits are established, make DOM injection quota-aware. Budget DOM tokens against both remaining TPM and the model context window, preserve mission instructions and actionable controls, and fall back to semantic sections plus on-demand DOM chunks instead of silent truncation.
+
 ## Automated MFA Follow-Ups
 
 - [ ] Add an integration smoke test against a local or staging API fixture for `get_mfa_code`.

package/package.json

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

package/tests/toolsTests/chromeBrowserClickText.test.js

@@ -69,4 +69,44 @@ describe('ChromeBrowser.check_text', () => {
 
     await expect(browser.check_text({ text: 'Hidden message' })).resolves.toBe('NOT FOUND: Hidden message');
   });
+
+  it('reports the iframe containing a visible match', async () => {
+    const noMatches = { count: vi.fn().mockResolvedValue(0) };
+    const frameMatches = {
+      count: vi.fn().mockResolvedValue(1),
+      nth: vi.fn().mockReturnValue({ isVisible: vi.fn().mockResolvedValue(true) }),
+    };
+    const mainFrame = { getByText: vi.fn().mockReturnValue(noMatches) };
+    const childFrame = {
+      getByText: vi.fn().mockReturnValue(frameMatches),
+      name: vi.fn().mockReturnValue(''),
+      frameElement: vi.fn().mockResolvedValue({ getAttribute: vi.fn().mockResolvedValue('webviewer-1') }),
+      url: vi.fn().mockReturnValue('https://example.test/viewer'),
+    };
+    const browser = Object.create(ChromeBrowser.prototype);
+    browser.page = {
+      mainFrame: vi.fn().mockReturnValue(mainFrame),
+      frames: vi.fn().mockReturnValue([mainFrame, childFrame]),
+    };
+
+    await expect(browser.check_text({ text: 'Quarterly report' }))
+      .resolves.toBe('FOUND in frame webviewer-1: Quarterly report');
+  });
+});
+
+describe('ChromeBrowser iframe interaction targeting', () => {
+  it('builds an explicit frame-qualified click locator', () => {
+    const locator = { first: vi.fn().mockReturnThis() };
+    const frameContext = { locator: vi.fn().mockReturnValue(locator) };
+    const browser = Object.create(ChromeBrowser.prototype);
+    browser.page = { frameLocator: vi.fn().mockReturnValue(frameContext) };
+
+    const [make] = browser._buildClickCandidates({
+      frame: 'iframe#webviewer-1', selector: 'button[aria-label="Settings"]', searchAllFrames: true,
+    });
+
+    expect(make()).toBe(locator);
+    expect(browser.page.frameLocator).toHaveBeenCalledWith('iframe#webviewer-1');
+    expect(frameContext.locator).toHaveBeenCalledWith('button[aria-label="Settings"]');
+  });
 });

package/tests/toolsTests/chromeBrowserGetDomFrames.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChromeBrowser } from '../../tools/chromeBrowser.js';
+
+describe('ChromeBrowser.get_dom iframe serialization', () => {
+  it('keeps serialized same-origin content and inaccessible-frame markers', async () => {
+    const browser = Object.create(ChromeBrowser.prototype);
+    browser.domListLimit = 3;
+    browser.debugEnabled = false;
+    browser.context = null;
+    browser.page = {
+      isClosed: vi.fn().mockReturnValue(false),
+      waitForLoadState: vi.fn().mockResolvedValue(undefined),
+      content: vi.fn().mockResolvedValue('<html><body></body></html>'),
+      evaluate: vi.fn().mockResolvedValue(`
+        <html><body>
+          <testronaut-frame id="viewer" data-testronaut-frame="viewer" data-testronaut-frame-status="same-origin">
+            <html><body><button aria-label="Settings">Settings</button><p>Quarterly report</p></body></html>
+          </testronaut-frame>
+          <testronaut-frame id="payment" data-testronaut-frame="payment" data-testronaut-frame-status="cross-origin">
+            [cross-origin frame, content not accessible]
+          </testronaut-frame>
+        </body></html>`),
+    };
+
+    const result = await browser.get_dom();
+
+    expect(result).toContain('data-testronaut-frame="viewer"');
+    expect(result).toContain('<iframe');
+    expect(result).toContain('Quarterly report');
+    expect(result).toContain('aria-label="Settings"');
+    expect(result).toContain('[cross-origin frame, content not accessible]');
+  });
+});

package/tests/toolsTests/chromeBrowserPressKey.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from 'vitest';
+import { CHROME_TOOL_MAP, ChromeBrowser } from '../../tools/chromeBrowser.js';
+
+describe('ChromeBrowser.press_key', () => {
+  it('presses a key on the active page', async () => {
+    const browser = new ChromeBrowser();
+    browser.page = { keyboard: { press: vi.fn().mockResolvedValue(undefined) } };
+
+    await expect(browser.press_key({ key: 'Escape' })).resolves.toBe('pressed Escape');
+    expect(browser.page.keyboard.press).toHaveBeenCalledWith('Escape');
+  });
+
+  it('focuses a selected element before pressing Enter', async () => {
+    const browser = new ChromeBrowser();
+    const focus = vi.fn().mockResolvedValue(undefined);
+    const first = vi.fn().mockReturnValue({ focus });
+    browser.page = {
+      locator: vi.fn().mockReturnValue({ first }),
+      keyboard: { press: vi.fn().mockResolvedValue(undefined) },
+    };
+
+    await expect(browser.press_key({ key: 'Enter', selector: '#email' }))
+      .resolves.toBe('pressed Enter after focusing #email');
+
+    expect(browser.page.locator).toHaveBeenCalledWith('#email');
+    expect(first).toHaveBeenCalledOnce();
+    expect(focus).toHaveBeenCalledWith({ timeout: 3000 });
+    expect(browser.page.keyboard.press).toHaveBeenCalledWith('Enter');
+    expect(focus.mock.invocationCallOrder[0])
+      .toBeLessThan(browser.page.keyboard.press.mock.invocationCallOrder[0]);
+  });
+
+  it('is exposed through the browser tool dispatcher', async () => {
+    const press_key = vi.fn().mockResolvedValue('pressed Control+B');
+    await expect(CHROME_TOOL_MAP.press_key({ press_key }, { key: 'Control+B' }))
+      .resolves.toBe('pressed Control+B');
+    expect(press_key).toHaveBeenCalledWith({ key: 'Control+B' });
+  });
+});

package/tests/toolsTests/domControl.test.js

@@ -56,7 +56,7 @@ describe('domControl helpers', () => {
       expect(result).not.toContain('<style');
       expect(result).not.toContain('<meta');
       expect(result).not.toContain('<link');
-      expect(result).not.toContain('<iframe');
+      expect(result).toContain('<iframe src="frame.html"></iframe>');
       expect(result).not.toContain('<canvas');
       expect(result).not.toContain('<svg');
       expect(result).not.toContain('<!-- comment -->');

package/tests/toolsTests/toolSchema.test.js

@@ -21,6 +21,20 @@ describe('tools/toolSchema', () => {
     const entry = toolsSchema.find(tool => tool.function.name === 'get_dom');
     expect(entry.function.parameters.properties.selector.type).toBe('string');
   });
+  it('includes press_key with a required key and optional selector', () => {
+    const entry = toolsSchema.find(tool => tool.function.name === 'press_key');
+    expect(entry?.function.parameters.required).toEqual(['key']);
+    expect(entry.function.parameters.properties.key.type).toBe('string');
+    expect(entry.function.parameters.properties.selector.type).toBe('string');
+  });
+  it('exposes iframe targeting and iframe text search', () => {
+    const fill = toolsSchema.find(tool => tool.function.name === 'fill');
+    const click = toolsSchema.find(tool => tool.function.name === 'click');
+    const checkText = toolsSchema.find(tool => tool.function.name === 'check_text');
+    expect(fill.function.parameters.properties.frame.type).toBe('string');
+    expect(click.function.parameters.properties.frame.type).toBe('string');
+    expect(checkText.function.parameters.properties.searchAllFrames.default).toBe(true);
+  });
   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

@@ -180,8 +180,13 @@ export class ChromeBrowser {
   }
 
   // Build candidate locator MAKERS (Page|Frame-aware)
-  _buildClickCandidates({ selector, text, role, attrs, scope, searchAllFrames }) {
-    const frames = searchAllFrames ? this._allFrames({ includeMain: true }) : [this.page.mainFrame()];
+  _interactionContexts(frame, searchAllFrames) {
+    if (frame) return [this.page.frameLocator(frame)];
+    return searchAllFrames ? this._allFrames({ includeMain: true }) : [this.page.mainFrame()];
+  }
+
+  _buildClickCandidates({ selector, text, role, attrs, scope, searchAllFrames, frame }) {
+    const frames = this._interactionContexts(frame, searchAllFrames);
     const makers = [];
     const add = (fn) => fn && makers.push(fn);
 
@@ -211,8 +216,9 @@ export class ChromeBrowser {
       }
     }
 
-    const seen = new Set();
-    return makers.filter(fn => { const k = fn.toString(); if (seen.has(k)) return false; seen.add(k); return true; });
+    // Do not de-duplicate by function source: closures for different frames have
+    // identical source text but resolve against different documents.
+    return makers;
   }
 
 
@@ -459,8 +465,8 @@ export class ChromeBrowser {
   }
 
   // Build candidates for text entry (Page|Frame-aware)
-  _buildFillCandidates({ selector, placeholder, role = 'textbox', attrs, scope, searchAllFrames }) {
-    const frames = searchAllFrames ? this._allFrames({ includeMain: true }) : [this.page.mainFrame()];
+  _buildFillCandidates({ selector, placeholder, role = 'textbox', attrs, scope, searchAllFrames, frame }) {
+    const frames = this._interactionContexts(frame, searchAllFrames);
     const makers = [];
     const add = (fn) => fn && makers.push(fn);
 
@@ -499,9 +505,9 @@ export class ChromeBrowser {
       }
     }
 
-    // de-dup
-    const seen = new Set();
-    return makers.filter(fn => { const k = fn.toString(); if (seen.has(k)) return false; seen.add(k); return true; });
+    // Do not de-duplicate by function source: closures for different frames have
+    // identical source text but resolve against different documents.
+    return makers;
   }
 
 
@@ -714,6 +720,7 @@ export class ChromeBrowser {
   async fill({
     selector,
     text,
+    frame,
     placeholder,          // string | RegExp
     role = 'textbox',     // generic default
     attrs,
@@ -729,9 +736,9 @@ export class ChromeBrowser {
 
     const makeCandidates = () => {
       if (strategy === 'strict') {
-        return this._buildFillCandidates({ selector, scope, searchAllFrames });
+        return this._buildFillCandidates({ selector, scope, searchAllFrames, frame });
       }
-      return this._buildFillCandidates({ selector, placeholder, role, attrs, scope, searchAllFrames });
+      return this._buildFillCandidates({ selector, placeholder, role, attrs, scope, searchAllFrames, frame });
     };
 
     return this._withRetries(async () => {
@@ -764,6 +771,18 @@ export class ChromeBrowser {
     }, { attempts: 3, baseMs: 250 });
   }
 
+  async press_key({ key, selector }) {
+    if (selector) {
+      const target = this.page.locator(selector).first();
+      await target.focus({ timeout: 3000 });
+    }
+
+    await this.page.keyboard.press(key);
+    return selector
+      ? `pressed ${key} after focusing ${selector}`
+      : `pressed ${key}`;
+  }
+
 
 
   /**
@@ -778,7 +797,7 @@ export class ChromeBrowser {
    * @param {number}          [opts.delayMs=200]       // micro settle
    */
   async click({
-    selector, text, role, attrs, scope,
+    selector, text, role, attrs, scope, frame,
     searchAllFrames = true,
     strategy = 'auto',
     waitFor,   
@@ -794,8 +813,8 @@ export class ChromeBrowser {
 
     // Build your candidates the way you already do (generic/hint-driven)
     const makers = (strategy === 'strict')
-      ? this._buildClickCandidates({ selector, scope, searchAllFrames })
-      : this._buildClickCandidates({ selector, text, role, attrs, scope, searchAllFrames });
+      ? this._buildClickCandidates({ selector, scope, searchAllFrames, frame })
+      : this._buildClickCandidates({ selector, text, role, attrs, scope, searchAllFrames, frame });
 
     // choose & click (same as your generic version)
     let chosen = null;
@@ -1014,9 +1033,57 @@ export class ChromeBrowser {
     // Fallback to empty string if still nothing (keeps caller logic simple)
     if (!html) html = '';
 
+    // page.content() only serializes iframe elements, not their documents. Build a
+    // read-only clone that embeds accessible frame documents so selectors and the
+    // global output limit apply to the complete snapshot.
+    try {
+      html = await this.page.evaluate(() => {
+        const serializeDocument = (doc) => {
+          const clone = doc.documentElement.cloneNode(true);
+          const sourceFrames = Array.from(doc.querySelectorAll('iframe'));
+          const clonedFrames = Array.from(clone.querySelectorAll('iframe'));
+
+          sourceFrames.forEach((sourceFrame, index) => {
+            const clonedFrame = clonedFrames[index];
+            if (!clonedFrame) return;
+            // iframe is a raw-text element in HTML parsers. Use a temporary
+            // custom element so Cheerio parses the embedded controls as markup.
+            const serializedFrame = doc.createElement('testronaut-frame');
+            for (const attribute of Array.from(clonedFrame.attributes)) {
+              serializedFrame.setAttribute(attribute.name, attribute.value);
+            }
+            clonedFrame.replaceWith(serializedFrame);
+            const label = sourceFrame.id || sourceFrame.name || sourceFrame.getAttribute('src') || `frame-${index + 1}`;
+            serializedFrame.setAttribute('data-testronaut-frame', label);
+            try {
+              const childDocument = sourceFrame.contentDocument;
+              if (!childDocument?.documentElement) throw new Error('inaccessible');
+              serializedFrame.setAttribute('data-testronaut-frame-status', 'same-origin');
+              serializedFrame.innerHTML = serializeDocument(childDocument);
+            } catch {
+              serializedFrame.setAttribute('data-testronaut-frame-status', 'cross-origin');
+              serializedFrame.textContent = '[cross-origin frame, content not accessible]';
+            }
+          });
+
+          return clone.outerHTML;
+        };
+        return serializeDocument(document);
+      });
+    } catch {
+      // Preserve the main-document snapshot if serialization races a navigation.
+    }
+
     // --- 4) Optional DOM reduction/cleanup (your existing steps) ---
     let $ = cheerio.load(html);
 
+    // Restore the public marker shape after the HTML parser has materialized
+    // the temporary element's descendants.
+    $('testronaut-frame').each((_, element) => {
+      element.name = 'iframe';
+      element.tagName = 'iframe';
+    });
+
     if (selector) {
       let selection;
       try {
@@ -1141,12 +1208,27 @@ export class ChromeBrowser {
   }
 
   
-  async check_text({ text }) {
-    const matches = this.page.getByText(text);
-    const count = await matches.count();
-    for (let index = 0; index < count; index++) {
-      if (await matches.nth(index).isVisible().catch(() => false)) {
-        return `FOUND: ${text}`;
+  async check_text({ text, searchAllFrames = true }) {
+    const mainFrame = this.page.mainFrame?.();
+    const frames = searchAllFrames && this.page.frames
+      ? [mainFrame, ...this.page.frames().filter(frame => frame !== mainFrame)].filter(Boolean)
+      : [mainFrame || this.page];
+
+    for (const frame of frames) {
+      const matches = frame.getByText(text);
+      const count = await matches.count();
+      for (let index = 0; index < count; index++) {
+        if (!await matches.nth(index).isVisible().catch(() => false)) continue;
+        if (frame === mainFrame || frame === this.page) return `FOUND: ${text}`;
+
+        let label = frame.name?.() || '';
+        if (!label) {
+          label = await frame.frameElement?.()
+            .then(element => element.getAttribute('id'))
+            .catch(() => '') || '';
+        }
+        label ||= frame.url?.() || 'unnamed';
+        return `FOUND in frame ${label}: ${text}`;
       }
     }
     return `NOT FOUND: ${text}`;
@@ -1455,6 +1537,7 @@ export const CHROME_TOOL_MAP = {
   reload: (b) => b.reload(),
   fill: (b, args) => b.fill(args),
   click: (b, args) => b.click(args),
+  press_key: (b, args) => b.press_key(args),
   get_dom: (b, args, agentMemory) => b.get_dom(args, agentMemory),
   check_text: (b, args) => b.check_text(args),
   click_text: async (browser, args, agentMemory) => {

package/tools/domControl.js

@@ -7,7 +7,7 @@
  *   normalize, and compress HTML so it’s cheaper and clearer for LLMs.
  *
  * Responsibilities:
- *   - Remove non-content tags (scripts, styles, iframes, etc.) and noisy attributes.
+ *   - Remove non-content tags (scripts, styles, etc.) and noisy attributes.
  *   - Collapse overly long lists/sections into truncated markers.
  *   - Reduce repeated div blocks to a representative sample.
  *   - Strip obfuscated/utility CSS classes that don’t help reasoning.
@@ -23,7 +23,8 @@
 
 /**
  * Remove tags and attributes that are unlikely to help LLM reasoning.
- * - Strips: script, style, meta, link, noscript, iframe, canvas, svg
+ * - Strips: script, style, meta, link, noscript, canvas, svg
+ * - Keeps iframe shells and any same-origin content injected by get_dom.
  * - Keeps only a safe whitelist of attributes on remaining elements.
  * - Removes HTML comments.
  *
@@ -31,7 +32,7 @@
  * @returns {$} same Cheerio instance for chaining
  */
 export const removeNonContentTags = async ($) => {
-  $('script, style, meta, link, noscript, iframe, canvas, svg').remove();
+  $('script, style, meta, link, noscript, canvas, svg').remove();
   
   $('*').each((_, el) => {
     const $el = $(el);
@@ -39,6 +40,7 @@ export const removeNonContentTags = async ($) => {
       'href', 'src', 'type', 'alt', 'title',
       'placeholder', 'name', 'id', 'class', 'value',
       'data-testid', 'disabled', 'role', 'data-state',
+      'data-testronaut-frame', 'data-testronaut-frame-status',
       // keep key data-* attributes that help identify rows/items without bloating too much
       'data-type', 'data-id', 'data-title', 'data-parentid', 'data-order'
     ];

package/tools/toolSchema.js

@@ -44,6 +44,7 @@ const toolsSchema = [
         properties: {
           selector: { type: 'string' },
           text: { type: 'string' },
+          frame: { type: 'string', description: 'Optional CSS selector for the containing iframe.' },
         },
         required: ['selector', 'text'],
       },
@@ -58,6 +59,7 @@ const toolsSchema = [
         type: 'object',
         properties: {
           selector: { type: 'string' },
+          frame: { type: 'string', description: 'Optional CSS selector for the containing iframe.' },
           waitFor: {
             type: 'string',
             enum: ['load', 'domcontentloaded', 'networkidle'],
@@ -73,6 +75,27 @@ const toolsSchema = [
       },
     },
   },
+  {
+    type: 'function',
+    function: {
+      name: 'press_key',
+      description: 'Press a keyboard key or shortcut, optionally focusing an element by CSS selector first',
+      parameters: {
+        type: 'object',
+        properties: {
+          key: {
+            type: 'string',
+            description: 'Playwright key or shortcut, such as Enter, Escape, Control+B, or Meta+B',
+          },
+          selector: {
+            type: 'string',
+            description: 'Optional CSS selector of the element to focus before pressing the key',
+          },
+        },
+        required: ['key'],
+      },
+    },
+  },
   {
     type: 'function',
     function: {
@@ -108,6 +131,11 @@ const toolsSchema = [
         type: 'object',
         properties: {
           text: { type: 'string' },
+          searchAllFrames: {
+            type: 'boolean',
+            default: true,
+            description: 'Search iframe documents as well as the main document.',
+          },
         },
         required: ['text'],
       },

package/todo.md

@@ -1,25 +0,0 @@
-# Testronaut CLI TODO
-
-## OpenAI provider follow-ups
-
-- Migrate the OpenAI adapter from Chat Completions to the Responses API in a
-  dedicated change. Preserve Testronaut's provider-neutral message and tool-call
-  contract, add response-ID/reasoning-state handling, normalize usage and raw
-  headers, and cover multi-turn tool continuation with unit and API smoke tests.
-  Once migrated, remove the GPT-5.6 Chat Completions compatibility override that
-  sets `reasoning_effort` to `none` for function-tool requests.
-- Add active context budgeting after its behavior is designed and tested. Use
-  model context/output metadata to reserve response and reasoning capacity, then
-  apply explicit history compaction or summarization rules. Do not silently
-  truncate mission instructions, current DOM state, or unmatched tool calls.
-- Learn effective OpenAI TPM/RPM limits from successful response headers and
-  rate-limit errors. Prefer observed project/model limits over inferring a named
-  account tier; retain the environment override and conservative startup values.
-- Persist provider-observed rate limits in a separate, expiring local cache keyed
-  by provider, API project/account, endpoint/region, model, and traffic type.
-  Never rewrite user config or infer a named usage tier from a TPM value; expose
-  configured, cached, and live sources distinctly and discard stale observations.
-- After dynamic rate limits are established, make DOM injection quota-aware.
-  Budget DOM tokens against both remaining TPM and the model context window,
-  preserve mission instructions and actionable controls, and fall back to
-  semantic sections plus on-demand DOM chunks instead of silent truncation.