Open-source AI browser agent for Chrome and Firefox (monorepo) ðŸ§
JavaScript ai-agentai-agentsai-toolsbrowser-aibrowser-automationbrowser-extensionchrome-aichrome-devtoolschrome-extensionchrome-extensionsfirefox-addonfirefox-addonsfirefox-extensionfirefox-extensionsgemmagemma4minimaxoffline-aioffline-llmqwen
Fix workflow recovery receipts and actor evidence ownership
Codex release-state test9750b3450c07
diff --git a/website-tests/README.md b/website-tests/README.mdindex b568bfd4b..e985968bb 100644--- a/website-tests/README.md+++ b/website-tests/README.md@@ -181,16 +181,16 @@ build. Configure `manualActorIdentityVerified:true` only after checking A'sactual login in the chosen browser; the string `"false"` is not confirmation.Cloud REST has no documented DOM/control endpoint. A separate logged-in local-B can independently prove public posts, incoming mail/messages and shared access,-but cannot observe A's private unsent draft or pre-share folder. Full workflows-therefore require explicit actor-tab manual evidence for those phases. Without-it, preflight reports unsupported before dispatching a private-phase task.+B can independently prove incoming mail/messages and shared access in the+separate receiver stages. Every A stage requires explicit actor-tab manual+evidence, including sends, replies and cleanup, so captured message/thread IDs+belong to A's account. Without it, preflight reports unsupported before dispatch.Automated active steering/checkpoints are also unsupported on REST alone.Finished-run `/messages` continuation is not active-run steering.For manual verification set `manualEvidenceFile` to an ignored private JSONfile and run in an interactive terminal. A noninteractive CLI with no manual-observer callback is blocked before any private-phase task. Each checkpoint writes a private+observer callback is blocked before any actor task. Each checkpoint writes a privaterequirement file with the exact run marker, stage, expected body/account/resource.Observe the actual browser and append evidence to `{ "observations": [...] }`.Rows use the same `webbrain-authenticated-evidence/1` schema as DOM observations,@@ -290,6 +290,12 @@ select the matching dashboard run explicitly:npm run reconcile -- --report RUN_DIRECTORY --request-id RECORDED_REQUEST_ID --run-id CONFIRMED_RUN_ID```+Local shutdown saves exact terminal extension receipts in the private ledger+before closing actor tabs. Recovery can use those receipts after the live tab+journal has been deleted, and still requires independent effect evidence. If a+receipt cannot be saved or the run is still active, shutdown retains the browser+and its tabs for reconciliation.+Reconciliation reads existing runs/effects and never resends. An ambiguous Cloudupload can be reconciled by its recorded byte hash and exact server filename;use `--remote-name CONFIRMED_SERVER_FILENAME` if its upload response was lost. Cleanup operatesdiff --git a/website-tests/backends/local.mjs b/website-tests/backends/local.mjsindex fef3ae8e5..5698d6aba 100644--- a/website-tests/backends/local.mjs+++ b/website-tests/backends/local.mjs@@ -630,9 +630,20 @@ export function createLocalBackend(role, options = {}) {if (!mime) throw new Error('Only WebBrain-supported text, image and PDF chat attachments are accepted.');return { name, kind: extension === '.pdf' ? 'document' : 'image', mimeType: mime, dataUrl: `data:${mime};base64,${bytes.toString('base64')}` };},- async close() {+ async close({ pendingEntries = [], saveReceipt } = {}) {for (const entry of [...activeRuns.values()]) await backend.stop(entry.handle).catch(() => {});- for (const page of ownedPages) await page.close().catch(() => {});+ // Closing a tab deletes the extension journal. Persist exact terminal+ // receipts first; otherwise retain the browser for live reconciliation.+ let preserveBrowser = false;+ for (const entry of pendingEntries) {+ try {+ const receipt = await backend.inspectSavedRun(entry);+ if (!saveReceipt || receipt.active || !terminalStatuses.has(receipt.status)) throw new Error('Journal is not durably terminal.');+ await saveReceipt(entry, receipt);+ } catch { preserveBrowser = true; }+ }+ if (preserveBrowser && !attached) return { preserved: true };+ if (!preserveBrowser) for (const page of ownedPages) await page.close().catch(() => {});ownedPages.clear(); handles.clear(); checkpoints.clear();await transport?.close?.().catch(() => {});transport = null;diff --git a/website-tests/core.test.mjs b/website-tests/core.test.mjsindex 539bd7767..8adad7814 100644--- a/website-tests/core.test.mjs+++ b/website-tests/core.test.mjs@@ -215,3 +215,36 @@ test('copied placeholder configuration defaults to exactly one owned fixture andconst live = await loadConfig({ cwd, env: {}, overrides: { target: 'live' } }); assert.equal(selectScenarios(live).length, 8);await assert.rejects(main(['run', '--target', 'live'], { cwd, env: {} }), { code: 'live_scenario_selection_required' });});++test('paired Cloud stages use actor evidence and reserve B for receipts', async t => {+ const cfg = await config(t, { actors: { A: { backend: 'cloud', name: 'actor' }, B: { backend: 'local', name: 'observer' } }, manualEvidenceFile: 'unused' });+ Object.assign(cfg.sites.x, { manualActorIdentityVerified: true, observerIdentity: 'receiver', recipientIdentity: 'receiver', recipient: 'receiver' });+ cfg.allowedRecipients = ['receiver'];+ const { runner } = injectedRunner(cfg, path.join(cfg.artifacts, 'one'));+ runner.manualCheckpoint = async () => {};+ await runner.backend('A');+ runner.backends.A.capabilities.domObservation = false;+ const roles = [];+ runner.observe = async role => { roles.push(role); return { actualEffect: true }; };+ await runner.initialize();+ const result = await runner.runScenario({ ...simpleScenario, requiresObserver: true,+ steps: [{ id: 'publish', actor: 'A', action: 'post' }, { id: 'receipt', actor: 'B', action: 'navigation' }] });+ await runner.close();+ assert.equal(result.status, 'passed', JSON.stringify(result));+ assert.deepEqual(roles, ['A', 'B']);+});++test('runner shutdown durably saves pending local receipts', async t => {+ const cfg = await config(t), { runner } = injectedRunner(cfg, path.join(cfg.artifacts, 'one'), { observed: false });+ await runner.initialize(); await runner.runScenario(simpleScenario);+ runner.backends.A.close = async ({ pendingEntries, saveReceipt }) => {+ assert.equal(pendingEntries.length, 1);+ const entry = pendingEntries[0];+ await saveReceipt(entry, { backend: 'local', source: 'installed-extension-run-journal', tabId: entry.tabId,+ requestId: entry.requestId, runId: entry.runId, status: 'completed', active: false, content: 'private' });+ };+ await runner.close();+ const ledger = await MutationLedger.load(runner.ledger.filename, cfg);+ assert.equal(ledger.pendingEntries()[0].localReceipt.status, 'completed');+ assert.equal(JSON.stringify(ledger.data).includes('private'), false);+});diff --git a/website-tests/ledger.mjs b/website-tests/ledger.mjsindex 914efa84f..9c9ab5c60 100644--- a/website-tests/ledger.mjs+++ b/website-tests/ledger.mjs@@ -38,6 +38,13 @@ export class MutationLedger {for (const key of ['status', 'runId', 'sessionId', 'tabId', 'completedAt', 'code', 'verifiedAt', 'remoteName', 'sha256']) if (patch[key] !== undefined) entry[key] = patch[key];await this.save(); return entry;}+ async saveLocalReceipt(requestId, receipt) {+ const entry = this.data.entries.find(item => item.requestId === requestId);+ if (!validLocalReceipt(entry, receipt)) throw new HarnessError('local_saved_run_identity_mismatch');+ entry.localReceipt = { backend: 'local', source: receipt.source, tabId: receipt.tabId,+ requestId, runId: receipt.runId, status: receipt.status, active: false };+ await this.save();+ }async recordResource(entry, resource, identity) {if (!resource?.id || !resource?.url || !identity) throw new HarnessError('resource_ownership_unproven');const item = { id: resource.id, url: resource.url, kind: resource.kind, conversationId: resource.conversationId,@@ -59,3 +66,10 @@ export class MutationLedger {pendingEntries() { return this.data.entries.filter(e => ['attempted', 'accepted', 'ambiguous', 'running', 'needs_user_input'].includes(e.status)); }pendingResources() { return this.data.resources.filter(r => r.cleanup !== 'verified'); }}++export function validLocalReceipt(entry, receipt) {+ return !!entry && receipt?.backend === 'local' && receipt.source === 'installed-extension-run-journal'+ && Number.isSafeInteger(entry.tabId) && entry.tabId > 0 && receipt.tabId === entry.tabId && receipt.requestId === entry.requestId && !!receipt.runId+ && (!entry.runId || receipt.runId === entry.runId) && receipt.active === false+ && ['completed', 'failed', 'aborted', 'stopped', 'cancelled'].includes(receipt.status);+}diff --git a/website-tests/local.test.mjs b/website-tests/local.test.mjsindex e26a118e7..ab213cb7d 100644--- a/website-tests/local.test.mjs+++ b/website-tests/local.test.mjs@@ -621,3 +621,22 @@ test('installed MV3 extension reports real source and attached-browser detach prconst stillAlive = await fetch(`${cdpUrl}/json/version`);assert.equal(stillAlive.status, 200, 'CDP detachment leaves the Chrome process alive.');});++test('shutdown saves an exact terminal receipt before destroying its tab journal', async t => {+ const { backend, calls } = await rig(t, { prior: { requestId: 'saved-request', runId: 'saved-run', status: 'failed', events: [] } });+ await backend.connect(); await backend.open('https://x.com/');+ await backend.close({ pendingEntries: [{ tabId: 31, runId: 'saved-run', requestId: 'saved-request' }],+ saveReceipt: async (entry, receipt) => {+ assert.equal(calls.some(call => call[0] === 'page.close'), false);+ assert.equal(receipt.requestId, entry.requestId); assert.equal(receipt.status, 'failed');+ calls.push(['receipt.saved']);+ } });+ assert.ok(calls.findIndex(call => call[0] === 'receipt.saved') < calls.findIndex(call => call[0] === 'page.close'));+});++test('shutdown preserves a dedicated browser if its pending receipt cannot be saved', async t => {+ const { backend, calls } = await rig(t);+ await backend.connect(); await backend.open('https://x.com/');+ assert.deepEqual(await backend.close({ pendingEntries: [{ tabId: 31, requestId: 'unknown' }], saveReceipt: async () => {} }), { preserved: true });+ assert.equal(calls.some(call => ['page.close', 'context.close', 'transport.close'].includes(call[0])), false);+});diff --git a/website-tests/recovery.mjs b/website-tests/recovery.mjsindex b68556d99..4ef12180b 100644--- a/website-tests/recovery.mjs+++ b/website-tests/recovery.mjs@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';import path from 'node:path';import { createHash, randomUUID } from 'node:crypto';import { authorize, HarnessError, lockFiles, placeholder, redact, safeError } from './config.mjs';-import { MutationLedger } from './ledger.mjs';+import { MutationLedger, validLocalReceipt } from './ledger.mjs';import { WorkflowRunner, createBackend, publicDoctor } from './runner.mjs';import { sites, normalizeIdentity } from './sites.mjs';import { scenarios, planTask, verifyEvidence } from './scenarios.mjs';@@ -261,7 +261,8 @@ export async function recover(config, directory, args = {}, cleanup = false, { bif (!runId && !entry.tabId) fail('explicit_dispatch_receipt_required');const value = await backend(role, entry);const runtime = config.actors[role].backend === 'cloud' ? await value.getRun(runId)- : value.inspectSavedRun ? await value.inspectSavedRun(entry) : null;+ : validLocalReceipt(entry, entry.localReceipt) ? entry.localReceipt+ : value.inspectSavedRun ? await value.inspectSavedRun(entry) : null;if (!runtime) fail('runtime_terminal_receipt_required');const terminal = runtime.active !== true && TERMINAL.has(runtime.status);receipts.set(entry.requestId, { terminal, runtime });diff --git a/website-tests/recovery.test.mjs b/website-tests/recovery.test.mjsindex 083240123..625fbdee6 100644--- a/website-tests/recovery.test.mjs+++ b/website-tests/recovery.test.mjs@@ -436,3 +436,25 @@ test('unknown upload hash or mismatched remote bytes remain pending without anyassert.equal((await loaded(mismatch)).pendingEntries().length, 1);assert.ok(mismatch.calls.every(call => call.method === 'GET' || call.method === 'POST' && call.url.endsWith('/downloads-access')));});++test('recovery uses a durable exact local receipt after shutdown deletes the live journal', async t => {+ const ctx = await setup(t);+ await capture(ctx, 'publish', { id: '123', url: ctx.binding.url, kind: 'post' });+ const entry = await ctx.ledger.attempt({ scenario: ctx.scenario.id, stage: 'cleanup', actor: 'A', action: 'delete', marker });+ await ctx.ledger.update(entry.requestId, { status: 'ambiguous', tabId: 7, runId: 'cleanup-run' });+ await ctx.ledger.saveLocalReceipt(entry.requestId, { backend: 'local', source: 'installed-extension-run-journal',+ tabId: 7, requestId: entry.requestId, runId: 'cleanup-run', active: false, status: 'stopped' });+ await assert.rejects(ctx.ledger.saveLocalReceipt(entry.requestId, { ...entry.localReceipt, runId: 'other' }), { code: 'local_saved_run_identity_mismatch' });+ const mock = injected(ctx, { removed: ['123'] });+ const original = mock.backendFactory;+ mock.backendFactory = async (...args) => {+ const backend = await original(...args);+ backend.inspectSavedRun = async () => { throw new Error('Tab was closed'); };+ return backend;+ };+ const report = await recover(ctx.config, ctx.directory, {}, false, mock);+ assert.equal(report.counts.blocked, 0, JSON.stringify(report));+ assert.equal((await loaded(ctx)).pendingEntries().length, 0);+ assert.equal((await loaded(ctx)).pendingResources().length, 0);+ assert.equal(mock.calls.run.length, 0);+});diff --git a/website-tests/runner.mjs b/website-tests/runner.mjsindex b6d8135b4..9a9cb7abd 100644--- a/website-tests/runner.mjs+++ b/website-tests/runner.mjs@@ -189,10 +189,9 @@ export class WorkflowRunner {if (!site.originAllowed(url, binding)) throw new HarnessError('site_origin_mismatch');if (this.config.actors.A.backend === 'cloud' && binding.manualActorIdentityVerified !== true)throw new HarnessError('cloud_actor_identity_confirmation_required');- const cloudPrivatePhases = this.config.actors.A.backend === 'cloud' && scenario.steps.some(stage =>- stage.expectation === 'composer' || scenario.kind === 'files');- if (cloudPrivatePhases && (!this.config.manualEvidenceFile || !this.manualCheckpoint))- throw new HarnessError('cloud_private_phase_requires_manual_evidence', 'A receiver cannot observe the actor’s private draft/folder.', 'unsupported');+ const cloudActorEvidence = this.config.actors.A.backend === 'cloud' && scenario.steps.some(stage => stage.actor !== 'B');+ if (cloudActorEvidence && (!this.config.manualEvidenceFile || !this.manualCheckpoint))+ throw new HarnessError('cloud_private_phase_requires_manual_evidence', 'Actor stages require evidence from the actor’s selected browser.', 'unsupported');const actor = await this.backend('A');// Establish independent observation before allowing any remote mutation.const observerRole = scenario.requiresObserver || actor.capabilities?.domObservation === false && this.config.actors.B.backend ? 'B' : 'A';@@ -241,8 +240,7 @@ export class WorkflowRunner {const plan = this.taskPlanner({ scenario, stage, context });const task = typeof plan === 'string' ? plan : plan.task;const phase = plan.observation?.phase || stage.phase || stage.expectation || 'resource';- const actorPrivatePhase = phase === 'composer' || scenario.kind === 'files' && stage.actor !== 'B';- const viewRole = stage.actor === 'B' ? 'B' : actor.capabilities?.domObservation === false && !actorPrivatePhase ? observerRole : 'A';+ const viewRole = stage.actor === 'B' ? 'B' : 'A';let observedContext = { ...context, ...plan.observation, observedAfter: new Date(stageStart).toISOString(), expectedIdentity: viewRole === 'B' ? binding.observerIdentity || binding.recipientIdentity : binding.expectedIdentity };if (stage.actor === 'B' && stage.action === 'navigation') {const evidence = await this.observe('B', scenario.site, observedContext, phase);@@ -350,7 +348,10 @@ export class WorkflowRunner {}async close() {if (this.events.length) await fs.writeFile(path.join(this.directory, 'events.json'), JSON.stringify(this.events, null, 2), { mode: 0o600 });- for (const backend of Object.values(this.backends)) await backend.close().catch(() => {});+ for (const [role, backend] of Object.entries(this.backends)) await backend.close({+ pendingEntries: this.ledger?.pendingEntries().filter(entry => entry.actor === role) || [],+ saveReceipt: (entry, receipt) => this.ledger.saveLocalReceipt(entry.requestId, receipt),+ }).catch(() => {});for (const lockPath of this.lockPaths || []) {if (!this.ledger) continue;const lock = JSON.parse(await fs.readFile(lockPath, 'utf8'));