Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

agent: track finite collection read progress

Emre Sokullua46fc662c92c
diff --git a/package.json b/package.json
index 5043d0d0f..221de5cb8 100644
--- a/package.json
+++ b/package.json
@@ -53,7 +53,7 @@
"benchmark:relevance": "node scripts/benchmark-offline-relevance.mjs --verbose",
"test:social-contract": "node --test test/social-publish-contract.mjs",
"test:social-contract:dom": "node test/social-publish-contract-dom.mjs",
- "test:runtime-lifecycle": "node --test test/agent-lifecycle.mjs test/runtime-lifecycle.mjs test/network-lifecycle.mjs test/text-write-cancellation.mjs test/chat-steering.mjs test/page-feedback.mjs test/page-feedback-progress.mjs test/page-feedback-policy.mjs test/page-feedback-transport-races.mjs test/page-feedback-recovery.mjs test/media-download-agent-handler.mjs && node test/ui-content-lifecycle.mjs && node --test test/chat-steering-ui.mjs test/page-monitor-ui.mjs test/page-monitor-passive-progress.mjs test/media-download-binding.mjs test/media-download-capture-integration.mjs",
+ "test:runtime-lifecycle": "node --test test/agent-lifecycle.mjs test/runtime-lifecycle.mjs test/collection-read-progress.mjs test/network-lifecycle.mjs test/text-write-cancellation.mjs test/chat-steering.mjs test/page-feedback.mjs test/page-feedback-progress.mjs test/page-feedback-policy.mjs test/page-feedback-transport-races.mjs test/page-feedback-recovery.mjs test/media-download-agent-handler.mjs && node test/ui-content-lifecycle.mjs && node --test test/chat-steering-ui.mjs test/page-monitor-ui.mjs test/page-monitor-passive-progress.mjs test/media-download-binding.mjs test/media-download-capture-integration.mjs",
"test:page-feedback": "node --test test/page-feedback.mjs test/page-feedback-progress.mjs test/page-feedback-policy.mjs test/page-feedback-transport-races.mjs test/page-feedback-recovery.mjs test/media-download-agent-handler.mjs test/page-monitor-ui.mjs test/page-monitor-passive-progress.mjs test/media-download-binding.mjs test/media-download-capture-integration.mjs",
"test:chat-steering": "node --test test/chat-steering.mjs test/chat-steering-ui.mjs",
"test:rich-text-dom": "node test/ui-content-lifecycle.mjs --dom",
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 42b447244..69ec89502 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -17,6 +17,7 @@ import { handleDoneJson } from './cloud-output.js';
import { applyReadPageWindow, fitReadPageWindowResult, isReadPageWindowResult } from './read-page-window.js';
import { STANDARD_TOOL_RESULT_CHARS, createReadCompletenessState, isCommunicationThreadContext, normalizeReadScope, readCompletenessBlock, readCompletenessLimitation, readCompletenessMadeProgress, readWindowLimits, recordReadCompleteness, requirePlannerReadCompleteness, requiresCompleteThreadRead } from './read-completeness.js';
import { LoopDetector } from './loop-detector.js';
+import { recordCollectionReadProgress } from './collection-read-progress.js';
import { parseToolCallsFromText } from './tool-call-parser.js';
import { IMAGE_BUDGET, estimateImageTokens, fitImageDimensions } from './image-budget.js';
import { BROWSER_MUTATION_TOOLS, STATE_CHANGE_TOOLS as SHARED_STATE_CHANGE_TOOLS } from './mutation-tools.js';
@@ -1095,6 +1096,7 @@ export class Agent extends LoopDetector {
// useful result before exhausting the run.
this.deliveryObservationStreaks = new Map(); // tabId -> count
this.deliveryActionableDiscoveryResets = new Set(); // tabIds that used their one discovery reset since meaningful progress
+ this.deliveryCollectionReads = new Map(); // tabId -> task-bound finite source coverage
this.lastAutoScreenshotTs = new Map(); // tabId -> ms — defensive debounce
// tabId -> { toolName, streak }. Burst state must not leak across tabs or
// be consumed by read-only preflight checks.
@@ -7855,6 +7857,13 @@ export class Agent extends LoopDetector {
return { method, requestShape, failed };
}
+ // Source coverage survives navigation and page-level loop resets. Only a
+ // run boundary may forget it and register the same source ranges again.
+ _clearRunLoopState(tabId) {
+ super._clearRunLoopState(tabId);
+ this.deliveryCollectionReads.delete(tabId);
+ }
+
/**
* Extends the detector's own page-scoped cleanup with the Agent-owned state
* that is equally invalidated by a page replacement: the delivery-checkpoint
@@ -8598,9 +8607,37 @@ export class Agent extends LoopDetector {
return String(provider?.config?.providerName || '').trim().toLowerCase() === 'webbrain-cloud';
}
+ _deliveryCollectionTask(tabId) {
+ const guard = this._planExecutionGuards.get(tabId);
+ const expected = this.progressExpectedItems.get(tabId);
+ if (!guard?.enabled || guard.requiresStateChange !== false || guard.requiresSubmission === true
+ || !Number.isInteger(expected?.count) || expected.count < 2 || expected.count > 1000) return null;
+ const session = this._currentProgressSession(tabId, { readOnly: true });
+ const collectionActions = new Set(['process_item', 'collect_profile', 'collect_email', 'visit', 'open']);
+ if (!isProgressIntentActive(session)
+ || !session.allowedActions.every(action => collectionActions.has(action))) return null;
+ const taskKey = this._progressTaskKeyHash(tabId);
+ if (!taskKey || guard.taskDrifted === true || (guard.taskKey && guard.taskKey !== taskKey)) return null;
+ return { expected, taskKey };
+ }
+
+ _deliveryCheckpointCollectionReadProgress(tabId, name, args, result) {
+ if (name !== 'fetch_url' || !this._isSuccessfulExecutionEvidence(result)) return false;
+ const task = this._deliveryCollectionTask(tabId);
+ if (!task) return false;
+ let coverage = this.deliveryCollectionReads.get(tabId);
+ if (!coverage || coverage.taskKey !== task.taskKey) {
+ coverage = { taskKey: task.taskKey, sources: new Map() };
+ this.deliveryCollectionReads.set(tabId, coverage);
+ }
+ return recordCollectionReadProgress(coverage, args, result).madeProgress;
+ }
+
_checkDeliveryObservationStreak(tabId, name, args = {}, result = null, options = {}) {
const observation = this.constructor.DELIVERY_OBSERVATION_TOOLS.has(name)
&& !isNetworkMutation(name, args);
+ const collectionReadProgress = observation
+ && this._deliveryCheckpointCollectionReadProgress(tabId, name, args, result);
if (observation
&& options.discoveredActionableTargets === true
&& !this.deliveryActionableDiscoveryResets.has(tabId)) {
@@ -8612,6 +8649,12 @@ export class Agent extends LoopDetector {
this.deliveryObservationStreaks.delete(tabId);
return { kind: 'none' };
}
+ if (collectionReadProgress) {
+ // Reading new ranges of a finite collection's source is task progress,
+ // even before complete item records can be entered in the ledger.
+ this.deliveryObservationStreaks.delete(tabId);
+ return { kind: 'none' };
+ }
if (observation && options.requiredReadProgress === true) {
// A new page in the runtime-required complete-thread scope is bounded,
// deterministic progress, not aimless research drift. Let exact trusted
@@ -8645,14 +8688,18 @@ export class Agent extends LoopDetector {
return {
kind: 'deliver',
count,
- warning: `[DELIVERY REQUIRED: You have made ${count} consecutive read, scroll, or wait observations without verified consequential progress. Browser observation tools are now stopping. On the recovery turn, call done exactly once with outcome partial or failed and put the complete useful result, evidence, and blockers already known in its summary. Do not request another observation or claim unverified success.]`,
+ warning: `[DELIVERY REQUIRED: You have made ${count} consecutive read, scroll, or wait observations without verified task progress. Browser observation tools are now stopping. On the recovery turn, call done exactly once with outcome partial or failed and put the complete useful result, evidence, and blockers already known in its summary. Do not request another observation or claim unverified success.]`,
};
}
+ const collection = this._deliveryCollectionTask(tabId);
+ const guidance = collection
+ ? `The task requires all ${collection.expected.count} items. Continue through new source ranges or item records needed to complete that scope, and record complete items with progress_update. Do not reread covered ranges or stop just because the requested collection is large. If no new evidence can be obtained or a blocker prevents completion, deliver the useful partial result.`
+ : 'Do not keep observing merely to make the answer exhaustive. If the current evidence satisfies the request, call done now. For list or research tasks, deliver useful partial results rather than risk shipping nothing. Continue only when you can name a specific missing fact or control and the next tool will obtain it.';
return {
kind: 'nudge',
count,
- warning: `[DELIVERY CHECKPOINT: You have made ${count} consecutive read, scroll, or wait observations without verified consequential progress. Do not keep observing merely to make the answer exhaustive. If the current evidence satisfies the request, call done now. For list or research tasks, deliver useful partial results rather than risk shipping nothing. Continue only when you can name a specific missing fact or control and the next tool will obtain it.]`,
+ warning: `[DELIVERY CHECKPOINT: You have made ${count} consecutive read, scroll, or wait observations without verified task progress. ${guidance}]`,
};
}
diff --git a/src/chrome/src/agent/collection-read-progress.js b/src/chrome/src/agent/collection-read-progress.js
new file mode 100644
index 000000000..56c4cb983
--- /dev/null
+++ b/src/chrome/src/agent/collection-read-progress.js
@@ -0,0 +1,84 @@
+// Only already-seen, finite sources can earn read progress. Keep registration
+// bounded so cycling through pairs of fresh URLs cannot erase the cutoff.
+const MAX_SOURCES = 8;
+const MIN_NEW_CHARS = 1000;
+
+function sourceUrl(value) {
+ try {
+ const url = new URL(value);
+ if (!['http:', 'https:'].includes(url.protocol)) return '';
+ url.hash = '';
+ return url.href;
+ } catch {
+ return '';
+ }
+}
+
+function deliveredWindow(args, result) {
+ if (String(args.method || 'GET').toUpperCase() !== 'GET'
+ || args.find || args.body || args.replayRequestId
+ || Object.keys(args.headers || {}).some(key => key.toLowerCase() === 'range')
+ || result?.success !== true || result.error || result.noProgress
+ || result.blocked || result.denied || result.skipped || result.cancelled
+ || result.outcomeUnknown || result.inconclusive || result.verified === false
+ || !(result.status >= 200 && result.status < 300) || result.status === 206
+ || result.contentRange) return null;
+ const field = typeof result.json === 'string' ? 'json' : 'text';
+ const body = result[field];
+ const { offset, originalLength, maxChars, nextOffset, hasMore } = result;
+ const requestedOffset = args.offset === undefined ? 0 : args.offset;
+ const url = sourceUrl(result.url);
+ if (!url || url !== sourceUrl(args.url)
+ || typeof body !== 'string' || !body.trim()
+ || !Number.isSafeInteger(originalLength) || originalLength <= 0
+ || !Number.isSafeInteger(offset) || offset < 0
+ || !Number.isSafeInteger(requestedOffset) || requestedOffset < 0
+ || offset !== Math.min(requestedOffset, originalLength)
+ || maxChars !== body.length || offset + body.length > originalLength) return null;
+ const end = offset + body.length;
+ if (hasMore !== (end < originalLength)
+ || nextOffset !== (hasMore ? end : null)) return null;
+ return { url, field, start: offset, end, originalLength };
+}
+
+export function recordCollectionReadProgress(state, args = {}, result = null) {
+ const current = state || { sources: new Map() };
+ const window = deliveredWindow(args, result);
+ if (!window) return { state: current, madeProgress: false };
+ const { url, field, start, end, originalLength } = window;
+ let source = current.sources.get(url);
+ if (!source) {
+ // A first read is discovery, not evidence of advancement. Full one-shot
+ // responses have no remaining ranges to track.
+ if (originalLength === end - start || current.sources.size >= MAX_SOURCES) {
+ return { state: current, madeProgress: false };
+ }
+ source = { field, originalLength, ranges: [[start, end]], retired: false };
+ current.sources.set(url, source);
+ return { state: current, madeProgress: false };
+ }
+ if (source.field !== field || source.originalLength !== originalLength) {
+ // Growing/changing representations cannot continually establish a new
+ // baseline. A new task/run can legitimately start coverage again.
+ source.retired = true;
+ }
+ if (source.retired) return { state: current, madeProgress: false };
+
+ let newChars = end - start;
+ for (const [coveredStart, coveredEnd] of source.ranges) {
+ newChars -= Math.max(0, Math.min(end, coveredEnd) - Math.max(start, coveredStart));
+ }
+ const merged = [];
+ for (const range of [...source.ranges, [start, end]].sort((a, b) => a[0] - b[0])) {
+ const last = merged.at(-1);
+ if (last && range[0] <= last[1]) last[1] = Math.max(last[1], range[1]);
+ else merged.push([...range]);
+ }
+ source.ranges = merged;
+ return {
+ state: current,
+ // Tiny shifts across a mostly repeated window are still observation
+ // drift. Short final/serialization-constrained pages can advance in full.
+ madeProgress: newChars >= Math.min(MIN_NEW_CHARS, end - start),
+ };
+}
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index ab4aaf45b..a6a8800f9 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -18,6 +18,7 @@ import { handleDoneJson } from './cloud-output.js';
import { applyReadPageWindow, fitReadPageWindowResult, isReadPageWindowResult } from './read-page-window.js';
import { STANDARD_TOOL_RESULT_CHARS, createReadCompletenessState, isCommunicationThreadContext, normalizeReadScope, readCompletenessBlock, readCompletenessLimitation, readCompletenessMadeProgress, readWindowLimits, recordReadCompleteness, requirePlannerReadCompleteness, requiresCompleteThreadRead } from './read-completeness.js';
import { LoopDetector } from './loop-detector.js';
+import { recordCollectionReadProgress } from './collection-read-progress.js';
import { parseToolCallsFromText } from './tool-call-parser.js';
import { IMAGE_BUDGET, estimateImageTokens, fitImageDimensions } from './image-budget.js';
import { BROWSER_MUTATION_TOOLS, STATE_CHANGE_TOOLS as SHARED_STATE_CHANGE_TOOLS } from './mutation-tools.js';
@@ -913,6 +914,7 @@ export class Agent extends LoopDetector {
// useful result before exhausting the run.
this.deliveryObservationStreaks = new Map();
this.deliveryActionableDiscoveryResets = new Set();
+ this.deliveryCollectionReads = new Map(); // tabId -> task-bound finite source coverage
// Local screenshot redaction (issue #312). When true, screenshots sent
// to a Vision endpoint are pixelated over DOM-detected PII regions
// (form fields + email/phone text) BEFORE leaving the extension. Off by
@@ -7700,6 +7702,13 @@ export class Agent extends LoopDetector {
return { method, requestShape, failed };
}
+ // Source coverage survives navigation and page-level loop resets. Only a
+ // run boundary may forget it and register the same source ranges again.
+ _clearRunLoopState(tabId) {
+ super._clearRunLoopState(tabId);
+ this.deliveryCollectionReads.delete(tabId);
+ }
+
/**
* Extends the detector's own page-scoped cleanup with the Agent-owned state
* that is equally invalidated by a page replacement: the delivery-checkpoint
@@ -8431,9 +8440,37 @@ export class Agent extends LoopDetector {
return String(provider?.config?.providerName || '').trim().toLowerCase() === 'webbrain-cloud';
}
+ _deliveryCollectionTask(tabId) {
+ const guard = this._planExecutionGuards.get(tabId);
+ const expected = this.progressExpectedItems.get(tabId);
+ if (!guard?.enabled || guard.requiresStateChange !== false || guard.requiresSubmission === true
+ || !Number.isInteger(expected?.count) || expected.count < 2 || expected.count > 1000) return null;
+ const session = this._currentProgressSession(tabId, { readOnly: true });
+ const collectionActions = new Set(['process_item', 'collect_profile', 'collect_email', 'visit', 'open']);
+ if (!isProgressIntentActive(session)
+ || !session.allowedActions.every(action => collectionActions.has(action))) return null;
+ const taskKey = this._progressTaskKeyHash(tabId);
+ if (!taskKey || guard.taskDrifted === true || (guard.taskKey && guard.taskKey !== taskKey)) return null;
+ return { expected, taskKey };
+ }
+
+ _deliveryCheckpointCollectionReadProgress(tabId, name, args, result) {
+ if (name !== 'fetch_url' || !this._isSuccessfulExecutionEvidence(result)) return false;
+ const task = this._deliveryCollectionTask(tabId);
+ if (!task) return false;
+ let coverage = this.deliveryCollectionReads.get(tabId);
+ if (!coverage || coverage.taskKey !== task.taskKey) {
+ coverage = { taskKey: task.taskKey, sources: new Map() };
+ this.deliveryCollectionReads.set(tabId, coverage);
+ }
+ return recordCollectionReadProgress(coverage, args, result).madeProgress;
+ }
+
_checkDeliveryObservationStreak(tabId, name, args = {}, result = null, options = {}) {
const observation = this.constructor.DELIVERY_OBSERVATION_TOOLS.has(name)
&& !isNetworkMutation(name, args);
+ const collectionReadProgress = observation
+ && this._deliveryCheckpointCollectionReadProgress(tabId, name, args, result);
if (observation
&& options.discoveredActionableTargets === true
&& !this.deliveryActionableDiscoveryResets.has(tabId)) {
@@ -8445,6 +8482,12 @@ export class Agent extends LoopDetector {
this.deliveryObservationStreaks.delete(tabId);
return { kind: 'none' };
}
+ if (collectionReadProgress) {
+ // Reading new ranges of a finite collection's source is task progress,
+ // even before complete item records can be entered in the ledger.
+ this.deliveryObservationStreaks.delete(tabId);
+ return { kind: 'none' };
+ }
if (observation && options.requiredReadProgress === true) {
// A new page in the runtime-required complete-thread scope is bounded,
// deterministic progress, not aimless research drift. Let exact trusted
@@ -8478,14 +8521,18 @@ export class Agent extends LoopDetector {
return {
kind: 'deliver',
count,
- warning: `[DELIVERY REQUIRED: You have made ${count} consecutive read, scroll, or wait observations without verified consequential progress. Browser observation tools are now stopping. On the recovery turn, call done exactly once with outcome partial or failed and put the complete useful result, evidence, and blockers already known in its summary. Do not request another observation or claim unverified success.]`,
+ warning: `[DELIVERY REQUIRED: You have made ${count} consecutive read, scroll, or wait observations without verified task progress. Browser observation tools are now stopping. On the recovery turn, call done exactly once with outcome partial or failed and put the complete useful result, evidence, and blockers already known in its summary. Do not request another observation or claim unverified success.]`,
};
}
+ const collection = this._deliveryCollectionTask(tabId);
+ const guidance = collection
+ ? `The task requires all ${collection.expected.count} items. Continue through new source ranges or item records needed to complete that scope, and record complete items with progress_update. Do not reread covered ranges or stop just because the requested collection is large. If no new evidence can be obtained or a blocker prevents completion, deliver the useful partial result.`
+ : 'Do not keep observing merely to make the answer exhaustive. If the current evidence satisfies the request, call done now. For list or research tasks, deliver useful partial results rather than risk shipping nothing. Continue only when you can name a specific missing fact or control and the next tool will obtain it.';
return {
kind: 'nudge',
count,
- warning: `[DELIVERY CHECKPOINT: You have made ${count} consecutive read, scroll, or wait observations without verified consequential progress. Do not keep observing merely to make the answer exhaustive. If the current evidence satisfies the request, call done now. For list or research tasks, deliver useful partial results rather than risk shipping nothing. Continue only when you can name a specific missing fact or control and the next tool will obtain it.]`,
+ warning: `[DELIVERY CHECKPOINT: You have made ${count} consecutive read, scroll, or wait observations without verified task progress. ${guidance}]`,
};
}
diff --git a/src/firefox/src/agent/collection-read-progress.js b/src/firefox/src/agent/collection-read-progress.js
new file mode 100644
index 000000000..56c4cb983
--- /dev/null
+++ b/src/firefox/src/agent/collection-read-progress.js
@@ -0,0 +1,84 @@
+// Only already-seen, finite sources can earn read progress. Keep registration
+// bounded so cycling through pairs of fresh URLs cannot erase the cutoff.
+const MAX_SOURCES = 8;
+const MIN_NEW_CHARS = 1000;
+
+function sourceUrl(value) {
+ try {
+ const url = new URL(value);
+ if (!['http:', 'https:'].includes(url.protocol)) return '';
+ url.hash = '';
+ return url.href;
+ } catch {
+ return '';
+ }
+}
+
+function deliveredWindow(args, result) {
+ if (String(args.method || 'GET').toUpperCase() !== 'GET'
+ || args.find || args.body || args.replayRequestId
+ || Object.keys(args.headers || {}).some(key => key.toLowerCase() === 'range')
+ || result?.success !== true || result.error || result.noProgress
+ || result.blocked || result.denied || result.skipped || result.cancelled
+ || result.outcomeUnknown || result.inconclusive || result.verified === false
+ || !(result.status >= 200 && result.status < 300) || result.status === 206
+ || result.contentRange) return null;
+ const field = typeof result.json === 'string' ? 'json' : 'text';
+ const body = result[field];
+ const { offset, originalLength, maxChars, nextOffset, hasMore } = result;
+ const requestedOffset = args.offset === undefined ? 0 : args.offset;
+ const url = sourceUrl(result.url);
+ if (!url || url !== sourceUrl(args.url)
+ || typeof body !== 'string' || !body.trim()
+ || !Number.isSafeInteger(originalLength) || originalLength <= 0
+ || !Number.isSafeInteger(offset) || offset < 0
+ || !Number.isSafeInteger(requestedOffset) || requestedOffset < 0
+ || offset !== Math.min(requestedOffset, originalLength)
+ || maxChars !== body.length || offset + body.length > originalLength) return null;
+ const end = offset + body.length;
+ if (hasMore !== (end < originalLength)
+ || nextOffset !== (hasMore ? end : null)) return null;
+ return { url, field, start: offset, end, originalLength };
+}
+
+export function recordCollectionReadProgress(state, args = {}, result = null) {
+ const current = state || { sources: new Map() };
+ const window = deliveredWindow(args, result);
+ if (!window) return { state: current, madeProgress: false };
+ const { url, field, start, end, originalLength } = window;
+ let source = current.sources.get(url);
+ if (!source) {
+ // A first read is discovery, not evidence of advancement. Full one-shot
+ // responses have no remaining ranges to track.
+ if (originalLength === end - start || current.sources.size >= MAX_SOURCES) {
+ return { state: current, madeProgress: false };
+ }
+ source = { field, originalLength, ranges: [[start, end]], retired: false };
+ current.sources.set(url, source);
+ return { state: current, madeProgress: false };
+ }
+ if (source.field !== field || source.originalLength !== originalLength) {
+ // Growing/changing representations cannot continually establish a new
+ // baseline. A new task/run can legitimately start coverage again.
+ source.retired = true;
+ }
+ if (source.retired) return { state: current, madeProgress: false };
+
+ let newChars = end - start;
+ for (const [coveredStart, coveredEnd] of source.ranges) {
+ newChars -= Math.max(0, Math.min(end, coveredEnd) - Math.max(start, coveredStart));
+ }
+ const merged = [];
+ for (const range of [...source.ranges, [start, end]].sort((a, b) => a[0] - b[0])) {
+ const last = merged.at(-1);
+ if (last && range[0] <= last[1]) last[1] = Math.max(last[1], range[1]);
+ else merged.push([...range]);
+ }
+ source.ranges = merged;
+ return {
+ state: current,
+ // Tiny shifts across a mostly repeated window are still observation
+ // drift. Short final/serialization-constrained pages can advance in full.
+ madeProgress: newChars >= Math.min(MIN_NEW_CHARS, end - start),
+ };
+}
diff --git a/test/collection-read-progress.mjs b/test/collection-read-progress.mjs
new file mode 100644
index 000000000..92fe65cdc
--- /dev/null
+++ b/test/collection-read-progress.mjs
@@ -0,0 +1,298 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+const PAGE_URL = 'https://example.com/repositories';
+const DATA_URL = 'https://example.com/data.json';
+const TASK = 'Return a JSON list of all 174 repositories from this category.';
+const EXPECTED = { count: 174, item_type: 'repository', ordered: false, required_fields: ['name'] };
+const area = { get: async () => ({}), set: async () => {}, remove: async () => {} };
+const api = {
+ storage: { local: area, session: area },
+ runtime: { getURL: value => `extension://test/${value}`, sendMessage: async () => ({}) },
+ tabs: { get: async id => ({ id, url: PAGE_URL, title: 'Repositories' }), sendMessage: async () => ({ ready: true }) },
+ webNavigation: { getAllFrames: async () => [{ frameId: 0, parentFrameId: -1, documentId: 'collection-document', url: PAGE_URL }] },
+ scripting: { executeScript: async () => [{ result: null }] },
+};
+globalThis.chrome = api;
+globalThis.browser = api;
+let nextTab = 5600;
+
+function fetchWindow(offset = 0, length = 7000, originalLength = 200000, url = DATA_URL) {
+ const end = offset + length;
+ return {
+ success: true, status: 200, contentType: 'application/json', url,
+ json: 'x'.repeat(length), offset, maxChars: length, originalLength,
+ nextOffset: end < originalLength ? end : null, hasMore: end < originalLength,
+ truncated: end < originalLength,
+ };
+}
+
+const fetchArgs = (offset = 0, url = DATA_URL, maxChars = 7000) => ({ url, offset, maxChars });
+
+function bindCollection(agent, tab, { task = TASK, count = 174, mode = 'active', action = 'process_item', guard = {} } = {}) {
+ agent.conversations.set(tab, [{ role: 'system', content: 'System' }, { role: 'user', content: task }]);
+ agent.progressExpectedItems.set(tab, { ...EXPECTED, count });
+ const session = agent._setProgressSession(tab, { mode, allowedActions: [action], forbiddenActions: [], confidence: 1 }, {
+ taskText: task, pageScope: PAGE_URL, source: 'planner',
+ });
+ assert.ok(session?.sessionId);
+ agent._planExecutionGuards.set(tab, {
+ enabled: true, requestKind: 'execute', requiresStateChange: false, requiresSubmission: false,
+ taskDrifted: false, taskKey: agent._progressTaskKeyHash(tab), ...guard,
+ });
+ return session;
+}
+
+const checkRead = (agent, tab, args, result, name = 'fetch_url') => agent._checkDeliveryObservationStreak(
+ tab, name, args, result, { enforceTerminal: true },
+);
+
+function makeIntegrationAgent(Agent, next) {
+ const provider = {
+ name: 'collection read regression', model: 'test', promptTier: 'full', contextWindow: 128000,
+ supportsTools: true, supportsVision: false, chat: next,
+ async *chatStream(messages) {
+ const response = await next(messages);
+ if (response.content) yield { type: 'text', content: response.content };
+ if (response.toolCalls) yield { type: 'tool_call', content: response.toolCalls.map((call, index) => ({ ...call, index })) };
+ yield { type: 'done' };
+ },
+ };
+ const agent = new Agent({ getActive: () => provider, getProvider: () => provider, getVisionProvider: async () => null });
+ for (const name of ['_hydrate', '_persistSubmittedTurn', '_endTraceRun', '_manageContext', '_maybeEmitAskModeHandoff',
+ '_maybeReinjectAdapter']) agent[name] = async () => {};
+ agent._persist = () => {};
+ agent._persistNow = async () => ({ ok: true });
+ agent._startTraceRun = async () => null;
+ agent._beginReadCompleteness = async () => null;
+ agent._checkCostAllowance = async () => null;
+ agent._recordCostUsage = async () => null;
+ agent._currentUrl = async () => PAGE_URL;
+ agent._getTabUrlTitle = async () => ({ tabUrl: PAGE_URL, tabTitle: 'Repositories' });
+ agent._enrichUserMessageWithCurrentPage = async (_tab, _messages, content) => ({ role: 'user', content });
+ agent._plannerMode = () => 'off';
+ agent._runPlannerIntentGate = async () => ({
+ proceed: true, requestKind: 'execute', requiresStateChange: false, requiresSubmission: false,
+ expectedItems: EXPECTED, progressLedgerPolicy: 'enabled', progressAction: 'process_item',
+ });
+ // Classifier inference is unrelated to the observation cutoff. Keep real
+ // session/task binding while supplying the planner's known collection intent.
+ agent._ensureProgressSessionForCurrentTask = async (tab, opts = {}) => {
+ agent.progressExpectedItems.set(tab, { ...EXPECTED });
+ const session = agent._setProgressSession(tab, {
+ mode: 'active', allowedActions: ['process_item'], forbiddenActions: [], confidence: 1,
+ }, { taskText: opts.taskText || TASK, pageScope: PAGE_URL, source: 'planner' });
+ agent._seedExpectedProgressItems(tab, session, EXPECTED);
+ return session;
+ };
+ agent._skipPermissionGate = true;
+ agent._ensureGateSetting = async () => true;
+ for (const name of ['_chromeProtectedPageFailure', '_captchaMutationPreflight', '_workflowPreSubmitDispatchBlock',
+ '_messageRecipientGuardBlock', '_detectLikelySubmitAction', '_socialPublicationPreSubmitBlock']) agent[name] = async () => null;
+ agent._adoptLiveSocialPublishWorkflow = async () => false;
+ agent._isFormValidationCandidate = () => false;
+ agent._preflightRichTextToolbarTarget = async () => ({ block: null });
+ agent._auditRichTextToolbarTarget = async () => {};
+ agent._shouldAutoScreenshot = () => false;
+ agent._pageFeedbackIdleMs = 0;
+ agent._completionDoneBlock = () => null;
+ agent.maxSteps = Infinity;
+ return agent;
+}
+
+const call = (id, name, args) => ({ toolCalls: [{ id, function: { name, arguments: JSON.stringify(args) } }] });
+
+for (const build of ['chrome', 'firefox']) {
+ const { Agent } = await import(`../src/${build}/src/agent/agent.js`);
+ const { recordCollectionReadProgress } = await import(`../src/${build}/src/agent/collection-read-progress.js`);
+
+ test(`${build}: collection range coverage accepts jumps and earlier unseen intervals`, () => {
+ let state;
+ const record = (offset, length = 7000, total = 633870) => {
+ const recorded = recordCollectionReadProgress(state, fetchArgs(offset, DATA_URL, length), fetchWindow(offset, length, total));
+ state = recorded.state;
+ return recorded.madeProgress;
+ };
+ assert.equal(record(0, 4000), false, 'The first read only establishes a finite resource');
+ assert.equal(record(372040, 6951), true, 'Searching schema offsets may jump past earlier content');
+ assert.equal(record(378991, 4000), true, 'Actual delivered length determines the next interval');
+ assert.equal(record(4000, 7000), true, 'Returning to the names array advances previously unseen coverage');
+ assert.equal(record(372040, 7000), false, 'A changed maxChars cannot disguise covered positions');
+ assert.equal(record(6000, 7000), true, 'An overlapping range still contributes more than 1000 new characters');
+ assert.equal(record(12000, 1100), false, 'A tiny overlapping extension must not keep a run alive');
+ assert.equal(record(633370, 500), true, 'The final short window may add fewer than 1000 characters');
+ assert.equal(record(633370, 500), false, 'Completed tail coverage cannot reset twice');
+ });
+
+ test(`${build}: changing source length retires a resource instead of rebasing coverage`, () => {
+ let recorded = recordCollectionReadProgress(undefined, fetchArgs(), fetchWindow());
+ recorded = recordCollectionReadProgress(recorded.state, fetchArgs(7000), fetchWindow(7000, 7000, 200001));
+ assert.equal(recorded.madeProgress, false);
+ recorded = recordCollectionReadProgress(recorded.state, fetchArgs(14000), fetchWindow(14000));
+ assert.equal(recorded.madeProgress, false, 'Reverting to the old length must not restore retired coverage');
+ });
+
+ test(`${build}: same-length content changes cannot reopen already covered positions`, () => {
+ const initial = fetchWindow();
+ let recorded = recordCollectionReadProgress(undefined, fetchArgs(), initial);
+ recorded = recordCollectionReadProgress(recorded.state, fetchArgs(), { ...initial, json: 'y'.repeat(7000) });
+ assert.equal(recorded.madeProgress, false);
+ recorded = recordCollectionReadProgress(recorded.state, fetchArgs(7000), { ...fetchWindow(7000), json: 'y'.repeat(7000) });
+ assert.equal(recorded.madeProgress, true, 'Coverage advances by position within the finite resource');
+ });
+
+ test(`${build}: only eight established resources can contribute continuation progress`, () => {
+ let state;
+ for (let resource = 0; resource < 8; resource++) {
+ const url = `https://example.com/data-${resource}.json`;
+ const first = recordCollectionReadProgress(state, fetchArgs(0, url), fetchWindow(0, 7000, 200000, url));
+ assert.equal(first.madeProgress, false);
+ const continuation = recordCollectionReadProgress(first.state, fetchArgs(7000, url), fetchWindow(7000, 7000, 200000, url));
+ assert.equal(continuation.madeProgress, true);
+ state = continuation.state;
+ }
+ const extraUrl = 'https://example.com/data-over-limit.json';
+ const extra = recordCollectionReadProgress(state, fetchArgs(0, extraUrl), fetchWindow(0, 7000, 200000, extraUrl));
+ assert.equal(extra.madeProgress, false);
+ assert.equal(recordCollectionReadProgress(extra.state, fetchArgs(7000, extraUrl), fetchWindow(7000, 7000, 200000, extraUrl)).madeProgress, false);
+ });
+
+ for (const invalid of [
+ ['failed response', args => args, result => ({ ...result, success: false, status: 500 })],
+ ['find response', args => ({ ...args, find: 'name' }), result => ({ ...result, find: 'name' })],
+ ['POST', args => ({ ...args, method: 'POST' }), result => result],
+ ['HEAD', args => ({ ...args, method: 'HEAD' }), result => result],
+ ['byte range', args => ({ ...args, headers: { Range: 'bytes=7000-13999' } }), result => ({ ...result, contentRange: 'bytes 7000-13999/200000' })],
+ ['missing source length', args => args, result => ({ ...result, originalLength: undefined })],
+ ['incorrect delivered length', args => args, result => ({ ...result, maxChars: 7001 })],
+ ['incorrect continuation', args => args, result => ({ ...result, nextOffset: 15000 })],
+ ['out of range', args => args, result => ({ ...result, originalLength: 1000 })],
+ ['empty window', args => args, result => ({ ...result, json: '', maxChars: 0, nextOffset: 7000 })],
+ ]) test(`${build}: ${invalid[0]} cannot claim collection read progress`, () => {
+ const first = recordCollectionReadProgress(undefined, fetchArgs(), fetchWindow());
+ assert.equal(recordCollectionReadProgress(first.state, invalid[1](fetchArgs(7000)), invalid[2](fetchWindow(7000))).madeProgress, false);
+ });
+
+ test(`${build}: fresh finite collection reads pass the real delivery guard beyond eight`, () => {
+ const tab = nextTab++, agent = new Agent({});
+ bindCollection(agent, tab);
+ for (let index = 0; index < 15; index++) {
+ assert.equal(checkRead(agent, tab, fetchArgs(index * 7000), fetchWindow(index * 7000)).kind, 'none');
+ }
+ assert.equal(agent.deliveryObservationStreaks.has(tab), false);
+ assert.equal(agent._expectedItemsDoneBlock(tab)?.blocked, true, 'Read coverage must not falsely complete repository ledger rows');
+ });
+
+ test(`${build}: repeated covered windows still force terminal delivery after eight`, () => {
+ const tab = nextTab++, agent = new Agent({});
+ bindCollection(agent, tab);
+ checkRead(agent, tab, fetchArgs(), fetchWindow());
+ checkRead(agent, tab, fetchArgs(7000), fetchWindow(7000));
+ let result;
+ for (let attempt = 1; attempt <= 8; attempt++) {
+ result = checkRead(agent, tab, fetchArgs(7000), fetchWindow(7000));
+ assert.equal(result.kind, attempt === 4 ? 'nudge' : attempt === 8 ? 'deliver' : 'none');
+ }
+ assert.equal(result.count, 8);
+ });
+
+ test(`${build}: arbitrary fresh URLs do not erase the observation streak`, () => {
+ const tab = nextTab++, agent = new Agent({});
+ bindCollection(agent, tab);
+ let result;
+ for (let attempt = 0; attempt < 8; attempt++) {
+ const url = `https://example.com/arbitrary-${attempt}.json`;
+ result = checkRead(agent, tab, fetchArgs(0, url), fetchWindow(0, 7000, 200000, url));
+ }
+ assert.equal(result.kind, 'deliver');
+ assert.equal(result.count, 8);
+ });
+
+ for (const name of ['fetch_url', 'research_url']) test(`${build}: ${name} search, failure and mutation calls do not clear a read debt`, () => {
+ const tab = nextTab++, agent = new Agent({});
+ bindCollection(agent, tab);
+ checkRead(agent, tab, fetchArgs(), fetchWindow());
+ for (const [args, result] of [
+ [{ ...fetchArgs(7000), find: 'name' }, { ...fetchWindow(7000), find: 'name' }],
+ [fetchArgs(7000), { ...fetchWindow(7000), success: false }],
+ [{ ...fetchArgs(7000), method: 'POST' }, fetchWindow(7000)],
+ [{ ...fetchArgs(7000), method: 'HEAD' }, fetchWindow(7000)],
+ ]) {
+ assert.equal(agent._deliveryCheckpointCollectionReadProgress(tab, name, args, result), false);
+ }
+ assert.equal(agent.deliveryObservationStreaks.get(tab), 1);
+ });
+
+ for (const scenario of [
+ ['no expected items', (agent, tab) => agent.progressExpectedItems.delete(tab)],
+ ['single expected item', (agent, tab) => agent.progressExpectedItems.set(tab, { ...EXPECTED, count: 1 })],
+ ['inactive session', (agent, tab) => { agent.progressSessions.get(tab).mode = 'inactive'; }],
+ ['action session', (agent, tab) => { agent.progressSessions.get(tab).allowedActions = ['follow']; }],
+ ['mixed action session', (agent, tab) => { agent.progressSessions.get(tab).allowedActions = ['process_item', 'follow']; }],
+ ['mutation task', (agent, tab) => { agent._planExecutionGuards.get(tab).requiresStateChange = true; }],
+ ['submission task', (agent, tab) => { agent._planExecutionGuards.get(tab).requiresSubmission = true; }],
+ ['disabled guard', (agent, tab) => { agent._planExecutionGuards.get(tab).enabled = false; }],
+ ['stale session', (agent, tab) => { agent.progressSessions.get(tab).taskText = 'A different task'; }],
+ ['drifted task', (agent, tab) => { agent._planExecutionGuards.get(tab).taskDrifted = true; }],
+ ['replaced task', (agent, tab) => { agent.conversations.get(tab).push({ role: 'user', content: 'Read a different website' }); }],
+ ]) test(`${build}: ${scenario[0]} retains the ordinary eight-observation cutoff`, () => {
+ const tab = nextTab++, agent = new Agent({});
+ bindCollection(agent, tab);
+ scenario[1](agent, tab);
+ let result;
+ for (let index = 0; index < 8; index++) result = checkRead(agent, tab, fetchArgs(index * 7000), fetchWindow(index * 7000));
+ assert.equal(result.kind, 'deliver');
+ assert.equal(result.count, 8);
+ });
+
+ test(`${build}: task-bound coverage survives page resets and clears at a run boundary`, () => {
+ const tab = nextTab++, agent = new Agent({});
+ bindCollection(agent, tab);
+ assert.equal(agent._deliveryCheckpointCollectionReadProgress(tab, 'fetch_url', fetchArgs(), fetchWindow()), false);
+ assert.equal(agent._deliveryCheckpointCollectionReadProgress(tab, 'fetch_url', fetchArgs(7000), fetchWindow(7000)), true);
+ agent._clearPageLoopState(tab);
+ assert.equal(agent._deliveryCheckpointCollectionReadProgress(tab, 'fetch_url', fetchArgs(7000), fetchWindow(7000)), false,
+ 'Navigating or refreshing must not reopen covered positions');
+ assert.equal(agent._deliveryCheckpointCollectionReadProgress(tab, 'fetch_url', fetchArgs(14000), fetchWindow(14000)), true);
+ agent._clearRunLoopState(tab);
+ assert.equal(agent._deliveryCheckpointCollectionReadProgress(tab, 'fetch_url', fetchArgs(14000), fetchWindow(14000)), false,
+ 'A new run establishes a fresh baseline');
+ assert.equal(agent._deliveryCheckpointCollectionReadProgress(tab, 'fetch_url', fetchArgs(21000), fetchWindow(21000)), true);
+ });
+
+ for (const streaming of [false, true]) test(`${build}: ${streaming ? 'stream' : 'chat'} delivers a finite collection after fifteen fresh reads`, async () => {
+ const tab = nextTab++, updates = [], dispatched = [];
+ const names = Array.from({ length: 174 }, (_, index) => ({ name: `owner/repository-${index + 1}` }));
+ const answer = JSON.stringify(names);
+ let requests = 0;
+ const next = async () => {
+ requests++;
+ assert.ok(requests <= 17, 'Fresh collection windows should finish without terminal recovery');
+ if (requests <= 15) return call(`window-${requests}`, 'fetch_url', fetchArgs((requests - 1) * 7000));
+ if (requests === 16) return call('record-complete-items', 'progress_update', { items: names.map((item, index) => ({
+ id: `expected:${index + 1}`, label: item.name, status: 'processed',
+ fields: { name: item.name },
+ })) });
+ return call('finished', 'done', { summary: answer, outcome: 'success' });
+ };
+ const agent = makeIntegrationAgent(Agent, next);
+ agent.executeTool = async (_tab, name, args) => {
+ if (name === 'get_accessibility_tree') return { success: true, pageContent: 'heading "Repositories" [ref_1]' };
+ if (name === 'done') return { done: true, success: true, summary: args.summary, outcome: args.outcome };
+ if (name === 'progress_update') return agent._progressUpdate(_tab, args);
+ assert.equal(name, 'fetch_url');
+ dispatched.push(args.offset);
+ return fetchWindow(args.offset);
+ };
+ const update = (type, data) => updates.push({ type, data });
+ const options = { detachedRequestId: 'collection-run', askStreamingEnabled: false };
+ const result = streaming
+ ? await agent.processMessageStream(tab, TASK, update, 'act', options)
+ : await agent.processMessage(tab, TASK, update, 'act', [], options);
+ assert.equal(result.split('\n\nProgress ledger:')[0], answer, JSON.stringify(updates.filter(entry => entry.type === 'warning')));
+ assert.match(result, /174 row\(s\), 174 processed/);
+ assert.equal(requests, 17);
+ assert.equal(dispatched.length, 15);
+ assert.equal(updates.some(entry => entry.type === 'warning' && /observation tools are now stopping/.test(entry.data.message)), false);
+ });
+}