Skip to content

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

Guard policy: an exact table answer stays valid JSON when accepted over advice

Barack Sokullu71717928d1d6
diff --git a/docs/guards.md b/docs/guards.md
index 051b63d39..512e823ae 100644
--- a/docs/guards.md
+++ b/docs/guards.md
@@ -25,7 +25,10 @@ the action is wrong (`onDecided`) and when it cannot tell (`onCannotDecide`):
that refusal is its note. Each guard gets its own: when two apply, the
second is checked once the first has advised. The next completion a guard
would refuse is accepted, and the final answer ends with one line,
- "WebBrain could not verify everything: …" (at most four items).
+ "WebBrain could not verify everything: …" (at most four items). An
+ exact table delivered from its `data_ref` stays the complete JSON its
+ contract promises: the line goes beside it, as a warning and as the
+ done result's `completionCaveat`.
- A completion accepted over a guard that knows the claim is wrong (the
completion judge's "not done", an unauthorized mutation, missing, failed
or unfinished progress rows, unread pages of a whole thread the user
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 69d57a579..721590de9 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -5352,8 +5352,21 @@ export class Agent extends LoopDetector {
// Adds the "WebBrain could not verify everything" line, if any, to the
// answer of an accepted completion. _guardRunState first drops a previous
// run's caveats.
+ // The line a completion accepted over a guard's advice ends with, or ''.
+ _completionCaveatLine(tabId) {
+ return (this._guardRunState(tabId) && this._guardCaveatLine(tabId)) || '';
+ }
+
+ // Whether a done summary is the exact table its data_ref delivered: the
+ // complete JSON the data_ref contract promises, to which nothing is added.
+ _isExactTablePayload(tabId, args, summary) {
+ if (typeof args?.data_ref !== 'string' || !args.data_ref || typeof summary !== 'string') return false;
+ const record = this.readCompletenessStates.get(tabId)?.exactTableExports?.get(args.data_ref);
+ return typeof record?.summary === 'string' && record.summary === summary;
+ }
+
_withCompletionCaveat(tabId, text) {
- const line = this._guardRunState(tabId) && this._guardCaveatLine(tabId);
+ const line = this._completionCaveatLine(tabId);
if (!line) return text;
const base = String(text ?? '').trimEnd();
return base ? `${base}\n\n${line}` : line;
@@ -16696,6 +16709,12 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
toolResult.summary = (toolResult.summary || partialAssistantText || '') + '\n\n' + notice;
}
}
+ // An exact table delivered from its data_ref stays the complete JSON
+ // its contract promises: a caveat travels beside it, on the done
+ // result and as a warning, never inside the payload.
+ const exactTablePayload = !scheduledResume && this._isExactTablePayload(tabId, fnArgs, toolResult.summary);
+ const payloadCaveat = exactTablePayload ? this._completionCaveatLine(tabId) : '';
+ if (payloadCaveat) toolResult.completionCaveat = payloadCaveat;
onUpdate('tool_result', { name: fnName, result: toolResult });
this._doneBlockCount.delete(tabId);
rawDoneSummary = toolResult.summary || rawDoneSummary;
@@ -16704,7 +16723,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
: this._appendProgressLedgerToFinal(tabId, repairedDoneSummary);
// A completion accepted over a guard's advice tells the user what was
// not verified. A scheduled resume is a pause, not a completion.
- const finalResponse = scheduledResume ? deliveredSummary : this._withCompletionCaveat(tabId, deliveredSummary);
+ const finalResponse = scheduledResume || exactTablePayload ? deliveredSummary : this._withCompletionCaveat(tabId, deliveredSummary);
if (repairedDoneSummary !== rawDoneSummary) {
// Streaming providers may already have rendered the malformed summary
// before the done call. Replace it so the visible bubble matches the
@@ -16713,6 +16732,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
} else if (finalResponse !== deliveredSummary) {
onUpdate('text', { content: finalResponse, replace: true });
}
+ if (payloadCaveat) onUpdate('warning', { message: payloadCaveat });
messages.push({
role: 'tool',
tool_call_id: tc.id,
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index 52876acf7..fe1021205 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -4904,8 +4904,21 @@ export class Agent extends LoopDetector {
// Adds the "WebBrain could not verify everything" line, if any, to the
// answer of an accepted completion. _guardRunState first drops a previous
// run's caveats.
+ // The line a completion accepted over a guard's advice ends with, or ''.
+ _completionCaveatLine(tabId) {
+ return (this._guardRunState(tabId) && this._guardCaveatLine(tabId)) || '';
+ }
+
+ // Whether a done summary is the exact table its data_ref delivered: the
+ // complete JSON the data_ref contract promises, to which nothing is added.
+ _isExactTablePayload(tabId, args, summary) {
+ if (typeof args?.data_ref !== 'string' || !args.data_ref || typeof summary !== 'string') return false;
+ const record = this.readCompletenessStates.get(tabId)?.exactTableExports?.get(args.data_ref);
+ return typeof record?.summary === 'string' && record.summary === summary;
+ }
+
_withCompletionCaveat(tabId, text) {
- const line = this._guardRunState(tabId) && this._guardCaveatLine(tabId);
+ const line = this._completionCaveatLine(tabId);
if (!line) return text;
const base = String(text ?? '').trimEnd();
return base ? `${base}\n\n${line}` : line;
@@ -14963,6 +14976,12 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
toolResult.summary = (toolResult.summary || partialAssistantText || '') + '\n\n' + notice;
}
}
+ // An exact table delivered from its data_ref stays the complete JSON
+ // its contract promises: a caveat travels beside it, on the done
+ // result and as a warning, never inside the payload.
+ const exactTablePayload = !scheduledResume && this._isExactTablePayload(tabId, fnArgs, toolResult.summary);
+ const payloadCaveat = exactTablePayload ? this._completionCaveatLine(tabId) : '';
+ if (payloadCaveat) toolResult.completionCaveat = payloadCaveat;
onUpdate('tool_result', { name: fnName, result: toolResult });
this._doneBlockCount.delete(tabId);
rawDoneSummary = toolResult.summary || rawDoneSummary;
@@ -14971,7 +14990,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
: this._appendProgressLedgerToFinal(tabId, repairedDoneSummary);
// A completion accepted over a guard's advice tells the user what was
// not verified. A scheduled resume is a pause, not a completion.
- const finalResponse = scheduledResume ? deliveredSummary : this._withCompletionCaveat(tabId, deliveredSummary);
+ const finalResponse = scheduledResume || exactTablePayload ? deliveredSummary : this._withCompletionCaveat(tabId, deliveredSummary);
if (repairedDoneSummary !== rawDoneSummary) {
// Streaming providers may already have rendered the malformed summary
// before the done call. Replace it so the visible bubble matches the
@@ -14980,6 +14999,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
} else if (finalResponse !== deliveredSummary) {
onUpdate('text', { content: finalResponse, replace: true });
}
+ if (payloadCaveat) onUpdate('warning', { message: payloadCaveat });
messages.push({
role: 'tool',
tool_call_id: tc.id,
diff --git a/test/guard-advisory-completion.mjs b/test/guard-advisory-completion.mjs
index f732ebd41..06939b44d 100644
--- a/test/guard-advisory-completion.mjs
+++ b/test/guard-advisory-completion.mjs
@@ -681,6 +681,31 @@ for (const build of ['chrome', 'firefox']) {
}
});
+ test(`${build}: an exact table delivered over advice stays valid JSON; its caveat travels beside it`, async () => {
+ const askSchemas = new Map(getToolsForMode('ask', { tier: 'full' }).map(tool => [tool.function.name, tool.function.parameters]));
+ const h = batchAgent(Agent, { mode: 'ask', realDone: true, schemas: askSchemas });
+ const owner = { runToken: 'owned-run', current: () => true };
+ const table = { rowCount: 2, rows: [{ id: 'A' }, { id: 'B' }] };
+ const record = { dataRef: 'table_owned', runToken: 'owned-run', owner, args: { columns: ['id'] }, summary: JSON.stringify(table) };
+ h.agent.readCompletenessStates.set(h.tab, { runToken: 'owned-run', exactTableExports: new Map([['table_owned', record]]) });
+ h.agent._exactTableOwner = () => owner;
+ const realExecute = h.agent.executeTool.bind(h.agent);
+ h.agent.executeTool = async (tab, name, args, ...rest) => (name === 'extract_data'
+ ? { success: false, error: 'The source table changed.' } : realExecute(tab, name, args, ...rest));
+ const done = ['done', { summary: 'Full inventory.', data_ref: 'table_owned' }];
+ assert.equal((await h.batch([done])).action, 'continue', `${build}: the stale snapshot is refused once`);
+ const updates = [];
+ const accepted = await h.batch([done], updates);
+ assert.equal(accepted.action, 'return', `${build}: the second completion is accepted`);
+ assert.deepEqual(JSON.parse(accepted.value), table, `${build}: the answer is the exact table, nothing appended`);
+ const line = `${CAVEAT}The table on the page may have changed after it was extracted.`;
+ const doneResult = updates.filter(update => update.type === 'tool_result' && update.data.name === 'done').at(-1)?.data.result;
+ assert.equal(doneResult?.completionCaveat, line, `${build}: the done result carries the caveat`);
+ assert.ok(updates.some(update => update.type === 'warning' && update.data.message === line), `${build}: the user sees it as a warning`);
+ assert.ok(!updates.some(update => update.type === 'text' && String(update.data.content).includes(CAVEAT)),
+ `${build}: no caveat in the answer text`);
+ });
+
// ── Arithmetic tasks ───────────────────────────────────────────────────
test(`${build}: an honest failure before any calculator attempt is refused once, then accepted`, async () => {
for (const strict of [false, true]) {