Skip to content

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

Keep inference cache-only when a Bonsai graph is stale

Claudef04077b805d7
diff --git a/scripts/models/bonsai/README.md b/scripts/models/bonsai/README.md
index cdcf07edc..aafa9a2c9 100644
--- a/scripts/models/bonsai/README.md
+++ b/scripts/models/bonsai/README.md
@@ -77,9 +77,10 @@ checked against the bundle's graph hash and FP16 tolerances, and the model card
states parity or timing results only for reports that pass; otherwise it says
the evidence is pending, and a failing report stops the build. Browser evidence
recorded against the previous graph is not carried over; rerun the WebGPU
-checks below on the new bundle. The worker replaces a stale cached graph for the two
-webbrain-one Vision repositories by SHA-256, so existing installs only
-download the new 3 MB graph file.
+checks below on the new bundle. For the two webbrain-one Vision repositories
+the worker compares the cached graph with a pinned SHA-256. Inference stays
+cache-only and keeps using a stale graph; an explicit download of the model
+replaces just the 3 MB graph file and keeps the cached weights.
## Runtime contract
diff --git a/src/chrome/src/offscreen/inference-worker.js b/src/chrome/src/offscreen/inference-worker.js
index 0c87cf35d..e6060640e 100644
--- a/src/chrome/src/offscreen/inference-worker.js
+++ b/src/chrome/src/offscreen/inference-worker.js
@@ -229,10 +229,13 @@ async function sha256Hex(buffer) {
/**
* Make a cached Bonsai 2 Vision decoder graph the parallel-prefill revision.
- * Best effort: offline or unexpected responses keep the cached graph, which
- * still produces the same answers, only with slower prefill.
+ * Inference loads are cache-only, so they only detect a stale graph
+ * ('stale'); the replacement is fetched solely from explicit download flows
+ * (`allowNetwork`). Offline or unexpected responses keep the cached graph,
+ * which still produces the same answers, only with slower prefill.
*/
export async function refreshBonsai2DecoderGraph(modelId, {
+ allowNetwork = false,
expected = BONSAI2_DECODER_GRAPH_SHA256.get(modelId),
timeoutMs = BONSAI2_DECODER_GRAPH_REFRESH_TIMEOUT_MS,
} = {}) {
@@ -255,6 +258,8 @@ export async function refreshBonsai2DecoderGraph(modelId, {
} catch {
return 'unavailable';
}
+ // Cache-only loads (inference) never download; an explicit download replaces it.
+ if (!allowNetwork) return 'stale';
const fetcher = typeof globalThis.fetch === 'function' ? globalThis.fetch.bind(globalThis) : nativeFetch;
if (!fetcher) return 'unavailable';
// Known offline (Apocalypse Mode): load the cached graph now and retry on a
@@ -789,7 +794,10 @@ async function getVisionRuntime(modelId, dtype, device, {
error.code = readiness === 'text' ? 'text_model_not_downloaded' : 'vision_model_not_downloaded';
throw error;
}
- if (WEBGPU_BONSAI2_VISION_MODEL_IDS.has(modelId)) await refreshBonsai2DecoderGraph(modelId);
+ if (WEBGPU_BONSAI2_VISION_MODEL_IDS.has(modelId)
+ && await refreshBonsai2DecoderGraph(modelId, { allowNetwork: !localFilesOnly }) === 'stale') {
+ console.info(`[webgpu] ${modelId}: the cached decoder graph predates parallel prefill; download the model again to update it.`);
+ }
const library = await loadLibrary();
const { AutoModelForImageTextToText, AutoProcessor } = library;
if (!AutoModelForImageTextToText || !AutoProcessor) {
@@ -1121,6 +1129,10 @@ async function downloadTextModel(payload, { onStarted } = {}) {
}
await clearLegacyLfm25VlWrongPrecisionCache(modelId, dtype);
if (await isTextModelReady(modelId, dtype)) {
+ // An explicit download of a cached model is the update path for its graph.
+ if (WEBGPU_BONSAI2_VISION_MODEL_IDS.has(modelId)) {
+ await refreshBonsai2DecoderGraph(modelId, { allowNetwork: true });
+ }
if (payload?.requireTools === true) {
const runtime = await getDownloadedTextRuntime(modelId, dtype, device, { localFilesOnly: true });
assertToolCapableTextRuntime(runtime, modelId);
diff --git a/test/run.js b/test/run.js
index 403b4f7ec..a2b719dd0 100644
--- a/test/run.js
+++ b/test/run.js
@@ -67570,17 +67570,23 @@ test('Bonsai 2 Vision worker replaces only a stale cached decoder graph', async
assert.match(workerSource, new RegExp(`'webbrain-one/Ternary-Bonsai-2-${size}-ONNX-WebGPU-Vision', '[0-9a-f]{64}'`),
`the ${size} Vision decoder graph must be pinned by SHA-256`);
}
+ assert.match(workerSource, /refreshBonsai2DecoderGraph\(modelId, \{ allowNetwork: !localFilesOnly \}\)/,
+ 'runtime loads may download the graph only outside cache-only inference');
const entries = new Map([[graphUrl, 'scan graph'], [dataUrl, 'weights']]);
const fetched = [];
globalThis.caches = { open: async () => makeCache(entries) };
globalThis.fetch = async (url, init) => { fetched.push([url, init?.cache]); return new Response('chunked graph'); };
const worker = await import(`${pathToFileURL(path.join(ROOT, 'src/chrome/src/offscreen/inference-worker.js')).href}?bonsai2-graph-refresh`);
- assert.equal(await worker.refreshBonsai2DecoderGraph(model, { expected: sha('chunked graph') }), 'updated');
+ assert.equal(await worker.refreshBonsai2DecoderGraph(model, { expected: sha('chunked graph') }), 'stale',
+ 'cache-only (inference) loads detect a stale graph without downloading');
+ assert.deepEqual(fetched, [], 'inference must never reach the network');
+ assert.equal(entries.get(graphUrl), 'scan graph');
+ assert.equal(await worker.refreshBonsai2DecoderGraph(model, { allowNetwork: true, expected: sha('chunked graph') }), 'updated');
assert.equal(entries.get(graphUrl), 'chunked graph');
assert.equal(entries.get(dataUrl), 'weights', 'the unchanged weight file must stay cached');
assert.deepEqual(fetched, [[graphUrl, 'no-store']]);
- assert.equal(await worker.refreshBonsai2DecoderGraph(model, { expected: sha('chunked graph') }), 'skipped',
+ assert.equal(await worker.refreshBonsai2DecoderGraph(model, { allowNetwork: true, expected: sha('chunked graph') }), 'skipped',
'a verified graph is not re-hashed on every runtime load');
assert.equal(await worker.refreshBonsai2DecoderGraph('danyalmalik/Ternary-Bonsai-2-2B-ONNX-WebGPU'), 'skipped');
@@ -67588,15 +67594,15 @@ test('Bonsai 2 Vision worker replaces only a stale cached decoder graph', async
const otherUrl = `https://huggingface.co/${other}/resolve/main/onnx/decoder_model_merged_q2f16.onnx`;
entries.set(otherUrl, 'scan graph');
globalThis.fetch = async () => new Response('tampered graph');
- assert.equal(await worker.refreshBonsai2DecoderGraph(other, { expected: sha('chunked graph') }), 'unexpected');
+ assert.equal(await worker.refreshBonsai2DecoderGraph(other, { allowNetwork: true, expected: sha('chunked graph') }), 'unexpected');
assert.equal(entries.get(otherUrl), 'scan graph', 'an unverified response must not replace the cached graph');
- assert.equal(await worker.refreshBonsai2DecoderGraph(other, { expected: sha('chunked graph') }), 'skipped',
+ assert.equal(await worker.refreshBonsai2DecoderGraph(other, { allowNetwork: true, expected: sha('chunked graph') }), 'skipped',
'a failed refresh is attempted once per worker lifetime, not on every runtime load');
const fresh = async tag => import(`${pathToFileURL(path.join(ROOT, 'src/chrome/src/offscreen/inference-worker.js')).href}?bonsai2-graph-refresh-${tag}`);
const offline = await fresh('offline');
globalThis.fetch = async () => { throw new TypeError('Failed to fetch'); };
- assert.equal(await offline.refreshBonsai2DecoderGraph(other, { expected: sha('chunked graph') }), 'unavailable');
+ assert.equal(await offline.refreshBonsai2DecoderGraph(other, { allowNetwork: true, expected: sha('chunked graph') }), 'unavailable');
assert.equal(entries.get(otherUrl), 'scan graph', 'offline loads keep the working cached graph');
const stalled = await fresh('stalled');
@@ -67605,7 +67611,7 @@ test('Bonsai 2 Vision worker replaces only a stale cached decoder graph', async
init.signal.addEventListener('abort', () => { aborted = true; reject(new DOMException('Aborted', 'AbortError')); });
});
const started = Date.now();
- assert.equal(await stalled.refreshBonsai2DecoderGraph(other, { expected: sha('chunked graph'), timeoutMs: 50 }), 'unavailable');
+ assert.equal(await stalled.refreshBonsai2DecoderGraph(other, { allowNetwork: true, expected: sha('chunked graph'), timeoutMs: 50 }), 'unavailable');
assert.equal(aborted, true, 'a stalled refresh must be aborted');
assert.ok(Date.now() - started < 2000, 'a stalled refresh must not hold up model loading');
assert.equal(entries.get(otherUrl), 'scan graph');
@@ -67616,10 +67622,10 @@ test('Bonsai 2 Vision worker replaces only a stale cached decoder graph', async
globalThis.fetch = async () => { fetchCalls++; return new Response('chunked graph'); };
try {
Object.defineProperty(globalThis, 'navigator', { configurable: true, value: { onLine: false } });
- assert.equal(await knownOffline.refreshBonsai2DecoderGraph(other, { expected: sha('chunked graph') }), 'unavailable');
+ assert.equal(await knownOffline.refreshBonsai2DecoderGraph(other, { allowNetwork: true, expected: sha('chunked graph') }), 'unavailable');
assert.equal(fetchCalls, 0, 'a known-offline worker must not wait on the network');
Object.defineProperty(globalThis, 'navigator', { configurable: true, value: { onLine: true } });
- assert.equal(await knownOffline.refreshBonsai2DecoderGraph(other, { expected: sha('chunked graph') }), 'updated',
+ assert.equal(await knownOffline.refreshBonsai2DecoderGraph(other, { allowNetwork: true, expected: sha('chunked graph') }), 'updated',
'a refresh skipped while offline is retried once the worker is online');
} finally {
if (navigatorDescriptor) Object.defineProperty(globalThis, 'navigator', navigatorDescriptor);
@@ -67629,7 +67635,7 @@ test('Bonsai 2 Vision worker replaces only a stale cached decoder graph', async
const current = await fresh('current');
entries.set(otherUrl, 'chunked graph');
- assert.equal(await current.refreshBonsai2DecoderGraph(other, { expected: sha('chunked graph') }), 'current');
+ assert.equal(await current.refreshBonsai2DecoderGraph(other, { allowNetwork: true, expected: sha('chunked graph') }), 'current');
} finally {
if (previousSelf === undefined) delete globalThis.self;
else globalThis.self = previousSelf;