Skip to content

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

Publication prefetch: a background check never spends past the cost limit

Barack Sokullua05e684b374c
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 4b232a8fc..40c4a09d8 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -8688,21 +8688,84 @@ export class Agent extends LoopDetector {
return `Cloud cost allowance reached: ${scopeText} is ${this._formatUsd(spentUsd)} against the ${this._formatUsd(limitUsd)} limit. Stopping before further cloud/router model calls. Increase or reset the allowance in Settings.`;
}
- _checkCostAllowanceState(state, costState) {
+ // `pending`: which requests in flight to count at their most (see
+ // _holdCostAllowance): 'background' counts background checks, so a request
+ // that starts beside one cannot spend past the limit with it; 'all' also
+ // counts the run's own requests, for a background check that may start
+ // beside them; 'none' counts only what was spent.
+ _checkCostAllowanceState(state, costState, { pending = 'background' } = {}) {
+ const onlyBackground = pending !== 'all';
const sessionSpent = this._normalizeCostSpent(costState?.spentUsd);
- if (sessionSpent + COST_EPSILON >= state.sessionLimitUsd) {
+ const sessionPending = pending !== 'none' && costState ? this._pendingCostUsd(costState, onlyBackground) : 0;
+ if (sessionSpent + sessionPending + COST_EPSILON >= state.sessionLimitUsd) {
return this._costAllowanceMessage('session', sessionSpent, state.sessionLimitUsd);
}
- if (state.totalSpentUsd + COST_EPSILON >= state.totalLimitUsd) {
+ const totalPending = pending !== 'none' ? this._pendingCostUsd(null, onlyBackground) : 0;
+ if (state.totalSpentUsd + totalPending + COST_EPSILON >= state.totalLimitUsd) {
return this._costAllowanceMessage('total', state.totalSpentUsd, state.totalLimitUsd);
}
return null;
}
- async _checkCostAllowance(provider, costState) {
+ // Before a request. A background check (`hold.background`) counts every
+ // request in flight at its most and does not start when that could pass
+ // the limit. Any other request counts background checks in flight; when
+ // only they would put it over the limit, it waits for them to settle and
+ // counts what they actually cost, like a request made after them.
+ async _checkCostAllowance(provider, costState, { signal = null, hold = null } = {}) {
if (!this._isCostMeteredProvider(provider)) return null;
- const state = await this._getCostAllowanceState();
- return this._checkCostAllowanceState(state, costState);
+ for (;;) {
+ const state = await this._getCostAllowanceState();
+ if (hold?.background) return this._checkCostAllowanceState(state, costState, { pending: 'all' });
+ const message = this._checkCostAllowanceState(state, costState);
+ if (!message || !this._pendingCostUsd(null, true)
+ || this._checkCostAllowanceState(state, costState, { pending: 'none' })) return message;
+ await this._backgroundCostSettled(signal);
+ }
+ }
+
+ // Holds what a request in flight can cost at most (its prompt, tools and
+ // whole completion budget, priced like recorded usage) until it settles.
+ _holdCostAllowance(provider, messages, options, costState, { background = false } = {}) {
+ if (!this._isCostMeteredProvider(provider)) return null;
+ let toolChars = 0;
+ try { toolChars = JSON.stringify(options?.tools || []).length; } catch {}
+ const promptTokens = Math.max(1, Math.ceil(
+ (this._estimateContextChars(Array.isArray(messages) ? messages : []) + toolChars) / 4));
+ const completionTokens = Number.isFinite(options?.maxTokens) && options.maxTokens > 0 ? options.maxTokens : 4096;
+ const usd = this._estimateUsageCostUsd(provider, { prompt_tokens: promptTokens, completion_tokens: completionTokens });
+ if (!(usd > 0)) return null;
+ let settle = null;
+ const hold = { usd, costState, background, settled: new Promise(resolve => { settle = resolve; }) };
+ hold.release = () => {
+ if (this._costHolds?.delete(hold)) settle();
+ };
+ (this._costHolds ||= new Set()).add(hold);
+ return hold;
+ }
+
+ _pendingCostUsd(costState = null, onlyBackground = false) {
+ let usd = 0;
+ for (const hold of this._costHolds || []) {
+ if ((!costState || hold.costState === costState) && (!onlyBackground || hold.background)) usd += hold.usd;
+ }
+ return usd;
+ }
+
+ async _backgroundCostSettled(signal = null) {
+ const pending = [...(this._costHolds || [])].filter(hold => hold.background).map(hold => hold.settled);
+ if (!pending.length) return;
+ let onAbort = null;
+ const aborted = signal ? new Promise(resolve => {
+ if (signal.aborted) resolve();
+ else signal.addEventListener('abort', onAbort = () => resolve(), { once: true });
+ }) : null;
+ try {
+ await (aborted ? Promise.race([Promise.all(pending), aborted]) : Promise.all(pending));
+ } finally {
+ if (onAbort) signal.removeEventListener('abort', onAbort);
+ }
+ this._throwIfAborted(signal);
}
async _recordCostUsage(provider, usage, costState) {
@@ -8715,7 +8778,7 @@ export class Agent extends LoopDetector {
if (costState) costState.spentUsd = this._normalizeCostSpent(costState.spentUsd) + costUsd;
this.meteredProviderCostSpentUsd = nextTotal;
try { await chrome.storage.local.set({ [CLOUD_COST_SPENT_KEY]: nextTotal }); } catch {}
- return this._checkCostAllowanceState({ ...state, totalSpentUsd: nextTotal }, costState);
+ return this._checkCostAllowanceState({ ...state, totalSpentUsd: nextTotal }, costState, { pending: 'none' });
});
}
@@ -9330,9 +9393,12 @@ export class Agent extends LoopDetector {
messages = foldBrowserBatchMessages(messages, { repairPending: true });
const linked = this._linkAbortSignals(options?.signal, this._runAbortSignal(requestContext?.tabId));
options = { ...options, signal: linked.signal };
+ // Held at its most until it settles: see _checkCostAllowance.
+ const hold = this._holdCostAllowance(provider, messages, options, costState,
+ { background: requestContext?.background === true });
try {
this._throwIfAborted(options.signal);
- const before = await this._checkCostAllowance(provider, costState);
+ const before = await this._checkCostAllowance(provider, costState, { signal: options.signal, hold });
if (before) throw this._costAllowanceError(before);
this._throwIfAborted(options?.signal);
const result = await provider.chat(messages, requestContext
@@ -9346,6 +9412,7 @@ export class Agent extends LoopDetector {
if (after) result.costAllowanceMessage = after;
return result;
} finally {
+ hold?.release();
linked.dispose();
}
}
@@ -9446,9 +9513,11 @@ export class Agent extends LoopDetector {
messages = foldBrowserBatchMessages(messages, { repairPending: true });
const linked = this._linkAbortSignals(options?.signal, this._runAbortSignal(requestContext?.tabId));
options = { ...options, signal: linked.signal };
+ // Held at its most until it settles: see _checkCostAllowance.
+ const hold = this._holdCostAllowance(provider, messages, options, costState);
try {
this._throwIfAborted(options.signal);
- const before = await this._checkCostAllowance(provider, costState);
+ const before = await this._checkCostAllowance(provider, costState, { signal: options.signal, hold });
if (before) throw this._costAllowanceError(before);
const streamOptions = requestContext
@@ -9571,6 +9640,7 @@ export class Agent extends LoopDetector {
if (after) result.costAllowanceMessage = after;
return result;
} finally {
+ hold?.release();
linked.dispose();
}
}
@@ -24013,7 +24083,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
const response = await this._chatWithCostAllowance(provider, requestMessages,
background ? { ...options, signal: call.signal } : options,
background ? call.costState : (this.currentCostState.get(tabId) || null),
- { tabId, generationName: 'social_publication_contract' });
+ { tabId, generationName: 'social_publication_contract', ...(background ? { background: true } : {}) });
received = true;
await this._tracePlannerAttemptResponse(runId, 0, provider, response,
'social_publication_contract', attempt + 1, startedAt, options);
@@ -24435,7 +24505,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
const response = await this._chatWithCostAllowance(provider, requestMessages,
background ? { ...options, signal: background.signal } : options,
background ? background.costState : (this.currentCostState.get(tabId) || null),
- { tabId, generationName: 'social_publication_authorization' });
+ { tabId, generationName: 'social_publication_authorization', ...(background ? { background: true } : {}) });
received = true;
await this._tracePlannerAttemptResponse(runId, 0, provider, response,
'social_publication_authorization', attempt + 1, startedAt, options);
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index e42ebfc19..c2763f931 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -8403,21 +8403,84 @@ export class Agent extends LoopDetector {
return `Cloud cost allowance reached: ${scopeText} is ${this._formatUsd(spentUsd)} against the ${this._formatUsd(limitUsd)} limit. Stopping before further cloud/router model calls. Increase or reset the allowance in Settings.`;
}
- _checkCostAllowanceState(state, costState) {
+ // `pending`: which requests in flight to count at their most (see
+ // _holdCostAllowance): 'background' counts background checks, so a request
+ // that starts beside one cannot spend past the limit with it; 'all' also
+ // counts the run's own requests, for a background check that may start
+ // beside them; 'none' counts only what was spent.
+ _checkCostAllowanceState(state, costState, { pending = 'background' } = {}) {
+ const onlyBackground = pending !== 'all';
const sessionSpent = this._normalizeCostSpent(costState?.spentUsd);
- if (sessionSpent + COST_EPSILON >= state.sessionLimitUsd) {
+ const sessionPending = pending !== 'none' && costState ? this._pendingCostUsd(costState, onlyBackground) : 0;
+ if (sessionSpent + sessionPending + COST_EPSILON >= state.sessionLimitUsd) {
return this._costAllowanceMessage('session', sessionSpent, state.sessionLimitUsd);
}
- if (state.totalSpentUsd + COST_EPSILON >= state.totalLimitUsd) {
+ const totalPending = pending !== 'none' ? this._pendingCostUsd(null, onlyBackground) : 0;
+ if (state.totalSpentUsd + totalPending + COST_EPSILON >= state.totalLimitUsd) {
return this._costAllowanceMessage('total', state.totalSpentUsd, state.totalLimitUsd);
}
return null;
}
- async _checkCostAllowance(provider, costState) {
+ // Before a request. A background check (`hold.background`) counts every
+ // request in flight at its most and does not start when that could pass
+ // the limit. Any other request counts background checks in flight; when
+ // only they would put it over the limit, it waits for them to settle and
+ // counts what they actually cost, like a request made after them.
+ async _checkCostAllowance(provider, costState, { signal = null, hold = null } = {}) {
if (!this._isCostMeteredProvider(provider)) return null;
- const state = await this._getCostAllowanceState();
- return this._checkCostAllowanceState(state, costState);
+ for (;;) {
+ const state = await this._getCostAllowanceState();
+ if (hold?.background) return this._checkCostAllowanceState(state, costState, { pending: 'all' });
+ const message = this._checkCostAllowanceState(state, costState);
+ if (!message || !this._pendingCostUsd(null, true)
+ || this._checkCostAllowanceState(state, costState, { pending: 'none' })) return message;
+ await this._backgroundCostSettled(signal);
+ }
+ }
+
+ // Holds what a request in flight can cost at most (its prompt, tools and
+ // whole completion budget, priced like recorded usage) until it settles.
+ _holdCostAllowance(provider, messages, options, costState, { background = false } = {}) {
+ if (!this._isCostMeteredProvider(provider)) return null;
+ let toolChars = 0;
+ try { toolChars = JSON.stringify(options?.tools || []).length; } catch {}
+ const promptTokens = Math.max(1, Math.ceil(
+ (this._estimateContextChars(Array.isArray(messages) ? messages : []) + toolChars) / 4));
+ const completionTokens = Number.isFinite(options?.maxTokens) && options.maxTokens > 0 ? options.maxTokens : 4096;
+ const usd = this._estimateUsageCostUsd(provider, { prompt_tokens: promptTokens, completion_tokens: completionTokens });
+ if (!(usd > 0)) return null;
+ let settle = null;
+ const hold = { usd, costState, background, settled: new Promise(resolve => { settle = resolve; }) };
+ hold.release = () => {
+ if (this._costHolds?.delete(hold)) settle();
+ };
+ (this._costHolds ||= new Set()).add(hold);
+ return hold;
+ }
+
+ _pendingCostUsd(costState = null, onlyBackground = false) {
+ let usd = 0;
+ for (const hold of this._costHolds || []) {
+ if ((!costState || hold.costState === costState) && (!onlyBackground || hold.background)) usd += hold.usd;
+ }
+ return usd;
+ }
+
+ async _backgroundCostSettled(signal = null) {
+ const pending = [...(this._costHolds || [])].filter(hold => hold.background).map(hold => hold.settled);
+ if (!pending.length) return;
+ let onAbort = null;
+ const aborted = signal ? new Promise(resolve => {
+ if (signal.aborted) resolve();
+ else signal.addEventListener('abort', onAbort = () => resolve(), { once: true });
+ }) : null;
+ try {
+ await (aborted ? Promise.race([Promise.all(pending), aborted]) : Promise.all(pending));
+ } finally {
+ if (onAbort) signal.removeEventListener('abort', onAbort);
+ }
+ this._throwIfAborted(signal);
}
async _recordCostUsage(provider, usage, costState) {
@@ -8430,7 +8493,7 @@ export class Agent extends LoopDetector {
if (costState) costState.spentUsd = this._normalizeCostSpent(costState.spentUsd) + costUsd;
this.meteredProviderCostSpentUsd = nextTotal;
try { await browser.storage.local.set({ [CLOUD_COST_SPENT_KEY]: nextTotal }); } catch {}
- return this._checkCostAllowanceState({ ...state, totalSpentUsd: nextTotal }, costState);
+ return this._checkCostAllowanceState({ ...state, totalSpentUsd: nextTotal }, costState, { pending: 'none' });
});
}
@@ -9043,9 +9106,12 @@ export class Agent extends LoopDetector {
messages = foldBrowserBatchMessages(messages, { repairPending: true });
const linked = this._linkAbortSignals(options?.signal, this._runAbortSignal(requestContext?.tabId));
options = { ...options, signal: linked.signal };
+ // Held at its most until it settles: see _checkCostAllowance.
+ const hold = this._holdCostAllowance(provider, messages, options, costState,
+ { background: requestContext?.background === true });
try {
this._throwIfAborted(options.signal);
- const before = await this._checkCostAllowance(provider, costState);
+ const before = await this._checkCostAllowance(provider, costState, { signal: options.signal, hold });
if (before) throw this._costAllowanceError(before);
this._throwIfAborted(options?.signal);
const result = await provider.chat(messages, requestContext
@@ -9059,6 +9125,7 @@ export class Agent extends LoopDetector {
if (after) result.costAllowanceMessage = after;
return result;
} finally {
+ hold?.release();
linked.dispose();
}
}
@@ -9159,9 +9226,11 @@ export class Agent extends LoopDetector {
messages = foldBrowserBatchMessages(messages, { repairPending: true });
const linked = this._linkAbortSignals(options?.signal, this._runAbortSignal(requestContext?.tabId));
options = { ...options, signal: linked.signal };
+ // Held at its most until it settles: see _checkCostAllowance.
+ const hold = this._holdCostAllowance(provider, messages, options, costState);
try {
this._throwIfAborted(options.signal);
- const before = await this._checkCostAllowance(provider, costState);
+ const before = await this._checkCostAllowance(provider, costState, { signal: options.signal, hold });
if (before) throw this._costAllowanceError(before);
const streamOptions = requestContext
@@ -9284,6 +9353,7 @@ export class Agent extends LoopDetector {
if (after) result.costAllowanceMessage = after;
return result;
} finally {
+ hold?.release();
linked.dispose();
}
}
@@ -21196,7 +21266,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
const response = await this._chatWithCostAllowance(provider, requestMessages,
background ? { ...options, signal: call.signal } : options,
background ? call.costState : (this.currentCostState.get(tabId) || null),
- { tabId, generationName: 'social_publication_contract' });
+ { tabId, generationName: 'social_publication_contract', ...(background ? { background: true } : {}) });
received = true;
await this._tracePlannerAttemptResponse(runId, 0, provider, response,
'social_publication_contract', attempt + 1, startedAt, options);
@@ -21618,7 +21688,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
const response = await this._chatWithCostAllowance(provider, requestMessages,
background ? { ...options, signal: background.signal } : options,
background ? background.costState : (this.currentCostState.get(tabId) || null),
- { tabId, generationName: 'social_publication_authorization' });
+ { tabId, generationName: 'social_publication_authorization', ...(background ? { background: true } : {}) });
received = true;
await this._tracePlannerAttemptResponse(runId, 0, provider, response,
'social_publication_authorization', attempt + 1, startedAt, options);
diff --git a/test/publication-prefetch.mjs b/test/publication-prefetch.mjs
index 286b740d0..252266888 100644
--- a/test/publication-prefetch.mjs
+++ b/test/publication-prefetch.mjs
@@ -377,6 +377,51 @@ for (const browser of ['chrome', 'firefox']) {
assert.deepEqual(f.calls.map(call => call.name), ['social_publication_contract', 'social_publication_authorization']);
});
+ test(`${browser}: a background check counts every request in flight at its most, and a request beside it counts the check`, async () => {
+ const agent = new Agent({});
+ const tabId = 977;
+ const gates = [];
+ const provider = { name: 'metered', model: 'metered', config: {},
+ chat: async () => { const gate = deferred(); gates.push(gate); return gate.promise; } };
+ agent._isCostMeteredProvider = () => true;
+ agent._getCostAllowanceState = async () => ({ sessionLimitUsd: 1, totalLimitUsd: 100, totalSpentUsd: 0 });
+ agent._estimateUsageCostUsd = () => 0.3; // the most a request can cost
+ agent._extractUsageCostUsd = (_provider, usage) => usage?.cost_usd || 0; // what it cost
+ const costState = { spentUsd: 0.5 };
+ const ask = (content, context = {}) => agent._chatWithCostAllowance(provider, [{ role: 'user', content }], {}, costState,
+ { tabId, ...context });
+ // The run's own request is in flight: a background check counts it at its
+ // most, and $0.50 spent + $0.30 + its own $0.30 could pass the $1 limit.
+ const main = ask('next turn');
+ await until(() => gates.length === 1, 'the run\'s request started');
+ await assert.rejects(ask('audit', { background: true }), error => agent._isCostAllowanceError(error),
+ 'the background check does not start');
+ assert.equal(gates.length, 1, 'nothing was sent for the background check');
+ gates[0].release({ content: 'ok', usage: { cost_usd: 0.2 } });
+ await main;
+ assert.equal(costState.spentUsd, 0.7);
+ // A background check in flight ($0.40 + $0.30): a request beside it that
+ // would pass the limit only with the check's most waits for its actual
+ // cost, like a request made after it.
+ costState.spentUsd = 0.4;
+ const background = ask('audit', { background: true });
+ await until(() => gates.length === 2, 'the background check started');
+ costState.spentUsd = 0.8;
+ const next = ask('next turn');
+ await settle();
+ assert.equal(gates.length, 2, 'the next request waits for the check in flight');
+ gates[1].release({ content: 'ok', usage: { cost_usd: 0.05 } });
+ await background;
+ await until(() => gates.length === 3, 'the next request starts once the check cost $0.05');
+ gates[2].release({ content: 'ok', usage: { cost_usd: 0.1 } });
+ await next;
+ assert.ok(Math.abs(costState.spentUsd - 0.95) < 1e-9, `spent ${costState.spentUsd}`);
+ // Over the limit on what was spent alone, a request is refused at once.
+ costState.spentUsd = 1;
+ await assert.rejects(ask('after the limit'), error => agent._isCostAllowanceError(error));
+ assert.equal(gates.length, 3);
+ });
+
test(`${browser}: every predispatch stage the agent records survives the trace projection`, async () => {
const fs = await import('node:fs/promises');
const source = await fs.readFile(new URL(`../src/${browser}/src/agent/agent.js`, import.meta.url), 'utf8');