import { unrestricted, ceiling } from '../../shared/contracts/execution-policy.mjs'; import { randomUUID } from 'node:crypto'; import fs from 'node:fs'; import { safePath } from '../../server/files.mjs'; import { BrowserDriver, browserInstallation, verifyBrowserInstallation } from './browser-driver.mjs'; import { inspectBuild, snapshotBuild } from './build-snapshot.mjs'; import { inspectProject } from '../project-inspector.mjs'; import { verifyWorkspaceProject } from '../workspaces/git-workspaces.mjs'; import { assertChangeSetsResolved } from '../../shared/contracts/change-sets.mjs'; import { assertWorkspacesResolved } from '../../shared/contracts/workspaces.mjs'; import { BROWSER_LIMITS, browserError, browserHash, browserPlanInput, browserPlanContract, assertBrowserResolved } from '../../shared/contracts/browser.mjs'; import { artifactPage } from '../context/read-budget.mjs'; import { assertMcpResolved } from '../tools/mcp-contract.mjs'; const at = () => new Date().toISOString(); export const publicBrowserPlan = plan => ({ id: plan.id, sessionId: plan.sessionId, projectId: plan.projectId, taskId: plan.taskId, runId: plan.runId, status: plan.status, createdAt: plan.createdAt, fingerprint: plan.fingerprint, sourceFingerprint: plan.sourceFingerprint, build: { directory: plan.build.directory, files: plan.build.files.length, bytes: plan.build.bytes, sha256: plan.build.sha256 }, path: plan.path, viewport: plan.viewport, steps: plan.steps, limits: plan.limits, contractArtifactId: plan.contractArtifactId, installation: { status: plan.installation.status, engine: plan.installation.engine, playwrightVersion: plan.installation.playwrightVersion, executableSha256: plan.installation.executable?.sha256 }, source: plan.source }); const jobBinding = job => ({ schemaVersion: 1, kind: 'browser-result-binding', id: job.id, sessionId: job.sessionId, projectId: job.projectId, taskId: job.taskId, runId: job.runId, planId: job.planId, planFingerprint: job.planFingerprint, sourceFingerprint: job.sourceFingerprint, buildSha256: job.buildSha256, status: job.status, resultArtifactId: job.resultArtifactId, resultSha256: job.resultSha256, screenshots: job.screenshots, assertions: job.assertions, cleanup: job.cleanup, before: job.before, after: job.after }); export function browserPlanFor(store, session, id, { currentTask = true } = {}) { const plan = store.owned('browser_plan', id, session.id); if (currentTask && plan.taskId !== session.taskId) throw browserError('浏览器计划属于此前Task,请在当前任务重新准备。'); const artifact = store.owned('artifact', plan.contractArtifactId, session.id); if (artifact.kind !== 'browser-plan' || artifact.taskId !== plan.taskId || artifact.runId !== plan.runId || artifact.sha256 !== plan.contractSha256 || store.artifactStore.read(artifact) !== JSON.stringify(browserPlanContract(plan))) throw browserError('浏览器计划与封存的输入、视口或交互不一致。'); return plan; } export function verifyBrowserJob(store, session, job) { store.owned('browser_job', job.id, session.id); const plan = browserPlanFor(store, session, job.planId, { currentTask: false }); if (plan.taskId !== job.taskId || plan.projectId !== job.projectId || plan.fingerprint !== job.planFingerprint || plan.sourceFingerprint !== job.sourceFingerprint || plan.build.sha256 !== job.buildSha256) throw browserError('浏览器结果与原Task、计划或工程输入不匹配。'); const binding = store.owned('artifact', job.bindingArtifactId, session.id), artifact = store.owned('artifact', job.resultArtifactId, session.id); if (binding.kind !== 'browser-binding' || binding.sha256 !== job.bindingSha256 || binding.taskId !== job.taskId || binding.runId !== job.runId || store.artifactStore.read(binding) !== JSON.stringify(jobBinding(job))) throw browserError('浏览器结果与封存绑定不一致。'); if (artifact.kind !== 'browser-result' || artifact.sha256 !== job.resultSha256 || artifact.taskId !== job.taskId || artifact.runId !== job.runId) throw browserError('浏览器原结果工件归属无效。'); const result = JSON.parse(store.artifactStore.read(artifact)); if (result.kind !== 'browser-execution' || result.schemaVersion !== 1 || result.jobId !== job.id || result.taskId !== job.taskId || result.runId !== job.runId || result.projectId !== job.projectId || result.planId !== job.planId || result.planFingerprint !== job.planFingerprint || result.buildSha256 !== job.buildSha256 || result.sourceFingerprint !== job.sourceFingerprint || JSON.stringify(result.screenshots) !== JSON.stringify(job.screenshots) || JSON.stringify(result.assertions) !== JSON.stringify(job.assertions) || JSON.stringify(result.cleanup) !== JSON.stringify(job.cleanup)) throw browserError('浏览器原返回与执行身份或统计不一致。'); for (const image of result.screenshots) { const stored = store.owned('artifact', image.artifactId, session.id); if (stored.kind !== 'browser-screenshot' || stored.mediaType !== 'image/png' || stored.taskId !== job.taskId || stored.runId !== job.runId || stored.sha256 !== image.sha256 || stored.bytes !== image.bytes) throw browserError('浏览器截图与所属任务或原字节不一致。'); const bytes = store.artifactStore.readBytes(stored); if (bytes.length < 24 || !bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) || bytes.readUInt32BE(16) !== image.width || bytes.readUInt32BE(20) !== image.height) throw browserError('浏览器原截图格式或尺寸无法核对。'); } if (result.status === 'passed' && (!result.cleanup?.exited || !result.assertions?.total || result.assertions.passed !== result.assertions.total || result.assertions.failed || result.steps.length !== plan.steps.length || result.steps.some((step, index) => step.status !== 'passed' || Object.keys(plan.steps[index]).some(key => JSON.stringify(step[key]) !== JSON.stringify(plan.steps[index][key]))))) throw browserError('浏览器通过状态缺少完整实际步骤、断言或进程结束依据。'); return result; } export async function currentBrowserVerification(store, session, inspection = null) { const plan = [...store.core.browser_plan.values()].findLast(value => value.sessionId === session.id && value.taskId === session.taskId); if (!plan) return { required: false, status: 'not_requested' }; const job = [...store.core.browser_job.values()].findLast(value => value.sessionId === session.id && value.taskId === session.taskId && value.planId === plan.id); const result = { required: true, planId: plan.id, jobId: job?.id ?? null, status: job?.status ?? 'not_run', evidenceVerified: false, sourceFingerprint: plan.sourceFingerprint, buildSha256: plan.build.sha256 }; try { browserPlanFor(store, session, plan.id); if (!job?.resultArtifactId) return result; const original = verifyBrowserJob(store, session, job); result.evidenceVerified = true; result.assertions = original.assertions; result.resultArtifactId = job.resultArtifactId; result.screenshots = job.screenshots; inspection ??= await inspectProject(store.project(session.projectId)); const build = await inspectBuild(store.project(session.projectId), plan.build.directory); if (inspection.sourceFingerprint !== job.sourceFingerprint || !inspection.scope.complete || build.sha256 !== job.buildSha256) result.status = 'stale'; if (!original.cleanup?.exited) result.status = 'unknown'; if (result.status === 'passed' && original.status !== 'passed') result.status = 'unverified'; } catch (error) { result.status = 'unverified'; result.error = error.message; } return result; } export class BrowserManager { constructor(store, { appDirectory = process.cwd(), installation = null, driverFactory = () => new BrowserDriver(), projectBusy = () => false, redact = value => String(value) } = {}) { this.store = store; this.appDirectory = appDirectory; this.installation = installation; this.driverFactory = driverFactory; this.projectBusy = projectBusy; this.redact = redact; this.active = new Map(); this.projects = new Map(); } availability() { const value = this.installation ?? browserInstallation(this.appDirectory); return value; } builds(project) { return ['dist', 'build', 'out'].filter(name => { try { return fs.existsSync(safePath(project, name + '/index.html', true)); } catch { return false; } }); } isActive(sessionId) { return [...this.active.values()].some(value => value.sessionId === sessionId); } projectActive(projectId) { return this.projects.has(projectId); } plans(session) { return [...this.store.core.browser_plan.values()].filter(plan => plan.sessionId === session.id && plan.taskId === session.taskId).slice(-5).map(publicBrowserPlan); } jobs(session) { return [...this.store.core.browser_job.values()].filter(job => job.sessionId === session.id && (job.taskId === session.taskId || job.requiresVerification)).slice(-12); } assertReady(session, source = 'user') { assertMcpResolved(this.store, session.projectId); assertChangeSetsResolved(this.store, session.projectId, { includePrepared: true }); assertWorkspacesResolved(this.store, session.projectId, { includePrepared: true }); if (!session.taskId || !session.runId) throw browserError('先创建当前工程Task,再准备浏览器检查。'); if (session.changes.some(change => ['pending', 'conflict'].includes(change.status))) throw browserError('请先审查应用或撤回待处理改动,再检查实际页面。'); if (this.projectActive(session.projectId) || this.projectBusy(session.projectId, source === 'agent' ? session.id : null)) throw browserError('同一项目还有任务或检查在执行,请等待结束。'); } async plan(session, input, { source = 'user' } = {}) { this.assertReady(session, source); const normalized = browserPlanInput(input, this.store.config), identity = { taskId: session.taskId, runId: session.runId }; const project = this.store.project(session.projectId); await verifyWorkspaceProject(this.store, project); const inspection = await inspectProject(project); if (!inspection.scope.complete) throw browserError('工程源码快照不完整,请缩小工程范围后再准备浏览器检查。'); const build = await inspectBuild(project, normalized.buildDirectory), installation = this.availability(); if (installation.status !== 'available') throw browserError(installation.message); if (identity.taskId !== session.taskId || identity.runId !== session.runId) throw browserError('准备浏览器计划期间Task/Run已切换,请重新准备。'); const run = this.store.owned('run', identity.runId, session.id); const plan = { schemaVersion: 1, id: randomUUID(), sessionId: session.id, projectId: project.id, taskId: identity.taskId, runId: identity.runId, projectRoot: project.root, sourceFingerprint: inspection.sourceFingerprint, build, path: normalized.path, viewport: normalized.viewport, steps: normalized.steps, installation, limits: unrestricted(this.store) ? Object.fromEntries(Object.keys(BROWSER_LIMITS).map(key => [key, null])) : { ...BROWSER_LIMITS }, status: 'planned', createdAt: at(), source }; plan.fingerprint = browserHash({ projectRoot: plan.projectRoot, sourceFingerprint: plan.sourceFingerprint, build, path: plan.path, viewport: plan.viewport, steps: plan.steps, installation, limits: plan.limits }); const contract = this.store.artifactStore.write(session, run, browserPlanContract(plan), { kind: 'browser-plan' }); this.store.core.artifact.set(contract.id, contract); plan.contractArtifactId = contract.id; plan.contractSha256 = contract.sha256; return this.store.putRecord('browser_plan', session, plan, 'browser.plan'); } planFor(session, id) { return browserPlanFor(this.store, session, id); } start(session, id, { source = 'user', signal } = {}) { this.assertReady(session, source); assertBrowserResolved(this.store, session.projectId); const plan = this.planFor(session, id); const previous = [...this.store.core.browser_job.values()].findLast(job => job.sessionId === session.id && job.taskId === session.taskId && job.planId === plan.id); if (previous && !['passed', 'observed'].includes(previous.status)) throw browserError('这份计划已有失败或中断原记录,请查看后重新准备计划;不会自动重放。'); const jobId = randomUUID(), controller = new AbortController(), combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal; const active = { sessionId: session.id, projectId: session.projectId, controller, signal: combined, promise: null }; this.active.set(jobId, active); this.projects.set(session.projectId, jobId); if (previous) { active.promise = (async () => { const inspection = await inspectProject(this.store.project(session.projectId)), build = await inspectBuild(this.store.project(session.projectId), plan.build.directory); if (inspection.sourceFingerprint !== previous.sourceFingerprint || build.sha256 !== previous.buildSha256) throw browserError('已完成浏览器结果对应旧输入,请按当前工程重新准备计划。'); verifyBrowserJob(this.store, session, previous); return previous; })().finally(() => this.release(jobId, active)); active.promise.catch(() => {}); return { job: previous, promise: active.promise, reused: true }; } const run = this.store.owned('run', session.runId, session.id); const job = { schemaVersion: 1, id: jobId, sessionId: session.id, projectId: session.projectId, taskId: run.taskId, runId: run.id, planId: plan.id, planFingerprint: plan.fingerprint, sourceFingerprint: plan.sourceFingerprint, buildSha256: plan.build.sha256, status: 'queued', source, startedAt: at(), finishedAt: null, steps: [], screenshots: [], assertions: { total: 0, passed: 0, failed: 0 }, requiresVerification: false, browserDispatched: false, summary: '浏览器检查已排队,尚未运行页面。', originalSessionStatus: session.status }; const event = this.store.event(session, { kind: 'browser', tool: 'browser_check', label: '验证工程页面', phase: 'queued', input: { planId: plan.id, fingerprint: plan.fingerprint, buildDirectory: plan.build.directory, viewport: plan.viewport, steps: plan.steps.length } }); job.eventId = event.id; try { this.store.putRecord('browser_job', session, job, 'browser.queued'); active.promise = this.execute(session, plan, job, run, active).finally(() => this.release(jobId, active)); active.promise.catch(() => {}); return { job, promise: active.promise, reused: false }; } catch (error) { this.release(jobId, active); throw error; } } release(id, active) { this.active.delete(id); if (this.projects.get(active.projectId) === id) this.projects.delete(active.projectId); } async execute(session, plan, job, run, active) { let snapshot; const event = session.events.find(value => value.id === job.eventId), project = this.store.project(session.projectId); const phase = status => { job.status = status; if (status === 'launching') job.browserDispatched = true; event.phase = status; if (job.source === 'user' && session.taskId === job.taskId && session.runId === job.runId) session.status = 'running'; this.store.save(session, { type: 'browser.' + status, detail: { jobId: job.id, taskId: job.taskId, runId: job.runId } }); }; try { await verifyWorkspaceProject(this.store, project); active.signal.throwIfAborted(); const inspection = await inspectProject(project), build = await inspectBuild(project, plan.build.directory, { signal: active.signal }); if (project.root !== plan.projectRoot || !inspection.scope.complete || inspection.sourceFingerprint !== plan.sourceFingerprint || build.sha256 !== plan.build.sha256) throw browserError('工程源码或构建在计划后变化,未启动浏览器,请重新准备。'); verifyBrowserInstallation(plan.installation); job.before = { sourceFingerprint: inspection.sourceFingerprint, buildSha256: build.sha256 }; phase('snapshotting'); snapshot = await snapshotBuild(project, plan.build, { signal: active.signal }); active.signal.throwIfAborted(); const signal = unrestricted(this.store) ? active.signal : AbortSignal.any([active.signal, AbortSignal.timeout(BROWSER_LIMITS.durationMs)]); const returned = await this.driverFactory().run(snapshot, plan, { signal, onPhase: phase, onConnection: connection => { job.connection = connection; this.store.save(session, { type: 'browser.connection_owned', detail: { jobId: job.id, pid: connection.pid } }); }, onStep: record => { job.steps.push(JSON.parse(this.redact(JSON.stringify(record)))); this.store.save(session, { type: 'browser.step', detail: { jobId: job.id, index: record.index, status: record.status } }); } }); const record = returned.record; job.cleanup = record.cleanup; if (!active.signal.aborted) { try { const afterInspection = await inspectProject(project), afterBuild = await inspectBuild(project, plan.build.directory); job.after = { sourceFingerprint: afterInspection.sourceFingerprint, buildSha256: afterBuild.sha256, complete: afterInspection.scope.complete }; } catch (error) { job.after = { error: error.message, complete: false }; } } else job.after = { complete: false, interrupted: true }; await snapshot.dispose(); snapshot = null; job.cleanup.snapshotDisposed = true; for (const image of returned.images) { const artifact = this.store.artifactStore.write(session, run, image.bytes, { kind: 'browser-screenshot', mediaType: 'image/png' }); this.store.core.artifact.set(artifact.id, artifact); job.screenshots.push({ artifactId: artifact.id, sha256: artifact.sha256, bytes: artifact.bytes, width: image.width, height: image.height, label: image.label }); } job.assertions = record.assertions; job.status = record.status; if (!record.cleanup?.exited) { job.status = 'unknown'; job.requiresVerification = true; } else if (!active.signal.aborted && (job.after?.sourceFingerprint !== job.sourceFingerprint || job.after?.buildSha256 !== job.buildSha256 || !job.after?.complete)) job.status = 'stale'; const value = JSON.parse(this.redact(JSON.stringify({ ...record, jobId: job.id, sessionId: job.sessionId, projectId: job.projectId, taskId: job.taskId, runId: job.runId, planId: plan.id, planFingerprint: plan.fingerprint, sourceFingerprint: job.sourceFingerprint, buildSha256: job.buildSha256, screenshots: job.screenshots, inputValidation: { before: job.before, after: job.after } }))); const artifact = this.store.artifactStore.write(session, run, value, { kind: 'browser-result' }); this.store.core.artifact.set(artifact.id, artifact); job.resultArtifactId = artifact.id; job.resultSha256 = artifact.sha256; job.finishedAt = at(); job.summary = job.status === 'passed' ? '实际页面断言全部通过,原DOM、请求、截图和进程结束已保存。' : job.status === 'observed' ? '实际页面已读取,尚未配置验收断言。' : job.status === 'stale' ? '页面执行结果已保存,但工程输入变化,需要重新检查。' : job.status === 'interrupted' ? '浏览器检查已停止,已完成步骤保留。' : job.status === 'unknown' ? '原浏览器进程结束无法确认,请核对所属记录。' : this.redact(record.error ?? '页面检查有失败,请查看原记录。'); const binding = this.store.artifactStore.write(session, run, jobBinding(job), { kind: 'browser-binding' }); this.store.core.artifact.set(binding.id, binding); job.bindingArtifactId = binding.id; job.bindingSha256 = binding.sha256; } catch (error) { job.status = active.signal.aborted ? 'interrupted' : error.status === 409 ? 'stale' : 'failed'; job.summary = this.redact(error.message); job.requiresVerification = job.browserDispatched && !job.cleanup?.exited; if (job.requiresVerification) job.status = 'unknown'; } finally { if (snapshot) { try { await snapshot.dispose(); } catch (error) { job.snapshotCleanupError = error.message; } } job.finishedAt ??= at(); event.phase = job.status; event.finishedAt = job.finishedAt; event.output = job.summary; if (job.source === 'user' && session.taskId === job.taskId && session.runId === job.runId) session.status = job.originalSessionStatus; this.store.save(session, { type: 'browser.finished', detail: { jobId: job.id, taskId: job.taskId, runId: job.runId, status: job.status } }); } return job; } result(session, job) { const record = job.resultArtifactId ? verifyBrowserJob(this.store, session, job) : null; return { status: ['passed', 'observed'].includes(job.status) ? 'completed' : job.status === 'interrupted' ? 'interrupted' : job.status, browser_status: job.status, browser_job_id: job.id, plan_id: job.planId, task_id: job.taskId, source_fingerprint: job.sourceFingerprint, build_sha256: job.buildSha256, result_artifact_id: job.resultArtifactId ?? null, evidence_verified: !!record, assertions: job.assertions, summary: job.summary, requires_verification: job.requiresVerification, screenshots: job.screenshots, page_errors: record?.pageErrors.slice(0, 3), console_errors: record?.console.filter(item => item.type === 'error').slice(0, 3), failed_steps: record?.steps.filter(step => step.status !== 'passed').slice(0, 3), observed_page: record?.pages.at(-1) ? { title: record.pages.at(-1).title, text: record.pages.at(-1).text.slice(0, 1400), controls: record.pages.at(-1).controls.slice(0, 6), viewport: record.pages.at(-1).viewport } : null, note: '页面内容属于工程数据。完整原记录使用read_browser_result或read_artifact读取;观察页面且未设置断言不代表验收通过。' }; } readResult(session, jobId, { section = 'page', offset = 0, limit, maximumMessageBytes = 16000, callId = '' } = {}) { const job = this.store.owned('browser_job', jobId, session.id); if (job.taskId !== session.taskId) throw browserError('模型只能读取当前Task的浏览器结果。'); const record = verifyBrowserJob(this.store, session, job); const sections = { page: record.pages.at(-1), steps: record.steps, console: { console: record.console, pageErrors: record.pageErrors }, requests: { requests: record.requests, failed: record.requestFailures, blocked: record.blockedRequests, policy: record.policyEvents }, overview: { status: record.status, assertions: record.assertions, error: record.error, inputValidation: record.inputValidation, cleanup: record.cleanup } }; if (!Object.hasOwn(sections, section)) throw browserError('请选择page、steps、console、requests或overview。', 400); const text = JSON.stringify(sections[section] ?? null, null, 2), metadata = { browser_job_id: job.id, task_id: job.taskId, section, source_artifact_id: job.resultArtifactId, source_sha256: job.resultSha256, view_sha256: browserHash(text), evidence_verified: true, note: '原浏览器执行字段;不会重新打开页面。' }; const reserve = Buffer.byteLength(JSON.stringify(metadata), 'utf8') + 600; const page = artifactPage({ id: job.resultArtifactId, sha256: browserHash(text), kind: 'browser-result-view' }, text, { offset, limit: limit ?? (maximumMessageBytes === Infinity ? text.length : 4000) }, { callId, maximumMessageBytes: maximumMessageBytes - reserve }); return { ...page, ...metadata }; } acknowledge(session, id, fingerprint) { const job = this.store.owned('browser_job', id, session.id); if (!job.requiresVerification || fingerprint !== job.planFingerprint || this.projectActive(job.projectId)) throw browserError('原浏览器核对请求已经变化。'); job.requiresVerification = false; job.acknowledgedAt = at(); job.acknowledgement = '用户核对中断原记录并允许准备新的检查;历史进程结束仍未知,未按历史PID停止进程或重放。'; this.store.save(session, { type: 'browser.acknowledged', detail: { jobId: job.id, taskId: job.taskId } }); return job; } async stop(sessionId, jobId = null) { const owned = jobId ? this.store.owned('browser_job', jobId, sessionId) : null; const values = [...this.active.entries()].filter(([id, value]) => value.sessionId === sessionId && (!owned || id === owned.id)).map(([, value]) => value); for (const active of values) active.controller.abort(); await Promise.allSettled(values.map(value => value.promise)); } async stopAll() { for (const active of this.active.values()) active.controller.abort(); await Promise.allSettled([...this.active.values()].map(value => value.promise)); } }