Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(browser): isolate web bundle analysis with bounded partial results
morluto9aca543f4608
diff --git a/docs/browser-observation.md b/docs/browser-observation.mdindex 4c9f5fc38..3ea8b5101 100644--- a/docs/browser-observation.md+++ b/docs/browser-observation.md@@ -350,6 +350,40 @@ validation and resource bounds. Omitted script metadata makes its affectedsection explicitly truncated.Disallowed-origin entries are filtered before retention.+Selected script-source collection shares a 32 MiB aggregate UTF-8 retention+budget and a 20-second deadline across the capture. An oversized source is+omitted while later smaller sources may still fit. When the deadline expires,+remaining source reads are skipped. Script metadata, per-item omission reasons,+and `script_sources` completeness remain available. A single CDP response can+still be materialized up to the separate 64 MiB transport limit before source+admission; the retention budget does not bound that transient allocation.++Bundle parsing and semantic inspection run sequentially in an owned child,+without executing captured code. `max_heap_mb` defaults to 1024 MiB V8+old-space; `analysis_timeout_ms` defaults to 30000 per script, including startup+and transfer. A failed or timed-out script becomes an explicit unknown while+completed findings and later scripts remain available. `total_analysis_timeout_ms`+defaults to 300000 across script analysis; expiry returns a typed timeout with+partial Evidence and identifies unstarted scripts. These controls are also+available as CLI flags with hyphenated names. Capture and optional source-map+fetching have separate budgets.++One web-bundle capture/analysis is admitted per REA process at a time. Completed+script results share an 8 MiB serialized transfer budget, with host heap+reservation checked before decoding and validating another result.+Exhausted result capacity stops further script launches and returns a typed+resource failure with completed facts and explicit unstarted-script unknowns.+Worker control frames are limited to 64 KiB. Cleanup must confirm child termination+before releasing its private files; failed cleanup retains its exact owner and+blocks replacement until retry succeeds. Cancellation retains completed bundle+facts, including cancellation during final cleanup.++The worker heap setting is not a process-family RSS limit. Node enforces V8+old-space flags; Bun ignores them. Windows Bun instead uses an owned process+commit limit with a 512 MiB runtime reserve; other Bun hosts have no enforced+memory limit. These bounds do not establish an aggregate host-memory limit+across other REA operations or external processes.+Resource-tree inventories distinguish a valid empty `resources` array from amissing or malformed collection. Invalid resource entries are omitted withincomplete coverage, while valid resources from that frame and other framesdiff --git a/docs/electron-observation.md b/docs/electron-observation.mdindex 391aa5c17..d0b07dd2f 100644--- a/docs/electron-observation.md+++ b/docs/electron-observation.md@@ -68,7 +68,12 @@ Script metadata retains its execution-context frame ID when CDP supplies one. Thinventories worker, service-worker, and shared-worker targets withvalidated opener-target and parent-frame IDs. Worker discovery uses passivetarget metadata; REA does not attach to or execute code in those targets.-Collection counts and aggregate script-source bytes are not capped. Like every+Script-source collection retains at most 32 MiB of UTF-8 text across scripts+and shares a 20-second collection deadline. Omitted sources retain their script+metadata and an explicit reason; later smaller sources may still fit after an+oversized source is omitted. The separate 64 MiB CDP response limit bounds one+wire message before retention admission, rather than total transient memory.+The source budget adds no script-count cap. Like everytarget, frame, script, and resource, a worker URL must resolve to a localfile before it is retained. Relationship IDs improveattribution but do not prove which static module started a worker or that itsdiff --git a/knip.json b/knip.jsonindex df594f3f0..acea26bd1 100644--- a/knip.json+++ b/knip.json@@ -4,6 +4,7 @@"src/main.ts","src/cli.ts","src/composition/javascriptAnalysisWorkerProcess.ts",+ "src/composition/webBundleAnalysisWorkerProcess.ts","src/contracts/errorSchemas.ts","src/evaluation/AgentEvaluationFixtures.ts","src/application/RealHopperAssertions.ts",diff --git a/package.json b/package.jsonindex 1e112fcb8..58c354e11 100644--- a/package.json+++ b/package.json@@ -35,7 +35,8 @@},"type": "module","imports": {- "#javascript-analysis-worker": "./dist/composition/javascriptAnalysisWorkerProcess.js"+ "#javascript-analysis-worker": "./dist/composition/javascriptAnalysisWorkerProcess.js",+ "#web-bundle-analysis-worker": "./dist/composition/webBundleAnalysisWorkerProcess.js"},"bin": {"rea": "scripts/rea.mjs",diff --git a/src/application/BrowserEvidence.ts b/src/application/BrowserEvidence.tsindex 495f1f197..b8d99186c 100644--- a/src/application/BrowserEvidence.ts+++ b/src/application/BrowserEvidence.ts@@ -160,7 +160,18 @@ const browserParameters = (}: {}),...("fetch_source_maps" in input- ? { fetch_source_maps: input.fetch_source_maps }+ ? {+ fetch_source_maps: input.fetch_source_maps,+ ...(input.max_heap_mb === undefined+ ? {}+ : { max_heap_mb: input.max_heap_mb }),+ ...(input.analysis_timeout_ms === undefined+ ? {}+ : { analysis_timeout_ms: input.analysis_timeout_ms }),+ ...(input.total_analysis_timeout_ms === undefined+ ? {}+ : { total_analysis_timeout_ms: input.total_analysis_timeout_ms }),+ }: {}),};};diff --git a/src/application/BrowserObservationService.test.ts b/src/application/BrowserObservationService.test.tsindex 213885c2f..20b40c10c 100644--- a/src/application/BrowserObservationService.test.ts+++ b/src/application/BrowserObservationService.test.ts@@ -137,8 +137,8 @@ it("retains captured page Evidence when bundle analysis fails after capture", as"cancelled",{ partialObservation: inspection },);- const browser = {- identity: () => ({ id: "browser-fixture", name: "Fixture", version: "1" }),+ const browser: BrowserObservationPort = {+ ...provider(async () => ok(report)),analyzeBundle: async () => ({ ok: false as const, error: failure }),} as unknown as BrowserObservationPort;const bundleInput = analyzeWebBundleInputSchema.parse({@@ -159,3 +159,41 @@ it("retains captured page Evidence when bundle analysis fails after capture", as});}});++it("retains completed bundle facts as bundle Evidence after cancellation", async () => {+ const { analyzeCapturedWebBundle } =+ await import("../domain/webBundleAnalyzer.js");+ const { AnalysisCancelledError } =+ await import("../domain/analysisErrorCore.js");+ const bundle = analyzeCapturedWebBundle(passiveNetworkCapture());+ const reason = { requested: "stop after completed script" };+ const failure = new AnalysisCancelledError("analyze_web_bundle", {+ cause: reason,+ partialObservation: bundle,+ });+ const browser: BrowserObservationPort = {+ ...provider(async () => ok(report)),+ analyzeBundle: async () => ({ ok: false as const, error: failure }),+ };+ const selected = analyzeWebBundleInputSchema.parse({+ cdp_endpoint: input.cdp_endpoint.recorded,+ target_id: "page",+ max_heap_mb: 256,+ analysis_timeout_ms: 100,+ total_analysis_timeout_ms: 1000,+ });+ const result = await analyzeWebBundle(browser, selected);+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected cancellation");+ expect(result.error).toBe(failure);+ expect(result.error.cause).toBe(reason);+ expect(parseEvidence(result.error.partialObservation)).toMatchObject({+ operation: "analyze_web_bundle",+ parameters: expect.objectContaining({+ max_heap_mb: 256,+ analysis_timeout_ms: 100,+ total_analysis_timeout_ms: 1000,+ }),+ normalized_result: bundle,+ });+});diff --git a/src/application/BrowserObservationService.ts b/src/application/BrowserObservationService.tsindex 53f44360a..0c1f2a036 100644--- a/src/application/BrowserObservationService.ts+++ b/src/application/BrowserObservationService.ts@@ -3,7 +3,10 @@ import type {InspectWebPageInput,ListBrowserTargetsInput,} from "../domain/browserObservation.js";-import type { AnalyzeWebBundleInput } from "../domain/webBundleAnalysis.js";+import {+ webBundleAnalysisSchema,+ type AnalyzeWebBundleInput,+} from "../domain/webBundleAnalysis.js";import type { ObserveWebSessionInput } from "../domain/browserSession.js";import type { DiscoverWebMcpToolsInput } from "../domain/webMcpDiscovery.js";import type { BrowserCaptureComparisonInput } from "../domain/browserCaptureComparison.js";@@ -24,6 +27,7 @@ import { createBrowserEvidence } from "./BrowserEvidence.js";import { jsonValueSchema } from "../domain/jsonValue.js";import { completeProviderEvidence } from "./ProviderOperationExecution.js";import { webPageInspectionSchema } from "../domain/browserObservationSchemas.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";/** List browser targets within the endpoint and origin scope in the request. */export const listBrowserTargets = async (@@ -59,7 +63,7 @@ export const inspectWebPage = async (return err(new AnalysisCancelledError("inspect_web_page"));const result = await ready.value.inspectPage(input, options);if (!result.ok)- return retainPageInspection(+ return retainBrowserObservation(result.error,input,ready.value,@@ -88,7 +92,7 @@ export const analyzeWebBundle = async (return err(new AnalysisCancelledError("analyze_web_bundle"));const analyzed = await ready.value.analyzeBundle(input, options);if (!analyzed.ok)- return retainPageInspection(+ return retainBrowserObservation(analyzed.error,input,ready.value,@@ -247,14 +251,46 @@ const browserEvidence = ();};-/** Convert a provider-retained page capture without claiming bundle analysis completed. */-const retainPageInspection = (+/** Retain the completed capture or bundle facts under their actual operation. */+const retainBrowserObservation = (error: AnalysisError,input: InspectWebPageInput | AnalyzeWebBundleInput,provider: BrowserObservationPort,errorOperation: "inspect_web_page" | "analyze_web_bundle",): Result<Evidence, AnalysisError> => {const partial = error.partialObservation;+ if (+ errorOperation === "analyze_web_bundle" &&+ partial !== undefined &&+ !("evidence_id" in partial) &&+ "observations" in partial &&+ "capture" in partial+ ) {+ const bundle = webBundleAnalysisSchema.safeParse(partial);+ if (!bundle.success) {+ const malformed = new AnalysisOutputError(+ errorOperation,+ "Browser provider retained malformed completed bundle facts.",+ { cause: bundle.error },+ );+ return err(+ error.cleanupIncomplete+ ? analysisErrorWithCleanupFailure(+ malformed,+ error,+ errorOperation,+ ).bindCleanupDependencies([malformed, error])+ : malformed,+ );+ }+ error.partialObservation = createBrowserEvidence(+ "analyze_web_bundle",+ input,+ bundle.data,+ provider.identity(),+ );+ return err(error);+ }if (partial === undefined ||"evidence_id" in partial ||diff --git a/src/browser/CdpBrowserProvider.ts b/src/browser/CdpBrowserProvider.tsindex 2137d4348..3557a427d 100644--- a/src/browser/CdpBrowserProvider.ts+++ b/src/browser/CdpBrowserProvider.ts@@ -12,11 +12,10 @@ import {type BrowserTargetList,type WebPageInspection,} from "../domain/browserObservationSchemas.js";-import { analyzeCapturedWebBundle } from "../domain/webBundleAnalyzer.js";-import {- webBundleAnalysisSchema,- type AnalyzeWebBundleInput,- type WebBundleAnalysis,+import { IsolatedWebBundleAnalyzer } from "./IsolatedWebBundleAnalyzer.js";+import type {+ AnalyzeWebBundleInput,+ WebBundleAnalysis,} from "../domain/webBundleAnalysis.js";import {webObservationSessionSchema,@@ -93,9 +92,31 @@ const CLEANUP_DOMAINS = [/** Passive browser observation through a selected user-owned CDP endpoint. */export class CdpBrowserProvider implements BrowserObservationPort {readonly #owner = new CdpTargetSessionOwner();+ readonly #bundleAnalyzer = new IsolatedWebBundleAnalyzer();- close(): Promise<void> {- return this.#owner.close();+ async close(): Promise<void> {+ const outcomes = await Promise.allSettled([+ this.#owner.close(),+ this.#bundleAnalyzer.close(),+ ]);+ const failures = outcomes.flatMap((outcome) =>+ outcome.status === "rejected" ? [outcome.reason as unknown] : [],+ );+ if (failures.length === 1) throw failures[0];+ if (failures.length > 1) {+ const typed = failures.filter(+ (failure): failure is AnalysisError => failure instanceof AnalysisError,+ );+ throw new ProviderCleanupError(+ CDP_BROWSER_PROVIDER_IDENTITY.id,+ typed.flatMap((failure) => failure.cleanupResources),+ { reason: "Browser transport and analyzer cleanup remain incomplete" },+ {+ operation: "analyze_web_bundle",+ cause: new AggregateError(failures),+ },+ ).bindCleanupDependencies(typed);+ }}identity(): ProviderIdentity {@@ -166,6 +187,8 @@ export class CdpBrowserProvider implements BrowserObservationPort {input: AnalyzeWebBundleInput,options: ExecutionOptions = {},): Promise<Result<WebBundleAnalysis, AnalysisError>> {+ const admission = await this.#bundleAnalyzer.reserve();+ if (!admission.ok) return admission;let captured: CapturedPage | undefined;try {captured = await this.#capture(input, options, "analyze_web_bundle");@@ -182,10 +205,16 @@ export class CdpBrowserProvider implements BrowserObservationPort {options.signal,): undefined;- return ok(- webBundleAnalysisSchema.parse(- analyzeCapturedWebBundle(captured.inspection, sourceMaps),- ),+ return await this.#bundleAnalyzer.analyze(+ captured.inspection,+ sourceMaps ?? {+ status: "not_requested",+ requested: 0,+ processed: 0,+ items: [],+ },+ input,+ options.signal,);} catch (cause: unknown) {// fetchWebSourceMaps rethrows the exact abort reason. Preserve cancellation@@ -201,6 +230,8 @@ export class CdpBrowserProvider implements BrowserObservationPort {);}return err(providerError(cause, "analyze_web_bundle", options.signal));+ } finally {+ this.#bundleAnalyzer.releaseReservation();}}diff --git a/src/browser/CdpElectronInspection.test.ts b/src/browser/CdpElectronInspection.test.tsindex 018d15ec7..dcd77f008 100644--- a/src/browser/CdpElectronInspection.test.ts+++ b/src/browser/CdpElectronInspection.test.ts@@ -159,3 +159,75 @@ describe("Electron frame capture", () => {});});});++it("admits a prefix and fitting suffix around an oversized Electron source", async () => {+ const root = await mkdtemp(join(tmpdir(), "rea-electron-source-budget-"));+ temporary.push(root);+ const paths = await Promise.all(+ ["prefix.js", "oversized.js", "suffix.js"].map(async (name) => {+ const path = join(root, name);+ await writeFile(path, "metadata");+ return path;+ }),+ );+ const sourceById = {+ prefix: "p".repeat(16 * 1024 * 1024),+ oversized: "o".repeat(17 * 1024 * 1024),+ suffix: "s".repeat(1024 * 1024),+ };+ const scripts: ElectronScriptDraft[] = paths.map((path, index) => {+ const scriptId = ["prefix", "oversized", "suffix"][index];+ if (scriptId === undefined) throw new Error("Missing script identity");+ return {+ scriptId,+ rawUrl: pathToFileURL(path).href,+ hash: scriptId,+ length: null,+ isModule: false,+ language: "JavaScript",+ frameId: null,+ };+ });+ const completeness = new CdpCaptureCompleteness();+ const capture = await captureElectronScripts({+ connection: {+ send: async (+ _method: string,+ params: Readonly<Record<string, unknown>>,+ ) => ({+ scriptSource:+ sourceById[+ (params as { scriptId: keyof typeof sourceById }).scriptId+ ],+ }),+ } as unknown as CdpConnection,+ sessionId: undefined,+ request: inspectElectronPageInputSchema.parse({+ cdp_endpoint: "http://127.0.0.1:9222",+ target_id: "page-1",+ observation_ms: 0,+ include_script_sources: true,+ }),+ scripts,+ frameIds: new Set(),+ completeness,+ });+ const byHash = new Map(+ capture.items.map((item) => [item.cdp_hash, item.source]),+ );++ expect(capture.total).toBe(3);+ expect([...byHash.keys()].sort()).toEqual(["oversized", "prefix", "suffix"]);+ expect(byHash.get("prefix")?.included).toBe(true);+ expect(byHash.get("oversized")).toEqual({+ included: false,+ reason:+ "script source was omitted because the aggregate 32 MiB source budget was exhausted",+ });+ expect(byHash.get("suffix")?.included).toBe(true);+ expect(completeness.snapshot().excluded).toContainEqual({+ section: "script_sources",+ reason: "resource_budget_exhausted",+ count: 1,+ });+});diff --git a/src/browser/CdpElectronScripts.ts b/src/browser/CdpElectronScripts.tsindex ae1d24586..d648bc0c1 100644--- a/src/browser/CdpElectronScripts.ts+++ b/src/browser/CdpElectronScripts.ts@@ -10,6 +10,12 @@ import { requiredScriptSource } from "./CdpCaptureValues.js";import type { ElectronScriptDraft } from "./CdpElectronScriptEvents.js";import { authorizedElectronFile } from "./ElectronFileScope.js";import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import {+ CDP_SCRIPT_SOURCE_BYTES_OMISSION_REASON,+ CDP_SCRIPT_SOURCE_DEADLINE_OMISSION_REASON,+ CdpScriptSourceBudget,+} from "./CdpScriptSourceBudget.js";interface ElectronScriptCaptureInput {readonly connection: CdpConnection;@@ -28,33 +34,65 @@ export const captureElectronScripts = async (let total = 0;const items: ElectronPageInspection["scripts"]["items"] = [];const seen = new Set<string>();- for (const script of input.scripts) {- const path = await authorizedElectronFile(script.rawUrl);- if (path === undefined) {- input.completeness.exclude("scripts", "out_of_target_scope");- continue;+ const sourceBudget =+ input.request.include_script_sources && input.scripts.length > 0+ ? new CdpScriptSourceBudget(input.signal)+ : undefined;+ try {+ for (const script of input.scripts) {+ const path = await authorizedElectronFile(script.rawUrl);+ if (path === undefined) {+ input.completeness.exclude("scripts", "out_of_target_scope");+ continue;+ }+ const identity = {+ frame_id:+ script.frameId !== null && input.frameIds.has(script.frameId)+ ? script.frameId+ : null,+ file_path: path,+ cdp_hash: script.hash,+ length: script.length,+ is_module: script.isModule,+ language: script.language,+ };+ const scriptKey = `electron_script_${digestCanonicalValue(identity, "CDP capture")}`;+ if (seen.has(scriptKey)) continue;+ seen.add(scriptKey);+ total += 1;+ let source: ElectronScriptSource = input.request.include_script_sources+ ? {+ included: false,+ reason: CDP_SCRIPT_SOURCE_DEADLINE_OMISSION_REASON,+ }+ : {+ included: false,+ reason: "source capture was not selected",+ };+ if (+ input.request.include_script_sources &&+ isSourceDeadlineExpired(sourceBudget)+ ) {+ excludeScriptSource(input.completeness);+ } else if (+ input.request.include_script_sources &&+ sourceBudget !== undefined+ ) {+ try {+ source = await captureScriptSource(input, script, sourceBudget);+ } catch (cause: unknown) {+ throwIfCallerCancelled(input.signal);+ if (isSourceDeadlineExpired(sourceBudget)) {+ excludeScriptSource(input.completeness);+ } else {+ throw cause;+ }+ }+ }+ items.push({ script_key: scriptKey, ...identity, source });}- const identity = {- frame_id:- script.frameId !== null && input.frameIds.has(script.frameId)- ? script.frameId- : null,- file_path: path,- cdp_hash: script.hash,- length: script.length,- is_module: script.isModule,- language: script.language,- };- const scriptKey = `electron_script_${digestCanonicalValue(identity, "CDP capture")}`;- if (seen.has(scriptKey)) continue;- seen.add(scriptKey);- total += 1;- const capturedSource = await captureScriptSource(input, script);- items.push({- script_key: scriptKey,- ...identity,- source: capturedSource.source,- });+ } finally {+ sourceBudget?.dispose();}if (!input.request.include_script_sources)input.completeness.exclude("script_sources", "not_approved", total);@@ -72,29 +110,44 @@ type ElectronScriptSource =const captureScriptSource = async (input: ElectronScriptCaptureInput,script: ElectronScriptDraft,-): Promise<{- readonly source: ElectronScriptSource;-}> => {- if (!input.request.include_script_sources)+ sourceBudget: CdpScriptSourceBudget,+): Promise<ElectronScriptSource> => {+ const response = await input.connection.send(+ "Debugger.getScriptSource",+ { scriptId: script.scriptId },+ input.sessionId,+ sourceBudget.signal,+ );+ throwIfCallerCancelled(input.signal);+ const text = requiredScriptSource(response, "inspect_electron_page");+ if (sourceBudget.timedOut) {+ excludeScriptSource(input.completeness);return {- source: {- included: false,- reason: "source capture was not selected",- },+ included: false,+ reason: CDP_SCRIPT_SOURCE_DEADLINE_OMISSION_REASON,};- const text = requiredScriptSource(- await input.connection.send(- "Debugger.getScriptSource",- { scriptId: script.scriptId },- input.sessionId,- input.signal,- ),- "inspect_electron_page",- );+ }+ if (!sourceBudget.admit(text)) {+ excludeScriptSource(input.completeness);+ return { included: false, reason: CDP_SCRIPT_SOURCE_BYTES_OMISSION_REASON };+ }return {- source: {- included: true,- artifact: createWebTextArtifact(text, "text/javascript"),- },+ included: true,+ artifact: createWebTextArtifact(text, "text/javascript"),};};++const excludeScriptSource = (completeness: CdpCaptureCompleteness): void => {+ completeness.exclude("script_sources", "resource_budget_exhausted");+};++const throwIfCallerCancelled = (signal: AbortSignal | undefined): void => {+ if (signal?.aborted === true)+ throw new AnalysisCancelledError("inspect_electron_page", {+ cause: signal.reason,+ });+};++const isSourceDeadlineExpired = (+ sourceBudget: CdpScriptSourceBudget | undefined,+): boolean => sourceBudget?.timedOut === true;diff --git a/src/browser/CdpPageCaptureScripts.test.ts b/src/browser/CdpPageCaptureScripts.test.tsnew file mode 100644index 000000000..f591041fc--- /dev/null+++ b/src/browser/CdpPageCaptureScripts.test.ts@@ -0,0 +1,209 @@+import { expect, it, vi } from "vitest";++import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import { inspectWebPageInputSchema } from "../domain/browserObservation.js";+import { CdpCaptureEvents } from "./CdpCaptureEvents.js";+import type { CdpConnection } from "./CdpConnection.js";+import { captureScripts } from "./CdpPageCaptureScripts.js";+import type { CaptureContext } from "./CdpPageCapture.js";+import type { CapturedScript } from "./CdpCaptureEventTypes.js";++const script = (scriptId: string): CapturedScript => ({+ scriptId,+ rawUrl: `https://example.test/${scriptId}.js`,+ url: `https://example.test/${scriptId}.js`,+ origin: "https://example.test",+ hash: scriptId,+ length: null,+ isModule: false,+ language: "JavaScript",+ sourceMapUrl: null,+ sourceMapRawUrl: null,+ executionContextKey: null,+ frameId: null,+});++const capture = async (+ sources: Readonly<Record<string, string>>,+ includeScriptSources = true,+ signal?: AbortSignal,+) => {+ const input = inspectWebPageInputSchema.parse({+ cdp_endpoint: "http://127.0.0.1:9222",+ target_id: "page-1",+ allowed_origins: ["https://example.test"],+ observation_ms: 0,+ include_script_sources: includeScriptSources,+ });+ const events = new CdpCaptureEvents(input, new Set(input.allowed_origins));+ for (const id of Object.keys(sources)) events.scripts.set(id, script(id));+ const send = vi.fn(async (method: string, params: unknown) => {+ if (method !== "Debugger.getScriptSource")+ throw new Error(`Unexpected CDP command: ${method}`);+ const scriptId = (params as { scriptId: string }).scriptId;+ return { scriptSource: sources[scriptId] };+ });+ const context = {+ connection: { send } as unknown as CdpConnection,+ sessionId: undefined,+ operation: "inspect_web_page",+ discovery: undefined,+ target: undefined,+ input,+ ...(signal === undefined ? {} : { signal }),+ } as unknown as CaptureContext;+ const result = await captureScripts({+ context,+ events,+ rawResources: [],+ resources: [],+ frameIds: new Set(),+ });+ return { result, events, send };+};++it("admits a prefix and fitting suffix around an oversized script source", async () => {+ const prefix = "p".repeat(16 * 1024 * 1024);+ const oversized = "o".repeat(17 * 1024 * 1024);+ const suffix = "s".repeat(1024 * 1024);+ const { result, events } = await capture({ prefix, oversized, suffix });+ const byId = new Map(+ result.inventory.items.map((item) => [item.cdp_hash, item.source]),+ );++ expect(byId.get("prefix")).toMatchObject({ included: true });+ expect(byId.get("oversized")).toEqual({+ included: false,+ reason:+ "script source was omitted because the aggregate 32 MiB source budget was exhausted",+ });+ expect(byId.get("suffix")).toMatchObject({ included: true });+ expect(events.completeness.snapshot().excluded).toContainEqual({+ section: "script_sources",+ reason: "resource_budget_exhausted",+ count: 1,+ });+});++it("preserves the caller cancellation reason when a source read is pending", async () => {+ const controller = new AbortController();+ const reason = new AnalysisCancelledError("inspect_web_page");+ const input = inspectWebPageInputSchema.parse({+ cdp_endpoint: "http://127.0.0.1:9222",+ target_id: "page-1",+ allowed_origins: ["https://example.test"],+ observation_ms: 0,+ include_script_sources: true,+ });+ const events = new CdpCaptureEvents(input, new Set(input.allowed_origins));+ events.scripts.set("first", script("first"));+ const context = {+ connection: {+ send: async () => {+ controller.abort(reason);+ throw new AnalysisCancelledError("inspect_web_page");+ },+ } as unknown as CdpConnection,+ sessionId: undefined,+ operation: "inspect_web_page",+ discovery: undefined,+ target: undefined,+ input,+ signal: controller.signal,+ } as unknown as CaptureContext;++ await expect(+ captureScripts({+ context,+ events,+ rawResources: [],+ resources: [],+ frameIds: new Set(),+ }),+ ).rejects.toMatchObject({ _tag: "AnalysisCancelledError", cause: reason });+});++it("stops source reads at the shared collection deadline and retains metadata", async () => {+ vi.useFakeTimers();+ try {+ const input = inspectWebPageInputSchema.parse({+ cdp_endpoint: "http://127.0.0.1:9222",+ target_id: "page-1",+ allowed_origins: ["https://example.test"],+ observation_ms: 0,+ include_script_sources: true,+ });+ const events = new CdpCaptureEvents(input, new Set(input.allowed_origins));+ events.scripts.set("first", script("first"));+ events.scripts.set("second", script("second"));+ const send = vi.fn(+ (+ _method: string,+ _params: unknown,+ _sessionId: string | undefined,+ signal?: AbortSignal,+ ) =>+ new Promise((_resolve, reject) => {+ signal?.addEventListener(+ "abort",+ () => reject(new AnalysisCancelledError("inspect_web_page")),+ { once: true },+ );+ }),+ );+ const context = {+ connection: { send } as unknown as CdpConnection,+ sessionId: undefined,+ operation: "inspect_web_page",+ discovery: undefined,+ target: undefined,+ input,+ } as unknown as CaptureContext;+ const pending = captureScripts({+ context,+ events,+ rawResources: [],+ resources: [],+ frameIds: new Set(),+ });++ await vi.advanceTimersByTimeAsync(20_000);+ const result = await pending;++ expect(send).toHaveBeenCalledTimes(1);+ expect(result.inventory.items.map((item) => item.source)).toEqual([+ {+ included: false,+ reason:+ "script source was omitted because the 20-second source collection deadline elapsed",+ },+ {+ included: false,+ reason:+ "script source was omitted because the 20-second source collection deadline elapsed",+ },+ ]);+ expect(events.completeness.snapshot().excluded).toContainEqual({+ section: "script_sources",+ reason: "resource_budget_exhausted",+ count: 2,+ });+ } finally {+ vi.useRealTimers();+ }+});++it("leaves source-off capture unchanged and does not issue source reads", async () => {+ const { result, events, send } = await capture({ first: "unused" }, false);++ expect(send).not.toHaveBeenCalled();+ expect(result.inventory.items[0]?.source).toEqual({+ included: false,+ reason: "source capture was not selected",+ });+ expect(events.completeness.snapshot().excluded).toContainEqual({+ section: "script_sources",+ reason: "not_approved",+ count: 1,+ });+});diff --git a/src/browser/CdpPageCaptureScripts.ts b/src/browser/CdpPageCaptureScripts.tsindex 6c20c7514..97348d22e 100644--- a/src/browser/CdpPageCaptureScripts.ts+++ b/src/browser/CdpPageCaptureScripts.ts@@ -14,6 +14,13 @@ import {import type { CaptureContext } from "./CdpPageCapture.js";import type { WebSourceMapRequest } from "./WebSourceMapFetcher.js";import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import type { BrowserObservationOperation } from "../domain/browserObservationErrors.js";+import {+ CDP_SCRIPT_SOURCE_BYTES_OMISSION_REASON,+ CDP_SCRIPT_SOURCE_DEADLINE_OMISSION_REASON,+ CdpScriptSourceBudget,+} from "./CdpScriptSourceBudget.js";export interface CapturedScripts {readonly inventory: WebPageInspection["scripts"];@@ -51,17 +58,54 @@ export const captureScripts = async (readonly item: ScriptDraftItem;readonly sourceMapRawUrl: string | null;}[] = [];- for (const script of events.scripts.values()) {- state ??= {- context,- events,- frameIds,- reconcileResource: createCapturedWebScriptReconciler(- rawResources,- resources,- ),- };- drafts.push(await buildScriptDraft(script, state));+ const scripts = [...events.scripts.values()];+ const sourceBudget =+ context.input.include_script_sources && scripts.length > 0+ ? new CdpScriptSourceBudget(context.signal)+ : undefined;+ try {+ for (const script of scripts) {+ state ??= {+ context,+ events,+ frameIds,+ reconcileResource: createCapturedWebScriptReconciler(+ rawResources,+ resources,+ ),+ };+ let source: WebPageInspection["scripts"]["items"][number]["source"] =+ context.input.include_script_sources+ ? sourceExcluded(CDP_SCRIPT_SOURCE_DEADLINE_OMISSION_REASON)+ : sourceExcluded("source capture was not selected");+ if (+ context.input.include_script_sources &&+ isSourceDeadlineExpired(sourceBudget)+ ) {+ events.completeness.exclude(+ "script_sources",+ "resource_budget_exhausted",+ );+ } else if (+ context.input.include_script_sources &&+ sourceBudget !== undefined+ ) {+ try {+ source = await captureScriptSource(script, state, sourceBudget);+ } catch (cause: unknown) {+ throwIfCallerCancelled(context.signal, context.operation);+ if (isSourceDeadlineExpired(sourceBudget))+ events.completeness.exclude(+ "script_sources",+ "resource_budget_exhausted",+ );+ else throw cause;+ }+ }+ drafts.push(buildScriptDraft(script, state, source));+ }+ } finally {+ sourceBudget?.dispose();}if (!context.input.include_script_sources)events.completeness.exclude(@@ -72,17 +116,14 @@ export const captureScripts = async (return keyAndBuildInventory(drafts, events.scripts.size);};-const buildScriptDraft = async (+const buildScriptDraft = (script: CapturedScript,state: ScriptDraftState,-): Promise<{+ source: WebPageInspection["scripts"]["items"][number]["source"],+): {readonly item: ScriptDraftItem;readonly sourceMapRawUrl: string | null;-}> => {- let source: WebPageInspection["scripts"]["items"][number]["source"] = state- .context.input.include_script_sources- ? await captureScriptSource(script, state)- : sourceExcluded("source capture was not selected");+} => {const inventoryScript = {frame_id: state.events.frameForScript(script, state.frameIds),url: script.url,@@ -109,20 +150,46 @@ const buildScriptDraft = async (const captureScriptSource = async (script: CapturedScript,state: ScriptDraftState,+ sourceBudget: CdpScriptSourceBudget,): Promise<WebPageInspection["scripts"]["items"][number]["source"]> => {const { context } = state;- const content = requiredScriptSource(- await context.connection.send(- "Debugger.getScriptSource",- { scriptId: script.scriptId },- context.sessionId,- context.signal,- ),- context.operation,+ const response = await context.connection.send(+ "Debugger.getScriptSource",+ { scriptId: script.scriptId },+ context.sessionId,+ sourceBudget.signal,);+ throwIfCallerCancelled(context.signal, context.operation);+ const content = requiredScriptSource(response, context.operation);+ if (sourceBudget.timedOut) {+ state.events.completeness.exclude(+ "script_sources",+ "resource_budget_exhausted",+ );+ return sourceExcluded(CDP_SCRIPT_SOURCE_DEADLINE_OMISSION_REASON);+ }+ if (!sourceBudget.admit(content)) {+ state.events.completeness.exclude(+ "script_sources",+ "resource_budget_exhausted",+ );+ return sourceExcluded(CDP_SCRIPT_SOURCE_BYTES_OMISSION_REASON);+ }return sourceResult(content);};+const throwIfCallerCancelled = (+ signal: AbortSignal | undefined,+ operation: BrowserObservationOperation,+): void => {+ if (signal?.aborted === true)+ throw new AnalysisCancelledError(operation, { cause: signal.reason });+};++const isSourceDeadlineExpired = (+ sourceBudget: CdpScriptSourceBudget | undefined,+): boolean => sourceBudget?.timedOut === true;+const keyAndBuildInventory = (drafts: readonly {readonly item: ScriptDraftItem;diff --git a/src/browser/CdpScriptSourceBudget.ts b/src/browser/CdpScriptSourceBudget.tsnew file mode 100644index 000000000..689f38ca6--- /dev/null+++ b/src/browser/CdpScriptSourceBudget.ts@@ -0,0 +1,41 @@+import { WEB_RUNTIME_LIMITS } from "../domain/webRuntime.js";+import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";++const MIB = 1024 * 1024;++export const CDP_SCRIPT_SOURCE_BYTES_OMISSION_REASON = `script source was omitted because the aggregate ${String(WEB_RUNTIME_LIMITS.sourceBytes / MIB)} MiB source budget was exhausted`;+export const CDP_SCRIPT_SOURCE_DEADLINE_OMISSION_REASON = `script source was omitted because the ${String(WEB_RUNTIME_LIMITS.commandTimeoutMs / 1000)}-second source collection deadline elapsed`;++/** Shared admission for source text retained from passive CDP script reads. */+export class CdpScriptSourceBudget {+ readonly #deadline: ProviderStartupDeadline;+ #retainedBytes = 0;++ constructor(signal?: AbortSignal) {+ this.#deadline = new ProviderStartupDeadline(+ WEB_RUNTIME_LIMITS.commandTimeoutMs,+ signal,+ );+ }++ get signal(): AbortSignal {+ return this.#deadline.signal;+ }++ get timedOut(): boolean {+ return this.#deadline.interruption === "timeout";+ }++ /** Admit exact UTF-8 source bytes before building or retaining its artifact. */+ admit(text: string): boolean {+ const bytes = Buffer.byteLength(text, "utf8");+ if (bytes > WEB_RUNTIME_LIMITS.sourceBytes - this.#retainedBytes)+ return false;+ this.#retainedBytes += bytes;+ return true;+ }++ dispose(): void {+ this.#deadline.dispose();+ }+}diff --git a/src/browser/IsolatedWebBundleAnalyzer.test.ts b/src/browser/IsolatedWebBundleAnalyzer.test.tsnew file mode 100644index 000000000..131f83975--- /dev/null+++ b/src/browser/IsolatedWebBundleAnalyzer.test.ts@@ -0,0 +1,479 @@+import { expect, it } from "vitest";++import { webPageInspectionSchema } from "../domain/browserObservationSchemas.js";+import {+ AnalysisCancelledError,+ AnalysisOutputError,+ AnalysisResourceConstraintError,+ AnalysisTimeoutError,+} from "../domain/analysisErrorCore.js";+import type {+ AnalyzeWebBundleInput,+ WebBundleAnalysis,+} from "../domain/webBundleAnalysis.js";+import { analyzeWebBundleInputSchema } from "../domain/webBundleAnalysis.js";+import { analyzeCapturedWebScript } from "../domain/webBundleAnalyzer.js";+import { createWebTextArtifact } from "../domain/webContentArtifact.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { err, ok } from "../domain/result.js";+import {+ IsolatedWebBundleAnalyzer,+ type WebBundleAnalysisWorkerPort,+} from "./IsolatedWebBundleAnalyzer.js";++const origin = "https://app.example.test";+const noSourceMaps: WebBundleAnalysis["observations"]["source_maps"] = {+ status: "not_requested",+ requested: 0,+ processed: 0,+ items: [],+};+const input: AnalyzeWebBundleInput = analyzeWebBundleInputSchema.parse({+ cdp_endpoint: "http://127.0.0.1:9222",+ target_id: "page-1",+ include_script_sources: true,+});++it("preserves completed prefix and suffix facts when one script times out", async () => {+ const captured = inspection([+ "import './prefix.js'; fetch('/prefix');",+ "function stalled() {}",+ "import './suffix.js'; fetch('/suffix');",+ ]);+ const calls: string[] = [];+ const analyzer = new IsolatedWebBundleAnalyzer(() => ({+ analyze: async (script) => {+ calls.push(script.script_key);+ if (calls.length === 2)+ return err({+ error: new AnalysisTimeoutError("analyze_web_bundle", 5),+ completed: null,+ });+ return ok(analyzeCapturedWebScript(script));+ },+ close: async () => {},+ }));+ expect((await analyzer.reserve()).ok).toBe(true);++ const result = await analyzer.analyze(captured, noSourceMaps, input);+ analyzer.releaseReservation();++ expect(calls).toEqual(+ captured.scripts.items.map(({ script_key }) => script_key),+ );+ expect(result.ok).toBe(true);+ if (!result.ok) throw result.error;+ expect(+ result.value.observations.chunks.edges.map(({ specifier }) => specifier),+ ).toEqual(["./prefix.js", "./suffix.js"]);+ expect(result.value.observations.endpoints.map(({ value }) => value)).toEqual(+ ["/prefix", "/suffix"],+ );+ expect(result.value.completeness).toMatchObject({+ status: "partial",+ parsed_scripts: 2,+ parse_failures: 0,+ });+ expect(result.value.unknowns).toContainEqual({+ dimension: "javascript_analysis",+ reason: expect.stringContaining("deadline"),+ affected_script_keys: [captured.scripts.items[1]?.script_key],+ });+});++it("marks the unstarted suffix when the aggregate deadline expires", async () => {+ const captured = inspection([+ "fetch('/prefix');",+ "fetch('/stalled');",+ "fetch('/not-started');",+ ]);+ const calls: string[] = [];+ const analyzer = new IsolatedWebBundleAnalyzer(() => ({+ analyze: async (script, _timeout, signal) => {+ calls.push(script.script_key);+ if (calls.length === 1) return ok(analyzeCapturedWebScript(script));+ await waitForAbort(signal);+ return err({+ error: new AnalysisTimeoutError("analyze_web_bundle", 50),+ completed: null,+ });+ },+ close: async () => {},+ }));+ expect((await analyzer.reserve()).ok).toBe(true);++ const result = await analyzer.analyze(captured, noSourceMaps, {+ ...input,+ total_analysis_timeout_ms: 50,+ });++ analyzer.releaseReservation();++ expect(calls).toEqual(+ captured.scripts.items.slice(0, 2).map(({ script_key }) => script_key),+ );+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected total deadline failure");+ expect(result.error._tag).toBe("AnalysisTimeoutError");+ expect(result.error.partialObservation).toMatchObject({+ completeness: { status: "partial", parsed_scripts: 1 },+ observations: { endpoints: [{ value: "/prefix" }] },+ });+ expect(result.error.partialObservation).toMatchObject({+ unknowns: expect.arrayContaining([+ expect.objectContaining({+ dimension: "javascript_analysis",+ affected_script_keys: [captured.scripts.items[1]?.script_key],+ }),+ expect.objectContaining({+ dimension: "javascript_analysis",+ affected_script_keys: [captured.scripts.items[2]?.script_key],+ }),+ ]),+ });+});++it("stops after a middle-script result-capacity failure and retains prefix facts", async () => {+ const captured = inspection([+ "import './prefix.js'; fetch('/prefix');",+ "fetch('/capacity-blocked');",+ "fetch('/must-not-start');",+ ]);+ const calls: string[] = [];+ const caller = new AbortController();+ const primary = new AnalysisResourceConstraintError(+ "analyze_web_bundle",+ "memory",+ "No result capacity remains",+ { result_bytes: 0 },+ );+ const analyzer = new IsolatedWebBundleAnalyzer(() => ({+ analyze: async (script) => {+ calls.push(script.script_key);+ if (calls.length === 1) return ok(analyzeCapturedWebScript(script));+ return err({+ error: primary,+ completed: null,+ continuation: "result_capacity_exhausted",+ });+ },+ close: async () => {+ caller.abort(new Error("later cancellation during final close"));+ },+ }));+ expect((await analyzer.reserve()).ok).toBe(true);++ const result = await analyzer.analyze(+ captured,+ noSourceMaps,+ input,+ caller.signal,+ );+ analyzer.releaseReservation();++ expect(calls).toEqual(+ captured.scripts.items.slice(0, 2).map(({ script_key }) => script_key),+ );+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected result-capacity failure");+ expect(result.error).toBe(primary);+ expect(result.error.partialObservation).toMatchObject({+ completeness: { status: "partial", parsed_scripts: 1 },+ observations: {+ chunks: { edges: [{ specifier: "./prefix.js" }] },+ endpoints: [{ value: "/prefix" }],+ },+ unknowns: expect.arrayContaining([+ expect.objectContaining({+ dimension: "javascript_analysis",+ affected_script_keys: [captured.scripts.items[1]?.script_key],+ }),+ expect.objectContaining({+ dimension: "javascript_analysis",+ affected_script_keys: [captured.scripts.items[2]?.script_key],+ }),+ ]),+ });+});++it("carries the exact caller cancellation reason and completed prefix facts", async () => {+ const captured = inspection([+ "fetch('/prefix');",+ "fetch('/cancelled');",+ "fetch('/cancelled-suffix');",+ ]);+ const started = deferred<void>();+ const controller = new AbortController();+ const analyzer = new IsolatedWebBundleAnalyzer(() => ({+ analyze: async (script, _timeout, signal) => {+ if (script.script_key === captured.scripts.items[0]?.script_key)+ return ok(analyzeCapturedWebScript(script));+ started.resolve();+ await waitForAbort(signal);+ return err({+ error: new AnalysisCancelledError("analyze_web_bundle", {+ cause: signal?.reason,+ }),+ completed: null,+ });+ },+ close: async () => {},+ }));+ expect((await analyzer.reserve()).ok).toBe(true);+ const exactReason = new Error("caller stopped analysis");+ const pending = analyzer.analyze(+ captured,+ noSourceMaps,+ input,+ controller.signal,+ );+ await started.promise;+ controller.abort(exactReason);+ const result = await pending;+ analyzer.releaseReservation();++ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected cancellation");+ expect(result.error._tag).toBe("AnalysisCancelledError");+ expect(result.error.cause).toBe(exactReason);+ expect(result.error.partialObservation).toMatchObject({+ completeness: { status: "partial", parsed_scripts: 1 },+ observations: { endpoints: [{ value: "/prefix" }] },+ unknowns: expect.arrayContaining([+ expect.objectContaining({+ dimension: "javascript_analysis",+ affected_script_keys: [captured.scripts.items[1]?.script_key],+ }),+ expect.objectContaining({+ dimension: "javascript_analysis",+ affected_script_keys: [captured.scripts.items[2]?.script_key],+ }),+ ]),+ });+});++it("retains all completed facts when cancellation arrives during worker close", async () => {+ const captured = inspection(["fetch('/one');", "fetch('/two');"]);+ const closeStarted = deferred<void>();+ let closeWorker: (() => void) | undefined;+ const analyzer = new IsolatedWebBundleAnalyzer(() => ({+ analyze: async (script) => ok(analyzeCapturedWebScript(script)),+ close: async () => {+ closeStarted.resolve();+ await new Promise<void>((resolve) => {+ closeWorker = resolve;+ });+ },+ }));+ expect((await analyzer.reserve()).ok).toBe(true);+ const pending = analyzer.analyze(captured, noSourceMaps, input);+ await closeStarted.promise;+ const closing = analyzer.close();+ closeWorker?.();+ await closing;+ const result = await pending;+ analyzer.releaseReservation();++ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected cancellation during finalization");+ expect(result.error._tag).toBe("AnalysisCancelledError");+ expect(result.error.partialObservation).toMatchObject({+ completeness: { status: "complete", parsed_scripts: 2 },+ observations: { endpoints: [{ value: "/one" }, { value: "/two" }] },+ });+});++it("retains cleanup ownership after mixed worker/close failure and resolves it on retry", async () => {+ const captured = inspection(["fetch('/partial');"]);+ const primary = new ProviderCleanupError(+ "web-bundle-static-analysis",+ ["worker-job"],+ { reason: "analysis cleanup pending" },+ { operation: "analyze_web_bundle" },+ );+ const closeFailure = new ProviderCleanupError(+ "web-bundle-static-analysis",+ ["worker-root"],+ { reason: "worker close pending" },+ { operation: "analyze_web_bundle" },+ );+ let closeAttempts = 0;+ const analyzer = new IsolatedWebBundleAnalyzer(() => ({+ analyze: async () => err({ error: primary, completed: null }),+ close: async () => {+ closeAttempts += 1;+ if (closeAttempts <= 2) throw closeFailure;+ closeFailure.resolveCleanup();+ primary.resolveCleanup();+ },+ }));+ expect((await analyzer.reserve()).ok).toBe(true);++ const result = await analyzer.analyze(captured, noSourceMaps, input);+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected mixed failure");+ expect(result.error.cleanupIncomplete).toBe(true);+ expect(result.error.cleanupPrimary).toBe(primary);+ expect(result.error.cleanupResources).toEqual(["worker-job", "worker-root"]);+ expect(result.error.partialObservation).toMatchObject({+ completeness: { status: "partial", parsed_scripts: 0 },+ });++ const replacement = new IsolatedWebBundleAnalyzer(() => inertWorker());+ analyzer.releaseReservation();+ const blocked = await replacement.reserve();+ expect(blocked.ok).toBe(false);++ await analyzer.close();+ expect(closeAttempts).toBe(3);+ expect(result.error.cleanupIncomplete).toBe(false);+ expect(result.error.cleanupResources).toEqual([]);+ expect((await replacement.reserve()).ok).toBe(true);+ replacement.releaseReservation();+});++it("enforces one process-wide capture reservation across controller instances", async () => {+ const first = new IsolatedWebBundleAnalyzer(() => inertWorker());+ const second = new IsolatedWebBundleAnalyzer(() => inertWorker());+ expect((await first.reserve()).ok).toBe(true);+ const blocked = await second.reserve();+ expect(blocked.ok).toBe(false);+ if (blocked.ok) throw new Error("Expected process-wide admission refusal");+ expect(blocked.error._tag).toBe("AnalysisResourceConstraintError");+ first.releaseReservation();+ expect((await second.reserve()).ok).toBe(true);+ second.releaseReservation();+});++const inertWorker = (): WebBundleAnalysisWorkerPort => ({+ analyze: async () =>+ err({+ error: new AnalysisOutputError("analyze_web_bundle", "unused"),+ completed: null,+ }),+ close: async () => {},+});++const waitForAbort = (signal: AbortSignal | undefined): Promise<void> => {+ if (signal?.aborted) return Promise.resolve();+ return new Promise((resolve) => {+ signal?.addEventListener("abort", () => resolve(), { once: true });+ });+};++const deferred = <T>(): {+ promise: Promise<T>;+ resolve: (value: T) => void;+} => {+ let resolve!: (value: T) => void;+ const promise = new Promise<T>((done) => {+ resolve = done;+ });+ return { promise, resolve };+};++const inspection = (sources: readonly string[]) =>+ webPageInspectionSchema.parse({+ browser: {+ product: "Fake Chrome",+ protocol_version: "1.3",+ revision: "1",+ user_agent: "fake",+ js_version: "1",+ },+ target: {+ target_id: "page-1",+ type: "page",+ title: "App",+ url: `${origin}/app`,+ origin,+ attached: false,+ },+ capture_window: {+ started_at: "2026-07-14T00:00:00.000Z",+ ended_at: "2026-07-14T00:00:01.000Z",+ observation_ms: 1_000,+ },+ completeness: {+ status: "attach_limited",+ conditions: ["attach_limited"],+ policy_filtered_sections: [],+ attach_limited_sections: ["network_requests"],+ truncated_sections: [],+ unavailable_sections: [],+ excluded: [],+ dropped_events: {+ scripts: 0,+ network_requests: 0,+ console_events: 0,+ websocket_connections: 0,+ websocket_frames: 0,+ webmcp_tools: 0,+ timeline_events: 0,+ total: 0,+ },+ },+ frames: [],+ dom: { total_nodes: 0, nodes: [] },+ accessibility: {+ total_nodes: 0,+ text_capture: {+ status: "not_approved",+ retained_bytes: 0,+ excluded_fields: 0,+ },+ nodes: [],+ },+ scripts: {+ total: sources.length,+ items: sources.map((source, index) => ({+ script_key: `scr_${String(index + 1).repeat(64)}`,+ url: `${origin}/assets/${String(index)}.js`,+ origin,+ cdp_hash: `hash-${String(index)}`,+ length: Buffer.byteLength(source),+ is_module: true,+ language: "JavaScript",+ source_map_url: null,+ resource_reconciliation: {+ status: "unmatched",+ reason: "no_exact_sanitized_url",+ },+ source: {+ included: true,+ artifact: createWebTextArtifact(source, "text/javascript"),+ },+ })),+ },+ resources: [],+ network: {+ requests: [],+ websocket_connections: [],+ coverage_started_at: "2026-07-14T00:00:00.000Z",+ prior_activity_available: false,+ },+ console: {+ events: [],+ coverage_started_at: "2026-07-14T00:00:00.000Z",+ prior_activity_available: false,+ },+ workers: [],+ metadata: {+ responses: [],+ dom_urls: [],+ agent_hints: [],+ excluded_dom_urls: 0,+ headers_allowlisted: true,+ },+ storage: {+ origin,+ usage_bytes: null,+ quota_bytes: null,+ local_storage_keys: [],+ session_storage_keys: [],+ indexed_db_names: [],+ cache_names: [],+ values_redacted: true,+ },+ limitations: [],+ });diff --git a/src/browser/IsolatedWebBundleAnalyzer.ts b/src/browser/IsolatedWebBundleAnalyzer.tsnew file mode 100644index 000000000..ee77e3684--- /dev/null+++ b/src/browser/IsolatedWebBundleAnalyzer.ts@@ -0,0 +1,336 @@+import type { WebPageInspection } from "../domain/browserObservationSchemas.js";+import type {+ AnalyzeWebBundleInput,+ WebBundleAnalysis,+} from "../domain/webBundleAnalysis.js";+import { buildCapturedWebBundleAnalysis } from "../domain/webBundleAnalyzerResult.js";+import { isIncludedScript } from "../domain/webBundleAnalyzerInspection.js";+import type { WebBundleScriptAnalysis } from "../domain/webBundleScriptAnalysis.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisCapabilityUnavailableError,+ AnalysisCancelledError,+ AnalysisTimeoutError,+ AnalysisResourceConstraintError,+ AnalysisOutputError,+} from "../domain/analysisErrorCore.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { err, ok, type Result } from "../domain/result.js";+import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";+import { WebBundleAnalysisWorker } from "./WebBundleAnalysisWorker.js";+import { WEB_BUNDLE_WORKER_LIMITS } from "./WebBundleAnalysisWorkerProtocol.js";++// A process-wide admission, rather than one permit per provider instance, bounds+// simultaneous web analyzer children and their source/result transfer reservations.+export type WebBundleAnalysisWorkerPort = Pick<+ WebBundleAnalysisWorker,+ "analyze" | "close"+>;++let activeAnalyzer: IsolatedWebBundleAnalyzer | undefined;++/** Own one bundle's sequential analysis and finalization through provider close. */+export class IsolatedWebBundleAnalyzer {+ static readonly #pendingCleanup = new Set<IsolatedWebBundleAnalyzer>();+ #closed = false;+ #running: Promise<Result<WebBundleAnalysis, AnalysisError>> | undefined;+ #controller: AbortController | undefined;+ #worker: WebBundleAnalysisWorkerPort | undefined;++ constructor(+ readonly createWorker: (heapMb: number) => WebBundleAnalysisWorkerPort = (+ heapMb,+ ) => new WebBundleAnalysisWorker(heapMb),+ ) {}++ /** Reserve capacity before capture, so concurrent captures cannot retain source inventories. */+ async reserve(): Promise<Result<void, AnalysisError>> {+ if (this.#closed)+ return err(new AnalysisCancelledError("analyze_web_bundle"));+ if (activeAnalyzer !== undefined)+ return err(+ new AnalysisResourceConstraintError(+ "analyze_web_bundle",+ "capacity",+ "Another web-bundle capture or analysis owns the process-wide source and result reservation",+ { concurrent_web_bundle_analyses: 1 },+ ),+ );+ // Retry exact earlier owners before a replacement capture can retain sources.+ try {+ for (const owner of [...IsolatedWebBundleAnalyzer.#pendingCleanup])+ await owner.#releaseWorker();+ await WebBundleAnalysisWorker.retryPending();+ await this.#releaseWorker();+ } catch (cause) {+ return err(+ cause instanceof AnalysisError+ ? cause+ : new ProviderCleanupError(+ "web-bundle-static-analysis",+ [],+ { reason: "Earlier web analyzer cleanup remains incomplete" },+ { operation: "analyze_web_bundle", cause },+ ),+ );+ }+ if (this.#closed)+ return err(new AnalysisCancelledError("analyze_web_bundle"));+ if (activeAnalyzer !== undefined)+ return err(+ new AnalysisResourceConstraintError(+ "analyze_web_bundle",+ "capacity",+ "Another web-bundle capture or analysis owns the process-wide source and result reservation",+ { concurrent_web_bundle_analyses: 1 },+ ),+ );+ activeAnalyzer = this;+ return ok(undefined);+ }++ releaseReservation(): void {+ if (activeAnalyzer === this) activeAnalyzer = undefined;+ }++ analyze(+ inspection: WebPageInspection,+ sourceMaps: WebBundleAnalysis["observations"]["source_maps"],+ input: AnalyzeWebBundleInput,+ signal?: AbortSignal,+ ): Promise<Result<WebBundleAnalysis, AnalysisError>> {+ if (this.#closed)+ return Promise.resolve(+ err(+ new AnalysisCancelledError("analyze_web_bundle", {+ partialObservation: inspection,+ }),+ ),+ );+ if (this.#running !== undefined)+ return Promise.resolve(+ err(+ new AnalysisResourceConstraintError(+ "analyze_web_bundle",+ "capacity",+ "This web analyzer already owns an active analysis",+ { concurrent_web_bundle_analyses: 1 },+ ),+ ),+ );+ this.#controller = new AbortController();+ const running = this.#analyze(+ inspection,+ sourceMaps,+ input,+ signal,+ ).finally(() => {+ this.#running = undefined;+ this.#controller = undefined;+ });+ this.#running = running;+ return running;+ }++ async #analyze(+ inspection: WebPageInspection,+ sourceMaps: WebBundleAnalysis["observations"]["source_maps"],+ input: AnalyzeWebBundleInput,+ signal?: AbortSignal,+ ): Promise<Result<WebBundleAnalysis, AnalysisError>> {+ const scripts = inspection.scripts.items.filter(isIncludedScript);+ const results: WebBundleScriptAnalysis[] = [];+ const signals = [+ this.#controller!.signal,+ ...(signal === undefined ? [] : [signal]),+ ];+ const caller = AbortSignal.any(signals);+ const deadline = new ProviderStartupDeadline(+ input.total_analysis_timeout_ms ??+ WEB_BUNDLE_WORKER_LIMITS.totalTimeoutMs,+ caller,+ );+ let failure: AnalysisError | undefined;+ let resultCapacityExhausted = false;+ const appendUnstarted = (): void => {+ for (const script of scripts.slice(results.length))+ results.push({+ status: "unavailable",+ script_key: script.script_key,+ reason: "not_started",+ detail: caller.aborted+ ? "The operation was cancelled before this script was started."+ : deadline.interruption === "timeout"+ ? `The total captured-script analysis deadline of ${String(input.total_analysis_timeout_ms ?? WEB_BUNDLE_WORKER_LIMITS.totalTimeoutMs)} ms expired before this script was started.`+ : resultCapacityExhausted+ ? "The host could not reserve more web-analysis result capacity; this script was not started."+ : "An earlier analyzer failure prevented this script from starting.",+ });+ };+ try {+ await WebBundleAnalysisWorker.retryPending();+ this.#worker = this.createWorker(+ input.max_heap_mb ?? WEB_BUNDLE_WORKER_LIMITS.heapMb,+ );+ for (const script of scripts) {+ if (deadline.signal.aborted) break;+ const analyzed = await this.#worker.analyze(+ script,+ input.analysis_timeout_ms ?? WEB_BUNDLE_WORKER_LIMITS.scriptTimeoutMs,+ deadline.signal,+ );+ if (analyzed.ok) results.push(analyzed.value);+ else {+ const error = analyzed.error.error;+ results.push(+ analyzed.error.completed ?? {+ status: "unavailable",+ script_key: script.script_key,+ reason: caller.aborted+ ? "cancelled"+ : deadline.interruption === "timeout" ||+ error instanceof AnalysisTimeoutError+ ? "deadline"+ : error instanceof AnalysisResourceConstraintError+ ? "resource_constraint"+ : "worker_failure",+ detail:+ error instanceof AnalysisResourceConstraintError &&+ error.reportedLimits !== null+ ? `${error.message} Reported limits: ${JSON.stringify(error.reportedLimits)}`+ : error.message,+ },+ );+ if (error.cleanupIncomplete) {+ failure = error;+ break;+ }+ if (analyzed.error.continuation === "result_capacity_exhausted") {+ resultCapacityExhausted = true;+ failure = error;+ break;+ }+ if (error instanceof AnalysisCapabilityUnavailableError) {+ failure = error;+ break;+ }+ if (caller.aborted || deadline.signal.aborted) break;+ }+ }+ } catch (cause) {+ failure =+ cause instanceof AnalysisError+ ? cause+ : new AnalysisOutputError(+ "analyze_web_bundle",+ "Web analyzer could not complete its owned work",+ { cause },+ );+ }+ appendUnstarted();+ let partial: WebBundleAnalysis | undefined;+ try {+ partial = buildCapturedWebBundleAnalysis(inspection, sourceMaps, results);+ } catch (cause) {+ failure = new AnalysisOutputError(+ "analyze_web_bundle",+ "Completed web script facts could not be assembled",+ { cause },+ );+ }+ const hasPrimaryFailure =+ failure !== undefined &&+ (!failure.cleanupIncomplete || failure.cleanupPrimary !== undefined);+ try {+ await this.#releaseWorker();+ } catch (cause) {+ const cleanup =+ cause instanceof AnalysisError+ ? cause+ : new ProviderCleanupError(+ "web-bundle-static-analysis",+ [],+ { reason: "Web analyzer final cleanup remains incomplete" },+ { operation: "analyze_web_bundle", cause },+ );+ failure =+ failure === undefined+ ? cleanup+ : analysisErrorWithCleanupFailure(+ failure,+ cleanup,+ "analyze_web_bundle",+ ).bindCleanupDependencies([failure, cleanup]);+ } finally {+ deadline.dispose();+ }+ if (+ !hasPrimaryFailure &&+ caller.aborted &&+ deadline.interruption !== "timeout"+ ) {+ const cancelled = new AnalysisCancelledError("analyze_web_bundle", {+ cause: caller.reason,+ partialObservation: partial ?? inspection,+ });+ failure =+ failure?.cleanupIncomplete === true+ ? analysisErrorWithCleanupFailure(+ cancelled,+ failure,+ "analyze_web_bundle",+ ).bindCleanupDependencies([cancelled, failure])+ : cancelled;+ } else if (!hasPrimaryFailure && deadline.interruption === "timeout") {+ const timeout = new AnalysisTimeoutError(+ "analyze_web_bundle",+ input.total_analysis_timeout_ms ??+ WEB_BUNDLE_WORKER_LIMITS.totalTimeoutMs,+ {+ cause: deadline.signal.reason,+ partialObservation: partial ?? inspection,+ },+ );+ failure =+ failure?.cleanupIncomplete === true+ ? analysisErrorWithCleanupFailure(+ timeout,+ failure,+ "analyze_web_bundle",+ ).bindCleanupDependencies([timeout, failure])+ : timeout;+ }+ if (failure !== undefined) {+ failure.retainPartialObservation(partial ?? inspection);+ return err(failure);+ }+ if (partial === undefined)+ return err(+ new AnalysisOutputError(+ "analyze_web_bundle",+ "Web analysis produced no result",+ ),+ );+ return ok(partial);+ }++ async close(): Promise<void> {+ this.#closed = true;+ this.#controller?.abort(+ new Error("Browser provider closed during bundle analysis"),+ );+ await this.#running;+ await this.#releaseWorker();+ }+ async #releaseWorker(): Promise<void> {+ try {+ await this.#worker?.close();+ this.#worker = undefined;+ IsolatedWebBundleAnalyzer.#pendingCleanup.delete(this);+ } catch (cause) {+ IsolatedWebBundleAnalyzer.#pendingCleanup.add(this);+ throw cause;+ }+ }+}diff --git a/src/browser/WebBundleAnalysisWorker.test.ts b/src/browser/WebBundleAnalysisWorker.test.tsnew file mode 100644index 000000000..a75be3a8c--- /dev/null+++ b/src/browser/WebBundleAnalysisWorker.test.ts@@ -0,0 +1,360 @@+import { createHash, randomUUID } from "node:crypto";+import { access } from "node:fs/promises";+import { expect, it } from "vitest";++import { createWebTextArtifact } from "../domain/webContentArtifact.js";+import type { IncludedScript } from "../domain/webBundleAnalyzerInspection.js";+import {+ AnalysisCancelledError,+ AnalysisOutputError,+ AnalysisResourceConstraintError,+ AnalysisTimeoutError,+} from "../domain/analysisErrorCore.js";+import {+ resolvedAnalysisError,+ type AnalysisError,+} from "../domain/analysisErrorBase.js";+import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";+import {+ spawnOwnedProviderProcess,+ type ProviderProcessHandle,+} from "../process/ProviderProcess.js";+import { WebBundleAnalysisWorker } from "./WebBundleAnalysisWorker.js";+import { WEB_BUNDLE_WORKER_LIMITS } from "./WebBundleAnalysisWorkerProtocol.js";++const makeScript = (text: string): IncludedScript => ({+ script_key: `scr_${createHash("sha256").update(text).digest("hex")}`,+ frame_id: "frame-1",+ url: "https://app.example.test/app.js",+ origin: "https://app.example.test",+ cdp_hash: null,+ length: Buffer.byteLength(text),+ is_module: false,+ language: "JavaScript",+ source_map_url: null,+ resource_reconciliation: {+ status: "unmatched",+ reason: "no_exact_sanitized_url",+ },+ source: {+ included: true,+ artifact: createWebTextArtifact(text, "application/javascript"),+ },+});++const sourceWorkerProgram = (+ hangMarker?: string,+ oomMarker?: string,+): string => `+ const { serveWebBundleAnalysisWorker } = await import(${JSON.stringify(new URL("./WebBundleAnalysisWorkerServer.ts", import.meta.url).href)});+ const { analyzeCapturedWebScript } = await import(${JSON.stringify(new URL("../domain/webBundleAnalyzer.ts", import.meta.url).href)});+ const analyze = (script) => {+ if (${JSON.stringify(hangMarker)} !== undefined && script.source.artifact.text === ${JSON.stringify(hangMarker)}) {+ for (;;) {}+ }+ if (${JSON.stringify(oomMarker)} !== undefined && script.source.artifact.text === ${JSON.stringify(oomMarker)}) {+ const retained = [];+ for (;;) retained.push(new Array(50_000).fill({ marker: "bounded-child-oom" }));+ }+ return analyzeCapturedWebScript(script);+ };+ await serveWebBundleAnalysisWorker(analyze);+`;++type TestMode =+ | {+ readonly kind: "source";+ readonly hangMarker?: string;+ readonly oomMarker?: string;+ }+ | { readonly kind: "delayed-ready" }+ | {+ readonly kind: "protocol";+ readonly failure: "wrong-id" | "oversized-control" | "oversized-result";+ };++const protocolWorkerProgram = (+ failure: "wrong-id" | "oversized-control" | "oversized-result",+): string => `+ import { createInterface } from "node:readline";+ import { getHeapStatistics } from "node:v8";+ const send = (value) => process.stdout.write(JSON.stringify(value) + "\\n");+ send({ kind: "ready", heap_limit_bytes: getHeapStatistics().heap_size_limit });+ const input = createInterface({ input: process.stdin, crlfDelay: Infinity });+ input.once("line", (line) => {+ const request = JSON.parse(line);+ ${+ failure === "wrong-id"+ ? `send({ kind: "phase", id: ${JSON.stringify(randomUUID())}, phase: "analyze" });`+ : failure === "oversized-control"+ ? `process.stdout.write("x".repeat(70 * 1024) + "\\n");`+ : `send({ kind: "complete", id: request.id, result: { bytes: request.result_budget_bytes + 1, sha256: "${"0".repeat(64)}" } });`+ }+ });+`;++const delayedReadyProgram = `+ import { createInterface } from "node:readline";+ import { getHeapStatistics } from "node:v8";+ setTimeout(() => {+ process.stdout.write(JSON.stringify({ kind: "ready", heap_limit_bytes: getHeapStatistics().heap_size_limit }) + "\\n");+ }, 1_500);+ createInterface({ input: process.stdin, crlfDelay: Infinity });+`;++interface SpawnedTestProcess {+ readonly process: ProviderProcessHandle;+ readonly root: string | undefined;+}++const launcherFor = (+ mode: TestMode,+ options: {+ readonly failCleanupOnce?: boolean;+ readonly onSpawn?: (spawned: SpawnedTestProcess) => void;+ } = {},+): typeof spawnOwnedProviderProcess => {+ let failCleanup = options.failCleanupOnce ?? false;+ return async (request) => {+ const loader = import.meta.resolve("tsx");+ const program =+ mode.kind === "source"+ ? sourceWorkerProgram(mode.hangMarker, mode.oomMarker)+ : mode.kind === "delayed-ready"+ ? delayedReadyProgram+ : protocolWorkerProgram(mode.failure);+ const spawned = await spawnOwnedProviderProcess({+ ...request,+ arguments: [+ ...request.arguments.slice(0, -1),+ "--import",+ loader,+ "--input-type=module",+ "-e",+ program,+ ],+ });+ options.onSpawn?.({ process: spawned.process, root: request.cwd });+ return {+ ...spawned,+ cleanup: async () => {+ if (failCleanup) {+ failCleanup = false;+ return { cleaned: false, reason: "controlled worker cleanup retry" };+ }+ return spawned.cleanup === undefined+ ? cleanupOwnedProcessGroup(spawned.ownership)+ : spawned.cleanup();+ },+ };+ };+};++const failureOf = <Value>(+ result: Awaited<ReturnType<WebBundleAnalysisWorker["analyze"]>>,+): AnalysisError => {+ if (result.ok) throw new Error("Expected web worker failure");+ return result.error.error;+};++const waitForExit = async (child: ProviderProcessHandle): Promise<void> => {+ if (child.exitCode !== null || child.signalCode !== null) return;+ await new Promise<void>((resolve, reject) => {+ let timer: NodeJS.Timeout | undefined;+ const finish = (): void => {+ if (timer !== undefined) clearTimeout(timer);+ child.off("exit", onExit);+ resolve();+ };+ const onExit = (): void => finish();+ child.once("exit", onExit);+ timer = setTimeout(() => {+ child.off("exit", onExit);+ reject(new Error("Owned child did not exit"));+ }, 3_000);+ if (child.exitCode !== null || child.signalCode !== null) finish();+ });+};++it("reuses one real owned worker for completed facts from consecutive scripts", async () => {+ const children: ProviderProcessHandle[] = [];+ const worker = new WebBundleAnalysisWorker(+ WEB_BUNDLE_WORKER_LIMITS.heapMb,+ launcherFor(+ { kind: "source" },+ { onSpawn: ({ process: child }) => children.push(child) },+ ),+ );+ try {+ const first = await worker.analyze(makeScript("fetch('/users');"), 10_000);+ const second = await worker.analyze(+ makeScript("fetch('/orders');"),+ 10_000,+ );+ expect(first.ok).toBe(true);+ expect(second.ok).toBe(true);+ if (!first.ok || !second.ok)+ throw new Error("Expected both captured scripts to complete");+ expect(first.value).toMatchObject({+ status: "analyzed",+ script_key: makeScript("fetch('/users');").script_key,+ });+ expect(second.value).toMatchObject({+ status: "analyzed",+ script_key: makeScript("fetch('/orders');").script_key,+ });+ expect(children).toHaveLength(1);+ } finally {+ await worker.close();+ }+});++it("kills a hung owned child at the deadline and starts a fresh worker for the next script", async () => {+ const children: ProviderProcessHandle[] = [];+ const worker = new WebBundleAnalysisWorker(+ WEB_BUNDLE_WORKER_LIMITS.heapMb,+ launcherFor(+ { kind: "source", hangMarker: "hang forever" },+ { onSpawn: ({ process: child }) => children.push(child) },+ ),+ );+ try {+ const timedOut = await worker.analyze(makeScript("hang forever"), 500);+ expect(failureOf(timedOut)).toBeInstanceOf(AnalysisTimeoutError);+ await waitForExit(children[0]!);+ expect(+ children[0]?.exitCode !== null || children[0]?.signalCode !== null,+ ).toBe(true);+ const recovered = await worker.analyze(+ makeScript("fetch('/after-timeout');"),+ 10_000,+ );+ expect(recovered.ok).toBe(true);+ expect(children).toHaveLength(2);+ } finally {+ await worker.close();+ }+});++it("contains child heap exhaustion and reuses the host for a later script", async () => {+ const children: ProviderProcessHandle[] = [];+ const roots: string[] = [];+ const worker = new WebBundleAnalysisWorker(+ 128,+ launcherFor(+ { kind: "source", oomMarker: "exhaust child heap" },+ {+ onSpawn: ({ process: child, root }) => {+ children.push(child);+ if (root !== undefined) roots.push(root);+ },+ },+ ),+ );+ try {+ const exhausted = await worker.analyze(+ makeScript("exhaust child heap"),+ 15_000,+ );+ expect(failureOf(exhausted)).toBeInstanceOf(+ AnalysisResourceConstraintError,+ );+ await waitForExit(children[0]!);+ expect(+ children[0]?.exitCode !== null || children[0]?.signalCode !== null,+ ).toBe(true);+ const recovered = await worker.analyze(+ makeScript("fetch('/after-oom');"),+ 10_000,+ );+ expect(recovered.ok).toBe(true);+ expect(children).toHaveLength(2);+ expect(roots).toHaveLength(2);+ expect(roots[0]).toBe(roots[1]);+ await access(roots[0]!);+ await worker.close();+ await expect(access(roots[0]!)).rejects.toThrow();+ } finally {+ await worker.close();+ }+});++it("cancels during the late ready handshake and retains failed cleanup until exact retry", async () => {+ const children: SpawnedTestProcess[] = [];+ let announceSpawn: () => void = () => {};+ const spawned = new Promise<void>((resolve) => {+ announceSpawn = resolve;+ });+ const worker = new WebBundleAnalysisWorker(+ WEB_BUNDLE_WORKER_LIMITS.heapMb,+ launcherFor(+ { kind: "delayed-ready" },+ {+ failCleanupOnce: true,+ onSpawn: (child) => {+ children.push(child);+ announceSpawn();+ },+ },+ ),+ );+ const controller = new AbortController();+ const reason = { source: "late-handshake-test" };+ try {+ const analyzing = worker.analyze(+ makeScript("fetch('/cancelled');"),+ 10_000,+ controller.signal,+ );+ await spawned;+ controller.abort(reason);+ const result = await analyzing;+ const error = failureOf(result);+ expect(error.cleanupIncomplete).toBe(true);+ expect(error.cleanupPrimary).toBeInstanceOf(AnalysisCancelledError);+ expect(error.cleanupPrimary?.cause).toBe(reason);+ expect(children[0]?.root).toBeDefined();+ await access(children[0]?.root ?? "");++ await worker.close();+ expect(error.cleanupIncomplete).toBe(false);+ expect(resolvedAnalysisError(error).cause).toBe(reason);+ await expect(access(children[0]?.root ?? "")).rejects.toThrow();+ await waitForExit(children[0]!.process);+ } finally {+ if (+ children[0]?.process.exitCode === null &&+ children[0]?.process.signalCode === null+ )+ children[0]?.process.kill("SIGKILL");+ await worker.close().catch(() => undefined);+ await WebBundleAnalysisWorker.retryPending().catch(() => undefined);+ }+});++it.each([+ ["wrong-id", AnalysisOutputError],+ ["oversized-control", AnalysisOutputError],+ ["oversized-result", AnalysisResourceConstraintError],+] as const)(+ "rejects %s before accepting unverified result bytes",+ async (failure, ErrorType) => {+ const worker = new WebBundleAnalysisWorker(+ WEB_BUNDLE_WORKER_LIMITS.heapMb,+ launcherFor({ kind: "protocol", failure }),+ );+ try {+ const result = await worker.analyze(+ makeScript("fetch('/not-read');"),+ 10_000,+ );+ expect(failureOf(result)).toBeInstanceOf(ErrorType);+ if (failure === "oversized-result")+ expect(failureOf(result).message).toContain(+ "exceed the host's remaining reserved result capacity",+ );+ } finally {+ await worker.close();+ }+ },+);diff --git a/src/browser/WebBundleAnalysisWorker.ts b/src/browser/WebBundleAnalysisWorker.tsnew file mode 100644index 000000000..74a99c718--- /dev/null+++ b/src/browser/WebBundleAnalysisWorker.ts@@ -0,0 +1,612 @@+import { createHash, randomUUID } from "node:crypto";+import { open, rm } from "node:fs/promises";+import { join } from "node:path";+import { fileURLToPath } from "node:url";+import { StringDecoder } from "node:string_decoder";+import { getHeapStatistics } from "node:v8";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import {+ AnalysisCleanupLease,+ AnalysisCleanupLeaseGroup,+} from "../artifacts/AnalysisCleanupLease.js";+import {+ ArtifactFileCancelled,+ ArtifactFileCleanupFailure,+ artifactFileCancellationCause,+ withArtifactFileHandle,+} from "../artifacts/ArtifactFileOperation.js";+import { readStableArtifact } from "../artifacts/readStableArtifact.js";+import type { StableArtifactSnapshot } from "../artifacts/readStableArtifact.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisCapabilityUnavailableError,+ AnalysisCancelledError,+ AnalysisTimeoutError,+ AnalysisOutputError,+ AnalysisResourceConstraintError,+} from "../domain/analysisErrorCore.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { jsonParts, bufferedJsonParts } from "../domain/jsonSerialization.js";+import { javaScriptRuntime } from "../domain/runtimeVersion.js";+import { err, ok, type Result } from "../domain/result.js";+import type { IncludedScript } from "../domain/webBundleAnalyzerInspection.js";+import {+ webBundleScriptAnalysisSchema,+ type WebBundleScriptAnalysis,+} from "../domain/webBundleScriptAnalysis.js";+import { OwnedWorkerRuntime } from "../process/OwnedWorkerRuntime.js";+import { PrivateRuntimeRootUnavailableError } from "../process/PrivateRuntimeRootUnavailableError.js";+import { spawnOwnedProviderProcess } from "../process/ProviderProcess.js";+import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";+import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";+import { javaScriptWorkerMemoryLimitBytes } from "../process/JavaScriptWorkerMemoryLimit.js";+import {+ WEB_BUNDLE_WORKER_LIMITS,+ webBundleWorkerMessageSchema,+ webBundleWorkerRequestSchema,+ type WebBundleWorkerMessage,+} from "./WebBundleAnalysisWorkerProtocol.js";++const OPERATION = "analyze_web_bundle";+const PROVIDER = "web-bundle-static-analysis";+const MIB = 1024 * 1024;+/** Source/result buffers, decoded strings, parsed objects and validation copies. */+const RESULT_EXPANSION = 16;++type WebBundleResultDescriptor = Extract<+ WebBundleWorkerMessage,+ { readonly kind: "complete" }+>["result"];++const stableSnapshotValue = (+ value: unknown,+): StableArtifactSnapshot | undefined => {+ if (+ value === null ||+ typeof value !== "object" ||+ !("bytes" in value) ||+ !Buffer.isBuffer(value.bytes) ||+ !("sha256" in value) ||+ typeof value.sha256 !== "string"+ )+ return undefined;+ return { bytes: value.bytes, sha256: value.sha256 };+};++export interface WebBundleScriptAnalysisFailure {+ readonly error: AnalysisError;+ readonly completed: WebBundleScriptAnalysis | null;+ readonly continuation?: "result_capacity_exhausted";+}++/** Sequential inert-source analysis; only bounded completed facts cross into the host. */+export class WebBundleAnalysisWorker {+ static readonly #pendingCleanup = new Set<WebBundleAnalysisWorker>();+ readonly #runtime: OwnedWorkerRuntime;+ readonly #files = new ArtifactResourceScope();+ readonly #cleanup: AnalysisCleanupLease;+ #decoder = new StringDecoder("utf8");+ #pending = "";+ #frames: WebBundleWorkerMessage[] = [];+ #protocolFailure: unknown;+ #retainedResultBytes = 0;+ #ready = false;+ readonly #stdout = (chunk: Buffer | string): void => {+ if (this.#protocolFailure !== undefined) return;+ try {+ // Refuse the chunk before appending it to any retained control text.+ if (+ Buffer.byteLength(chunk) + Buffer.byteLength(this.#pending) >+ WEB_BUNDLE_WORKER_LIMITS.protocolBytes+ )+ throw new RangeError("Web analyzer exceeded its control-frame budget");+ this.#pending +=+ typeof chunk === "string" ? chunk : this.#decoder.write(chunk);+ for (;;) {+ const end = this.#pending.indexOf("\n");+ if (end < 0) break;+ if (this.#frames.length >= 16)+ throw new RangeError("Web analyzer exceeded its control-frame queue");+ this.#frames.push(+ webBundleWorkerMessageSchema.parse(+ JSON.parse(this.#pending.slice(0, end)),+ ),+ );+ this.#pending = this.#pending.slice(end + 1);+ }+ } catch (cause) {+ this.#pending = "";+ this.#protocolFailure = cause;+ }+ };++ constructor(+ readonly heapMb = 1024,+ launcher: typeof spawnOwnedProviderProcess = spawnOwnedProviderProcess,+ ) {+ if (!Number.isSafeInteger(heapMb) || heapMb < 128 || heapMb > 16_384)+ throw new RangeError(+ "Web analyzer heap must be an integer from 128 through 16384 MiB",+ );+ this.#runtime = new OwnedWorkerRuntime({+ rootPrefix: "rea-web-bundle-analysis-",+ launcher,+ retryCleanup: () => this.close(),+ supervisorOptions: {+ captureStdout: false,+ maxDiagnosticBytes: 256 * 1024,+ },+ });+ const owner = this;+ this.#cleanup = new AnalysisCleanupLease(() => this.#release(), {+ get cleanupResources() {+ return [+ ...owner.#files.cleanupResources,+ ...(owner.#runtime.cleanupResources ?? []),+ ];+ },+ });+ }++ static async retryPending(): Promise<void> {+ for (const worker of [...this.#pendingCleanup]) await worker.close();+ await OwnedWorkerRuntime.retryPending();+ }++ async analyze(+ script: IncludedScript,+ timeoutMs: number,+ signal?: AbortSignal,+ ): Promise<Result<WebBundleScriptAnalysis, WebBundleScriptAnalysisFailure>> {+ let deadline: ProviderStartupDeadline | undefined;+ const id = randomUUID();+ let result: Result<WebBundleScriptAnalysis, AnalysisError>;+ let completed: WebBundleScriptAnalysis | null = null;+ let continuation: "result_capacity_exhausted" | undefined;+ let resultDescriptor: WebBundleResultDescriptor | undefined;+ const failed = (+ error: AnalysisError,+ ): Result<WebBundleScriptAnalysis, WebBundleScriptAnalysisFailure> =>+ err({+ error,+ completed,+ ...(continuation === undefined ? {} : { continuation }),+ });+ try {+ if (signal?.aborted)+ throw new AnalysisCancelledError(OPERATION, { cause: signal.reason });+ const resultBudget = Math.min(+ WEB_BUNDLE_WORKER_LIMITS.resultBytes - this.#retainedResultBytes,+ Math.max(+ 0,+ Math.floor(+ (getHeapStatistics().heap_size_limit -+ process.memoryUsage().heapUsed -+ 64 * MIB) /+ RESULT_EXPANSION,+ ),+ ),+ );+ if (resultBudget <= 0) {+ continuation = "result_capacity_exhausted";+ throw new AnalysisResourceConstraintError(+ OPERATION,+ "memory",+ "The host has no remaining reserved web-analysis result capacity",+ { result_bytes: WEB_BUNDLE_WORKER_LIMITS.resultBytes },+ );+ }+ await prepareProcessOwnershipInspection(signal);+ deadline = new ProviderStartupDeadline(timeoutMs, signal);+ await this.#start(deadline);+ if (this.#frames.length > 0 || this.#pending !== "")+ throw new AnalysisOutputError(+ OPERATION,+ "Web analyzer emitted unsolicited control data",+ );+ const root = this.#runtime.rootPath;+ const supervisor = this.#runtime.supervisor;+ if (root === undefined || supervisor === undefined)+ throw new TypeError("Web analyzer resources were not acquired");+ supervisor.resetOutput();+ const source = await this.#files.run(() =>+ this.#writeSource(join(root, `${id}.source`), script, deadline!.signal),+ );+ const request = webBundleWorkerRequestSchema.parse({+ kind: "analyze",+ id,+ source,+ result_budget_bytes: resultBudget,+ });+ const frame = `${JSON.stringify(request)}\n`;+ const stdin = supervisor.launch.process.stdin;+ if (stdin === null || stdin === undefined)+ throw new TypeError("Web analyzer request stream is unavailable");+ await new Promise<void>((resolve, reject) =>+ stdin.write(frame, (error) =>+ error == null ? resolve() : reject(error),+ ),+ );+ let response: WebBundleWorkerMessage;+ do {+ response = await this.#next(deadline);+ if (response.kind === "ready" || response.id !== id)+ throw new AnalysisOutputError(+ OPERATION,+ "Web analyzer response names another request",+ );+ } while (response.kind === "phase");+ if (response.kind === "failure") {+ if (response.reason === "resource")+ throw new AnalysisResourceConstraintError(+ OPERATION,+ "memory",+ response.message,+ { result_budget_bytes: resultBudget },+ );+ throw new AnalysisOutputError(+ OPERATION,+ `Web script analysis failed (${response.reason}): ${response.message}`,+ );+ }+ if (response.kind !== "complete")+ throw new AnalysisOutputError(+ OPERATION,+ "Web analyzer did not complete a result",+ );+ const descriptor = response.result;+ resultDescriptor = descriptor;+ // Reserve expansion before reading bytes, decoding JSON or schema validation.+ if (+ descriptor.bytes > resultBudget ||+ descriptor.bytes * RESULT_EXPANSION + 64 * MIB >+ getHeapStatistics().heap_size_limit - process.memoryUsage().heapUsed+ )+ throw new AnalysisResourceConstraintError(+ OPERATION,+ "memory",+ "Completed script facts exceed the host's remaining reserved result capacity",+ { result_budget_bytes: resultBudget },+ );+ const stored = await this.#files.run(() =>+ readStableArtifact(+ join(root, `${id}.result`),+ descriptor.bytes,+ deadline!.signal,+ undefined,+ this.#files,+ ),+ );+ const facts = this.#validateCompletedResult(stored, descriptor, script);+ this.#retainedResultBytes += descriptor.bytes;+ completed = facts;+ result = ok(facts);+ } catch (cause) {+ const snapshot = this.#completedSnapshot(cause);+ if (snapshot !== undefined && resultDescriptor !== undefined) {+ try {+ completed = this.#validateCompletedResult(+ snapshot,+ resultDescriptor,+ script,+ );+ this.#retainedResultBytes += resultDescriptor.bytes;+ } catch {+ // The physical read completed, but only validated facts are retained.+ }+ }+ const cancellationCause = this.#completedReadCancellation(cause);+ const interrupted =+ deadline?.interruption === "timeout"+ ? new AnalysisTimeoutError(OPERATION, timeoutMs, { cause })+ : cancellationCause !== undefined+ ? new AnalysisCancelledError(OPERATION, {+ cause: cancellationCause.reason,+ })+ : deadline?.interruption === "cancelled" || signal?.aborted+ ? new AnalysisCancelledError(OPERATION, {+ cause: signal?.aborted+ ? signal.reason+ : deadline?.signal.reason,+ })+ : undefined;+ const failure =+ cause instanceof ArtifactFileCleanupFailure &&+ cause.fileCleanupFailure.outcome.kind === "completed"+ ? this.#cleanupFailure(cause, interrupted)+ : (interrupted ??+ (cause instanceof PrivateRuntimeRootUnavailableError+ ? new AnalysisCapabilityUnavailableError(+ PROVIDER,+ OPERATION,+ cause.message,+ { cause, retryable: cause.retryable },+ )+ : cause instanceof AnalysisError+ ? cause+ : new AnalysisOutputError(+ OPERATION,+ "Owned web-script analysis failed",+ { cause },+ )));+ result = err(failure);+ try {+ const stopped = await this.#runtime.stop();+ if (stopped.status === "incomplete") throw new Error(stopped.reason);+ this.#reset();+ } catch (cleanupCause) {+ result = err(this.#cleanupFailure(cleanupCause, failure));+ }+ } finally {+ deadline?.dispose();+ }+ // Never remove job files while a failed descriptor or child remains owned.+ if (!result.ok && result.error.cleanupIncomplete)+ return failed(result.error);+ if (this.#files.hasPending)+ return failed(+ this.#cleanupFailure(+ new Error("Web analyzer artifact cleanup is incomplete"),+ result.ok ? undefined : result.error,+ ),+ );+ try {+ const root = this.#runtime.rootPath;+ if (root !== undefined) {+ await rm(join(root, `${id}.source`), { force: true });+ await rm(join(root, `${id}.result`), { force: true });+ }+ } catch (cause) {+ return failed(+ this.#cleanupFailure(cause, result.ok ? undefined : result.error),+ );+ }+ if (signal?.aborted && result.ok)+ return failed(+ new AnalysisCancelledError(OPERATION, { cause: signal.reason }),+ );+ return result.ok ? result : failed(result.error);+ }++ async #writeSource(+ path: string,+ script: IncludedScript,+ signal: AbortSignal,+ ): Promise<{ bytes: number; sha256: string }> {+ const digest = createHash("sha256");+ let bytes = 0;+ const file = await open(path, "wx", 0o600);+ await withArtifactFileHandle(+ path,+ file,+ this.#files,+ signal,+ async (handle) => {+ for (const part of bufferedJsonParts(jsonParts(script))) {+ signal.throwIfAborted();+ const chunk = Buffer.from(part, "utf8");+ if (chunk.length > WEB_BUNDLE_WORKER_LIMITS.sourceBytes - bytes)+ throw new AnalysisResourceConstraintError(+ OPERATION,+ "transport",+ "Captured script metadata and source exceed the worker transfer budget",+ { source_bytes: WEB_BUNDLE_WORKER_LIMITS.sourceBytes },+ );+ await handle.writeFile(chunk);+ bytes += chunk.length;+ digest.update(chunk);+ }+ },+ );+ return { bytes, sha256: digest.digest("hex") };+ }++ async #start(deadline: ProviderStartupDeadline): Promise<void> {+ if (this.#ready && this.#runtime.supervisor !== undefined) return;+ const environment: NodeJS.ProcessEnv = {+ ...process.env,+ UV_THREADPOOL_SIZE: "1",+ };+ delete environment.NODE_OPTIONS;+ const memoryLimitBytes = javaScriptWorkerMemoryLimitBytes(this.heapMb);+ await this.#runtime.start(+ {+ command: process.execPath,+ arguments: [+ `--max-old-space-size=${String(this.heapMb)}`,+ "--max-semi-space-size=8",+ "--v8-pool-size=1",+ "--expose-gc",+ "--stack_size=2048",+ fileURLToPath(import.meta.resolve("#web-bundle-analysis-worker")),+ ],+ runId: `rea-web-bundle-analysis-${randomUUID()}`,+ hostEnvironment: environment,+ stdin: "pipe",+ signal: deadline.signal,+ ...(memoryLimitBytes === null ? {} : { memoryLimitBytes }),+ },+ async () => {+ this.#runtime.onStdout(this.#stdout);+ const ready = await this.#next(deadline);+ if (+ ready.kind !== "ready" ||+ (ready.heap_limit_bytes === null) ===+ (javaScriptRuntime(process.versions).id === "node")+ )+ throw new AnalysisOutputError(+ OPERATION,+ "Web analyzer ready frame has an incompatible runtime heap limit",+ );+ this.#ready = true;+ },+ );+ }++ async #next(+ deadline: ProviderStartupDeadline,+ ): Promise<WebBundleWorkerMessage> {+ for (;;) {+ if (deadline.interruption === "timeout")+ throw new AnalysisTimeoutError(OPERATION, deadline.timeoutMs);+ if (deadline.interruption === "cancelled")+ throw new AnalysisCancelledError(OPERATION, {+ cause: deadline.signal.reason,+ });+ deadline.signal.throwIfAborted();+ if (this.#runtime.inputFailure !== undefined)+ throw new AnalysisOutputError(+ OPERATION,+ "Web analyzer request stream failed",+ { cause: this.#runtime.inputFailure },+ );+ if (this.#protocolFailure !== undefined)+ throw new AnalysisOutputError(+ OPERATION,+ "Invalid web analyzer control frame",+ { cause: this.#protocolFailure },+ );+ const frame = this.#frames.shift();+ if (frame !== undefined) return frame;+ const supervisor = this.#runtime.supervisor;+ const snapshot = supervisor?.snapshot();+ if (+ snapshot !== undefined &&+ (snapshot.exitCode !== undefined || snapshot.signal !== undefined)+ ) {+ if (!(await supervisor?.waitForOutputClose(10))) continue;+ if (this.#frames.length > 0) continue;+ const finalSnapshot = supervisor?.snapshot() ?? snapshot;+ const capturedOutput = {+ stdout: "",+ stderr: finalSnapshot.stderr.text,+ truncated: finalSnapshot.diagnosticTruncated ?? false,+ exit_code: finalSnapshot.exitCode ?? null,+ signal: finalSnapshot.signal ?? null,+ };+ if (+ supervisor?.launch.process.memoryLimitReached === true ||+ /heap out of memory|heap limit|allocation failed/iu.test(+ finalSnapshot.stderr.text,+ )+ )+ throw new AnalysisResourceConstraintError(+ OPERATION,+ "memory",+ "Owned web analyzer exhausted its configured memory limit",+ {+ worker_heap_limit_mb: this.heapMb,+ worker_process_memory_limit_bytes:+ javaScriptWorkerMemoryLimitBytes(this.heapMb),+ },+ { capturedOutput },+ );+ throw new AnalysisOutputError(+ OPERATION,+ "Owned web analyzer exited before completing this script",+ { capturedOutput },+ );+ }+ await deadline.wait(10);+ }+ }++ #completedSnapshot(cause: unknown): StableArtifactSnapshot | undefined {+ if (cause instanceof ArtifactFileCancelled)+ return stableSnapshotValue(cause.fileCancellation.outcome.value);+ if (+ cause instanceof ArtifactFileCleanupFailure &&+ cause.fileCleanupFailure.outcome.kind === "completed"+ )+ return stableSnapshotValue(cause.fileCleanupFailure.outcome.value);+ return undefined;+ }++ #completedReadCancellation(+ cause: unknown,+ ): { readonly reason: unknown } | undefined {+ if (cause instanceof ArtifactFileCancelled)+ return { reason: artifactFileCancellationCause(cause) };+ if (+ cause instanceof ArtifactFileCleanupFailure &&+ cause.fileCleanupFailure.outcome.kind === "completed"+ )+ return cause.fileCleanupFailure.completionCancellation;+ return undefined;+ }++ #validateCompletedResult(+ stored: StableArtifactSnapshot,+ descriptor: WebBundleResultDescriptor,+ script: IncludedScript,+ ): WebBundleScriptAnalysis {+ if (+ stored.bytes.length !== descriptor.bytes ||+ stored.sha256 !== descriptor.sha256+ )+ throw new AnalysisOutputError(+ OPERATION,+ "Web analyzer result differs from its descriptor",+ );+ const facts = webBundleScriptAnalysisSchema.parse(+ JSON.parse(stored.bytes.toString("utf8")),+ );+ if (facts.status !== "analyzed" || facts.script_key !== script.script_key)+ throw new AnalysisOutputError(+ OPERATION,+ "Web analyzer facts name another script",+ );+ return facts;+ }++ #reset(): void {+ this.#ready = false;+ this.#frames = [];+ this.#pending = "";+ this.#decoder = new StringDecoder("utf8");+ this.#protocolFailure = undefined;+ }++ #cleanupFailure(cause: unknown, primary?: AnalysisError): AnalysisError {+ WebBundleAnalysisWorker.#pendingCleanup.add(this);+ this.#runtime.retainForCleanup();+ const cleanup = new ProviderCleanupError(+ PROVIDER,+ this.#cleanup.cleanupResources ?? [],+ { reason: "Owned web analyzer cleanup remains incomplete" },+ { operation: OPERATION, cause },+ );+ new AnalysisCleanupLeaseGroup(cleanup, [this.#cleanup]);+ return primary === undefined+ ? cleanup+ : analysisErrorWithCleanupFailure(+ primary,+ cleanup,+ OPERATION,+ ).bindCleanupDependencies([primary, cleanup]);+ }++ async close(): Promise<void> {+ try {+ await this.#cleanup.release();+ } catch (cause) {+ throw this.#cleanupFailure(cause);+ }+ }++ async #release(): Promise<void> {+ try {+ const stopped = await this.#runtime.stop();+ if (stopped.status === "incomplete") throw new Error(stopped.reason);+ await this.#files.close();+ await this.#runtime.close();+ this.#reset();+ WebBundleAnalysisWorker.#pendingCleanup.delete(this);+ } catch (cause) {+ WebBundleAnalysisWorker.#pendingCleanup.add(this);+ this.#runtime.retainForCleanup();+ throw cause;+ }+ }+}diff --git a/src/browser/WebBundleAnalysisWorkerCapacity.test.ts b/src/browser/WebBundleAnalysisWorkerCapacity.test.tsnew file mode 100644index 000000000..7d43f5369--- /dev/null+++ b/src/browser/WebBundleAnalysisWorkerCapacity.test.ts@@ -0,0 +1,82 @@+import { createHash } from "node:crypto";+import { expect, it, vi } from "vitest";++const heapLimit = vi.hoisted(() => ({ override: null as number | null }));++vi.mock("node:v8", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:v8")>();+ return {+ ...actual,+ getHeapStatistics: () => {+ const statistics = actual.getHeapStatistics();+ return heapLimit.override === null+ ? statistics+ : { ...statistics, heap_size_limit: heapLimit.override };+ },+ };+});++import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";+import { createWebTextArtifact } from "../domain/webContentArtifact.js";+import type { IncludedScript } from "../domain/webBundleAnalyzerInspection.js";+import { WebBundleAnalysisWorker } from "./WebBundleAnalysisWorker.js";++it("refuses before spawning or reading source when no host result capacity remains", async () => {+ const text = "fetch('/never-serialized');";+ const base = makeScript(text);+ let sourceReads = 0;+ let launches = 0;+ const artifact = { ...base.source.artifact };+ Object.defineProperty(artifact, "text", {+ configurable: true,+ get: () => {+ sourceReads += 1;+ return text;+ },+ });+ const script: IncludedScript = {+ ...base,+ source: { included: true, artifact },+ };+ const worker = new WebBundleAnalysisWorker(1024, async () => {+ launches += 1;+ throw new Error(+ "The worker must not launch when the host has no result capacity",+ );+ });+ heapLimit.override = 0;++ try {+ const result = await worker.analyze(script, 10_000);+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected result-capacity refusal");+ expect(result.error.error).toBeInstanceOf(AnalysisResourceConstraintError);+ expect(result.error.continuation).toBe("result_capacity_exhausted");+ expect(result.error.completed).toBeNull();+ expect(sourceReads).toBe(0);+ expect(launches).toBe(0);+ } finally {+ heapLimit.override = null;+ await worker.close();+ }+});++const makeScript = (text: string): IncludedScript => ({+ script_key: `scr_${createHash("sha256").update(text).digest("hex")}`,+ frame_id: "frame-1",+ url: "https://app.example.test/app.js",+ origin: "https://app.example.test",+ cdp_hash: null,+ length: Buffer.byteLength(text),+ is_module: false,+ language: "JavaScript",+ source_map_url: null,+ resource_reconciliation: {+ status: "unmatched",+ reason: "no_exact_sanitized_url",+ },+ source: {+ included: true,+ artifact: createWebTextArtifact(text, "application/javascript"),+ },+});diff --git a/src/browser/WebBundleAnalysisWorkerProtocol.ts b/src/browser/WebBundleAnalysisWorkerProtocol.tsnew file mode 100644index 000000000..527c2e62e--- /dev/null+++ b/src/browser/WebBundleAnalysisWorkerProtocol.ts@@ -0,0 +1,75 @@+import { z } from "zod";+import { digestSchema } from "../domain/digests.js";+import { WEB_RUNTIME_LIMITS } from "../domain/webRuntime.js";+import { webPageInspectionSchema } from "../domain/browserObservationSchemas.js";+import { webTextArtifactSchema } from "../domain/webContentArtifact.js";++/** Independent per-script worker limits for source records and control frames. */+export const WEB_BUNDLE_WORKER_LIMITS = {+ heapMb: 1024,+ scriptTimeoutMs: 30_000,+ totalTimeoutMs: 300_000,+ protocolBytes: 64 * 1024,+ sourceBytes: 8 * WEB_RUNTIME_LIMITS.sourceBytes,+ resultBytes: 8 * 1024 * 1024,+} as const;++const includedSourceSchema = z.strictObject({+ included: z.literal(true),+ artifact: webTextArtifactSchema.strict(),+});++const browserScriptSchema =+ webPageInspectionSchema.shape.scripts.shape.items.element;++/** Derive producer metadata rules; the worker requires captured source text. */+export const includedWebScriptSchema = browserScriptSchema+ .extend({ source: includedSourceSchema })+ .strict();++export const webBundleWorkerRequestSchema = z.strictObject({+ kind: z.literal("analyze"),+ id: z.uuid(),+ source: z.strictObject({+ bytes: z.number().int().min(0).max(WEB_BUNDLE_WORKER_LIMITS.sourceBytes),+ sha256: digestSchema,+ }),+ result_budget_bytes: z+ .number()+ .int()+ .min(0)+ .max(WEB_BUNDLE_WORKER_LIMITS.resultBytes),+});++const identity = { id: z.uuid() };++/** Control frames contain descriptors and progress only, never source or findings. */+export const webBundleWorkerMessageSchema = z.discriminatedUnion("kind", [+ z.strictObject({+ kind: z.literal("ready"),+ heap_limit_bytes: z.number().int().positive().nullable(),+ }),+ z.strictObject({+ kind: z.literal("phase"),+ ...identity,+ phase: z.literal("analyze"),+ }),+ z.strictObject({+ kind: z.literal("complete"),+ ...identity,+ result: z.strictObject({+ bytes: z.number().int().nonnegative(),+ sha256: digestSchema,+ }),+ }),+ z.strictObject({+ kind: z.literal("failure"),+ ...identity,+ reason: z.enum(["input", "resource", "output", "io"]),+ message: z.string(),+ }),+]);++export type WebBundleWorkerMessage = z.output<+ typeof webBundleWorkerMessageSchema+>;diff --git a/src/browser/WebBundleAnalysisWorkerReadCompletion.test.ts b/src/browser/WebBundleAnalysisWorkerReadCompletion.test.tsnew file mode 100644index 000000000..e7135d723--- /dev/null+++ b/src/browser/WebBundleAnalysisWorkerReadCompletion.test.ts@@ -0,0 +1,174 @@+import { createHash } from "node:crypto";+import { access } from "node:fs/promises";+import { expect, it, vi } from "vitest";++const closeFailure = vi.hoisted(() => ({+ enabled: false,+ resultCloseAttempts: 0,+ root: undefined as string | undefined,+ rootRemovedBeforeResultClose: false,+}));++vi.mock("node:fs/promises", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...actual,+ rm: async (...args: Parameters<typeof actual.rm>) => {+ if (+ closeFailure.root !== undefined &&+ String(args[0]) === closeFailure.root &&+ closeFailure.resultCloseAttempts < 2+ )+ closeFailure.rootRemovedBeforeResultClose = true;+ return await actual.rm(...args);+ },+ open: async (...args: Parameters<typeof actual.open>) => {+ const handle = await actual.open(...args);+ const path = args[0];+ if (closeFailure.enabled && String(path).endsWith(".result")) {+ closeFailure.enabled = false;+ const close = handle.close.bind(handle);+ let failOnce = true;+ Object.defineProperty(handle, "close", {+ configurable: true,+ value: async () => {+ closeFailure.resultCloseAttempts += 1;+ if (failOnce) {+ failOnce = false;+ throw new Error("controlled completed-read close failure");+ }+ await close();+ },+ });+ }+ return handle;+ },+ };+});++import { createWebTextArtifact } from "../domain/webContentArtifact.js";+import type { IncludedScript } from "../domain/webBundleAnalyzerInspection.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";+import {+ spawnOwnedProviderProcess,+ type ProviderProcessHandle,+} from "../process/ProviderProcess.js";+import { OwnedWorkerRuntime } from "../process/OwnedWorkerRuntime.js";+import { WebBundleAnalysisWorker } from "./WebBundleAnalysisWorker.js";+import { WEB_BUNDLE_WORKER_LIMITS } from "./WebBundleAnalysisWorkerProtocol.js";++const makeScript = (text: string): IncludedScript => ({+ script_key: `scr_${createHash("sha256").update(text).digest("hex")}`,+ frame_id: "frame-1",+ url: "https://app.example.test/app.js",+ origin: "https://app.example.test",+ cdp_hash: null,+ length: Buffer.byteLength(text),+ is_module: false,+ language: "JavaScript",+ source_map_url: null,+ resource_reconciliation: {+ status: "unmatched",+ reason: "no_exact_sanitized_url",+ },+ source: {+ included: true,+ artifact: createWebTextArtifact(text, "application/javascript"),+ },+});++const ownedSourceLauncher = (+ failCleanupOnce = false,+): typeof spawnOwnedProviderProcess => {+ let failCleanup = failCleanupOnce;+ return async (request) => {+ const loader = import.meta.resolve("tsx");+ const server = new URL(+ "./WebBundleAnalysisWorkerServer.ts",+ import.meta.url,+ );+ const analyzer = new URL("../domain/webBundleAnalyzer.ts", import.meta.url);+ const program = `+ const { serveWebBundleAnalysisWorker } = await import(${JSON.stringify(server.href)});+ const { analyzeCapturedWebScript } = await import(${JSON.stringify(analyzer.href)});+ await serveWebBundleAnalysisWorker(analyzeCapturedWebScript);+ `;+ const spawned = await spawnOwnedProviderProcess({+ ...request,+ arguments: [+ `--max-old-space-size=${String(WEB_BUNDLE_WORKER_LIMITS.heapMb)}`,+ "--expose-gc",+ "--import",+ loader,+ "--input-type=module",+ "-e",+ program,+ ],+ });+ closeFailure.root = request.cwd;+ return {+ ...spawned,+ cleanup: async () => {+ if (failCleanup) {+ failCleanup = false;+ return {+ cleaned: false,+ reason: "controlled first process cleanup failure",+ };+ }+ return spawned.cleanup === undefined+ ? cleanupOwnedProcessGroup(spawned.ownership)+ : spawned.cleanup();+ },+ };+ };+};++it("retains completed facts and resolves a result-file lease through another cleanup consumer", async () => {+ const children: ProviderProcessHandle[] = [];+ const launch = ownedSourceLauncher(true);+ const worker = new WebBundleAnalysisWorker(+ WEB_BUNDLE_WORKER_LIMITS.heapMb,+ async (request) => {+ const spawned = await launch(request);+ children.push(spawned.process);+ return spawned;+ },+ );+ closeFailure.resultCloseAttempts = 0;+ closeFailure.rootRemovedBeforeResultClose = false;+ closeFailure.enabled = true;+ try {+ const result = await worker.analyze(+ makeScript("fetch('/retained');"),+ 10_000,+ );+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected retained result cleanup failure");+ expect(result.error.completed).toMatchObject({+ status: "analyzed",+ script_key: makeScript("fetch('/retained');").script_key,+ observations: {+ endpoints: [{ value: "/retained", mechanism: "call:fetch" }],+ },+ });+ expect(result.error.error.cleanupPrimary).toBeInstanceOf(+ ProviderCleanupError,+ );+ expect(result.error.error.cleanupIncomplete).toBe(true);+ expect(closeFailure.resultCloseAttempts).toBe(1);+ expect(closeFailure.root).toBeDefined();+ await access(closeFailure.root ?? "");+ expect(children).toHaveLength(1);++ await OwnedWorkerRuntime.retryPending();+ expect(result.error.error.cleanupIncomplete).toBe(false);+ expect(closeFailure.resultCloseAttempts).toBeGreaterThanOrEqual(2);+ expect(closeFailure.rootRemovedBeforeResultClose).toBe(false);+ await expect(access(closeFailure.root ?? "")).rejects.toThrow();+ } finally {+ await worker.close().catch(() => undefined);+ await OwnedWorkerRuntime.retryPending().catch(() => undefined);+ }+});diff --git a/src/browser/WebBundleAnalysisWorkerServer.test.ts b/src/browser/WebBundleAnalysisWorkerServer.test.tsnew file mode 100644index 000000000..fdd915918--- /dev/null+++ b/src/browser/WebBundleAnalysisWorkerServer.test.ts@@ -0,0 +1,231 @@+import { createHash, randomUUID } from "node:crypto";+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";+import { once } from "node:events";+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { createInterface } from "node:readline";+import { expect, it } from "vitest";++import { createWebTextArtifact } from "../domain/webContentArtifact.js";+import type { IncludedScript } from "../domain/webBundleAnalyzerInspection.js";+import {+ webBundleWorkerMessageSchema,+ type WebBundleWorkerMessage,+} from "./WebBundleAnalysisWorkerProtocol.js";+import { WEB_BUNDLE_WORKER_LIMITS } from "./WebBundleAnalysisWorkerProtocol.js";++const makeScript = (text: string): IncludedScript => ({+ script_key: `scr_${createHash("sha256").update(text).digest("hex")}`,+ frame_id: "frame-1",+ url: "https://app.example.test/app.js",+ origin: "https://app.example.test",+ cdp_hash: null,+ length: Buffer.byteLength(text),+ is_module: false,+ language: "JavaScript",+ source_map_url: null,+ resource_reconciliation: {+ status: "unmatched",+ reason: "no_exact_sanitized_url",+ },+ source: {+ included: true,+ artifact: createWebTextArtifact(text, "application/javascript"),+ },+});++const sourceDescriptor = (script: IncludedScript) => {+ const bytes = Buffer.from(JSON.stringify(script));+ return {+ bytes,+ descriptor: {+ bytes: bytes.length,+ sha256: createHash("sha256").update(bytes).digest("hex"),+ },+ };+};++const writeSource = async (+ root: string,+ id: string,+ bytes: Buffer,+): Promise<void> => {+ await writeFile(join(root, `${id}.source`), bytes, {+ flag: "wx",+ mode: 0o600,+ });+};++const startServer = async (+ root: string,+): Promise<{+ readonly process: ChildProcessWithoutNullStreams;+ readonly next: () => Promise<WebBundleWorkerMessage>;+}> => {+ const loader = import.meta.resolve("tsx");+ const serverUrl = new URL(+ "./WebBundleAnalysisWorkerServer.ts",+ import.meta.url,+ ).href;+ const analyzerUrl = new URL("../domain/webBundleAnalyzer.ts", import.meta.url)+ .href;+ const program = `+ const { serveWebBundleAnalysisWorker } = await import(${JSON.stringify(serverUrl)});+ const { analyzeCapturedWebScript } = await import(${JSON.stringify(analyzerUrl)});+ await serveWebBundleAnalysisWorker(analyzeCapturedWebScript);+ `;+ const child = spawn(+ process.execPath,+ [+ "--max-old-space-size=128",+ "--import",+ loader,+ "--input-type=module",+ "-e",+ program,+ ],+ { cwd: root, stdio: ["pipe", "pipe", "pipe"] },+ );+ const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });+ const iterator = lines[Symbol.asyncIterator]();+ return {+ process: child,+ next: async () => {+ const line = await iterator.next();+ if (line.done) {+ const stderr = await readStream(child.stderr);+ throw new Error(`Worker exited before a control frame: ${stderr}`);+ }+ const raw: unknown = JSON.parse(line.value);+ return webBundleWorkerMessageSchema.parse(raw);+ },+ };+};++const readStream = async (stream: NodeJS.ReadableStream): Promise<string> => {+ let output = "";+ for await (const chunk of stream) output += String(chunk);+ return output;+};++const send = async (+ worker: ChildProcessWithoutNullStreams,+ request: unknown,+): Promise<void> => {+ const frame = `${JSON.stringify(request)}\n`;+ await new Promise<void>((resolve, reject) => {+ worker.stdin.write(frame, (error) =>+ error === null || error === undefined ? resolve() : reject(error),+ );+ });+};++it("bounds and binds per-script worker jobs, then reuses one worker for the next script", async () => {+ const root = await mkdtemp(join(tmpdir(), "rea-web-worker-server-test-"));+ let worker: ChildProcessWithoutNullStreams | undefined;+ try {+ const server = await startServer(root);+ worker = server.process;+ const ready = await server.next();+ expect(ready).toMatchObject({ kind: "ready" });+ if (ready.kind !== "ready") throw new Error("Expected worker ready frame");+ expect(ready.heap_limit_bytes).not.toBeNull();+ expect(ready.heap_limit_bytes).toBeLessThan(512 * 1024 * 1024);+ expect(WEB_BUNDLE_WORKER_LIMITS).toMatchObject({+ protocolBytes: 64 * 1024,+ sourceBytes: 8 * 32 * 1024 * 1024,+ resultBytes: 8 * 1024 * 1024,+ });++ const script = makeScript("fetch('/users');");+ const input = sourceDescriptor(script);+ const missingId = randomUUID();+ await writeSource(root, randomUUID(), input.bytes);+ await send(worker, {+ kind: "analyze",+ id: missingId,+ source: input.descriptor,+ result_budget_bytes: WEB_BUNDLE_WORKER_LIMITS.resultBytes,+ });+ const missing = await server.next();+ expect(missing).toMatchObject({+ kind: "failure",+ id: missingId,+ reason: "io",+ });++ const digestId = randomUUID();+ await writeSource(root, digestId, input.bytes);+ await send(worker, {+ kind: "analyze",+ id: digestId,+ source: { ...input.descriptor, sha256: "0".repeat(64) },+ result_budget_bytes: WEB_BUNDLE_WORKER_LIMITS.resultBytes,+ });+ expect(await server.next()).toMatchObject({+ kind: "failure",+ id: digestId,+ reason: "input",+ });++ const budgetId = randomUUID();+ await writeSource(root, budgetId, input.bytes);+ await send(worker, {+ kind: "analyze",+ id: budgetId,+ source: input.descriptor,+ result_budget_bytes: 1,+ });+ expect(await server.next()).toMatchObject({+ kind: "phase",+ id: budgetId,+ phase: "analyze",+ });+ expect(await server.next()).toMatchObject({+ kind: "failure",+ id: budgetId,+ reason: "resource",+ });++ const nextScript = makeScript("fetch('/orders');");+ const nextInput = sourceDescriptor(nextScript);+ const nextId = randomUUID();+ await writeSource(root, nextId, nextInput.bytes);+ await send(worker, {+ kind: "analyze",+ id: nextId,+ source: nextInput.descriptor,+ result_budget_bytes: WEB_BUNDLE_WORKER_LIMITS.resultBytes,+ });+ expect(await server.next()).toMatchObject({+ kind: "phase",+ id: nextId,+ phase: "analyze",+ });+ const complete = await server.next();+ expect(complete).toMatchObject({ kind: "complete", id: nextId });+ if (complete.kind !== "complete")+ throw new Error("Expected result descriptor");+ const result = await readFile(join(root, `${nextId}.result`));+ expect(result.length).toBe(complete.result.bytes);+ expect(createHash("sha256").update(result).digest("hex")).toBe(+ complete.result.sha256,+ );+ expect(JSON.parse(result.toString("utf8"))).toMatchObject({+ status: "analyzed",+ script_key: nextScript.script_key,+ });+ } finally {+ if (worker !== undefined) {+ worker.stdin.end();+ if (worker.exitCode === null && worker.signalCode === null) {+ const exited = once(worker, "exit");+ const timeout = setTimeout(() => worker?.kill("SIGKILL"), 2_000);+ await exited;+ clearTimeout(timeout);+ }+ }+ await rm(root, { recursive: true, force: true });+ }+});diff --git a/src/browser/WebBundleAnalysisWorkerServer.ts b/src/browser/WebBundleAnalysisWorkerServer.tsnew file mode 100644index 000000000..4c3e701c8--- /dev/null+++ b/src/browser/WebBundleAnalysisWorkerServer.ts@@ -0,0 +1,235 @@+import { createHash } from "node:crypto";+import { open } from "node:fs/promises";+import { join } from "node:path";+import { StringDecoder } from "node:string_decoder";+import { getHeapStatistics } from "node:v8";+import { withArtifactFileHandle } from "../artifacts/ArtifactFileOperation.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { jsonParts } from "../domain/jsonSerialization.js";+import type { IncludedScript } from "../domain/webBundleAnalyzerInspection.js";+import {+ webBundleScriptAnalysisSchema,+ type WebBundleScriptAnalysis,+} from "../domain/webBundleScriptAnalysis.js";+import { javaScriptRuntime } from "../domain/runtimeVersion.js";+import { readStableArtifact } from "../artifacts/readStableArtifact.js";+import {+ WEB_BUNDLE_WORKER_LIMITS as LIMITS,+ includedWebScriptSchema,+ webBundleWorkerRequestSchema,+ webBundleWorkerMessageSchema,+ type WebBundleWorkerMessage,+} from "./WebBundleAnalysisWorkerProtocol.js";++export interface WebBundleScriptAnalyzer {+ (script: IncludedScript): WebBundleScriptAnalysis;+}++class WebBundleWorkerInputError extends Error {}+class WebBundleWorkerOutputError extends Error {}++const send = async (input: WebBundleWorkerMessage): Promise<void> => {+ const value = webBundleWorkerMessageSchema.parse(input);+ const frame = `${JSON.stringify(value)}\n`;+ if (Buffer.byteLength(frame) > LIMITS.protocolBytes)+ throw new RangeError(+ "Web bundle worker control frame exceeds its byte budget",+ );+ await new Promise<void>((resolve, reject) => {+ process.stdout.write(frame, (error) =>+ error === null || error === undefined ? resolve() : reject(error),+ );+ });+};++async function* boundedControlLines(): AsyncGenerator<string> {+ const decoder = new StringDecoder("utf8");+ let pending = "";+ for await (const chunk of process.stdin) {+ const decoded = decoder.write(chunk);+ let start = 0;+ for (;;) {+ const newline = decoded.indexOf("\n", start);+ if (newline < 0) {+ pending += decoded.slice(start);+ if (Buffer.byteLength(pending) > LIMITS.protocolBytes)+ throw new RangeError(+ "Web bundle worker request exceeds its byte budget",+ );+ break;+ }+ const line = `${pending}${decoded.slice(start, newline)}`.replace(+ /\r$/u,+ "",+ );+ pending = "";+ if (Buffer.byteLength(line) > LIMITS.protocolBytes)+ throw new RangeError(+ "Web bundle worker request exceeds its byte budget",+ );+ yield line;+ start = newline + 1;+ }+ }+ pending += decoder.end();+ if (pending !== "") {+ if (Buffer.byteLength(pending) > LIMITS.protocolBytes)+ throw new RangeError("Web bundle worker request exceeds its byte budget");+ yield pending;+ }+}++/** Serve sequential script jobs from the private root owned by the worker runtime. */+export const serveWebBundleAnalysisWorker = async (+ analyze: WebBundleScriptAnalyzer,+): Promise<void> => {+ const root = process.cwd();+ const resources = new ArtifactResourceScope();+ const requests = boundedControlLines();+ await send({+ kind: "ready",+ heap_limit_bytes:+ javaScriptRuntime(process.versions).id === "node"+ ? getHeapStatistics().heap_size_limit+ : null,+ });+ try {+ for (;;) {+ const next = await requests.next();+ if (next.done) break;+ if (Buffer.byteLength(next.value) > LIMITS.protocolBytes)+ throw new RangeError(+ "Web bundle worker request exceeds its byte budget",+ );+ const raw: unknown = JSON.parse(next.value);+ const request = webBundleWorkerRequestSchema.parse(raw);+ const continueServing = await analyzeJob(+ root,+ request,+ analyze,+ resources,+ );+ if (!continueServing) break;+ if (+ process.memoryUsage().heapUsed >+ getHeapStatistics().heap_size_limit / 2+ )+ global.gc?.();+ }+ } finally {+ await requests.return(undefined);+ }+};++const analyzeJob = async (+ root: string,+ request: ReturnType<typeof webBundleWorkerRequestSchema.parse>,+ analyze: WebBundleScriptAnalyzer,+ resources: ArtifactResourceScope,+): Promise<boolean> => {+ try {+ const sourcePath = join(root, `${request.id}.source`);+ const source = await readStableArtifact(+ sourcePath,+ LIMITS.sourceBytes,+ undefined,+ undefined,+ resources,+ );+ if (+ source.bytes.length !== request.source.bytes ||+ source.sha256 !== request.source.sha256+ )+ throw new WebBundleWorkerInputError(+ "Web bundle worker source descriptor does not match its file",+ );+ let script: IncludedScript;+ try {+ const decoded: unknown = JSON.parse(+ new TextDecoder("utf-8", { fatal: true }).decode(source.bytes),+ );+ script = includedWebScriptSchema.parse(decoded);+ } catch (cause) {+ throw new WebBundleWorkerInputError(+ `Web bundle worker source is not a valid included script: ${cause instanceof Error ? cause.message : String(cause)}`,+ );+ }+ await send({ kind: "phase", id: request.id, phase: "analyze" });+ let result: WebBundleScriptAnalysis;+ try {+ result = webBundleScriptAnalysisSchema.parse(analyze(script));+ } catch (cause) {+ throw new WebBundleWorkerOutputError(+ `Web bundle analyzer returned an invalid result: ${cause instanceof Error ? cause.message : String(cause)}`,+ );+ }+ if (result.status !== "analyzed")+ throw new WebBundleWorkerOutputError(+ "Web bundle analyzer did not produce a completed per-script result",+ );+ const resultPath = join(root, `${request.id}.result`);+ const file = await open(resultPath, "wx", 0o600);+ const hash = createHash("sha256");+ let bytes = 0;+ await withArtifactFileHandle(+ resultPath,+ file,+ resources,+ undefined,+ async (handle) => {+ for (const part of jsonParts(result)) {+ const chunk = Buffer.from(part);+ bytes += chunk.length;+ if (bytes > request.result_budget_bytes)+ throw new RangeError(+ "Web bundle worker result exceeds its admitted byte budget",+ );+ hash.update(chunk);+ let offset = 0;+ while (offset < chunk.length) {+ const written = await handle.write(+ chunk,+ offset,+ chunk.length - offset,+ );+ if (written.bytesWritten === 0)+ throw new Error(+ "Web bundle worker result write made no progress",+ );+ offset += written.bytesWritten;+ }+ }+ },+ );+ await send({+ kind: "complete",+ id: request.id,+ result: { bytes, sha256: hash.digest("hex") },+ });+ return true;+ } catch (cause: unknown) {+ const resource = cause instanceof RangeError;+ const input = cause instanceof WebBundleWorkerInputError;+ const fatalCleanupFailure =+ cause instanceof ArtifactReaderFailure &&+ cause.cleanupLeases !== undefined &&+ cause.cleanupLeases.length > 0;+ const rawMessage = cause instanceof Error ? cause.message : String(cause);+ await send({+ kind: "failure",+ id: request.id,+ reason: resource+ ? "resource"+ : input+ ? "input"+ : cause instanceof WebBundleWorkerOutputError ||+ cause instanceof TypeError+ ? "output"+ : "io",+ message:+ rawMessage.length > 2048 ? `${rawMessage.slice(0, 2048)}…` : rawMessage,+ });+ return !fatalCleanupFailure;+ }+};diff --git a/src/cli/browserCommands.ts b/src/cli/browserCommands.tsindex cd4cde56e..5585218a6 100644--- a/src/cli/browserCommands.ts+++ b/src/cli/browserCommands.ts@@ -158,6 +158,10 @@ const registerBundleAnalysis = (.boolean().default(false).describe("Fetch source maps referenced by captured scripts"),+ maxHeapMb: analyzeWebBundleInputSchema.shape.max_heap_mb,+ analysisTimeoutMs: analyzeWebBundleInputSchema.shape.analysis_timeout_ms,+ totalAnalysisTimeoutMs:+ analyzeWebBundleInputSchema.shape.total_analysis_timeout_ms,}),run: ({ args, options }) =>withCommandCancellation((signal) =>@@ -170,6 +174,15 @@ const registerBundleAnalysis = (observation_ms: options.observationMs,include_script_sources: true,fetch_source_maps: options.fetchSourceMaps,+ ...(options.maxHeapMb === undefined+ ? {}+ : { max_heap_mb: options.maxHeapMb }),+ ...(options.analysisTimeoutMs === undefined+ ? {}+ : { analysis_timeout_ms: options.analysisTimeoutMs }),+ ...(options.totalAnalysisTimeoutMs === undefined+ ? {}+ : { total_analysis_timeout_ms: options.totalAnalysisTimeoutMs }),};const parsed = analyzeWebBundleInputSchema.safeParse(input);if (!parsed.success)diff --git a/src/composition/webBundleAnalysisWorkerProcess.ts b/src/composition/webBundleAnalysisWorkerProcess.tsnew file mode 100644index 000000000..967bd623f--- /dev/null+++ b/src/composition/webBundleAnalysisWorkerProcess.ts@@ -0,0 +1,17 @@+import { analyzeCapturedWebScript } from "../domain/webBundleAnalyzer.js";+import {+ serveWebBundleAnalysisWorker,+ type WebBundleScriptAnalyzer,+} from "../browser/WebBundleAnalysisWorkerServer.js";++const analyze: WebBundleScriptAnalyzer = (script) =>+ analyzeCapturedWebScript(script);++try {+ await serveWebBundleAnalysisWorker(analyze);+} catch (cause: unknown) {+ process.stderr.write(+ `${cause instanceof Error ? cause.message : String(cause)}\n`,+ );+ process.exitCode = 1;+}diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.tsindex 85312d777..8105a574e 100644--- a/src/domain/analysisErrorBase.ts+++ b/src/domain/analysisErrorBase.ts@@ -231,6 +231,7 @@ import type {RecordedCrashPartialObservation,} from "./native/recordedCrash.js";import type { WebPageInspection } from "./browserObservationSchemas.js";+import type { WebBundleAnalysis } from "./webBundleAnalysis.js";import type { WebExecution } from "./webExecution.js";import type { WebEventListeners } from "./webEventListeners.js";@@ -252,6 +253,7 @@ export type AnalysisPartialObservation =| ElectronActivePartialObservation| BrowserScenarioPartialObservation| WebPageInspection+ | WebBundleAnalysis| WebExecution| WebEventListeners| JavaScriptRuntimeObservationdiff --git a/src/domain/webBundleAnalysis.ts b/src/domain/webBundleAnalysis.tsindex b4e4c11f8..4eef3cf94 100644--- a/src/domain/webBundleAnalysis.ts+++ b/src/domain/webBundleAnalysis.ts@@ -8,6 +8,33 @@ import { webTextArtifactSchema } from "./webContentArtifact.js";export const analyzeWebBundleInputSchema =inspectWebPageWithSourceInputSchema.safeExtend({fetch_source_maps: z.boolean().default(false),+ max_heap_mb: z+ .number()+ .int()+ .min(128)+ .max(16_384)+ .optional()+ .describe(+ "Maximum V8 old-space heap in MiB for the isolated inert-script analyzer; defaults to 1024. This is not a total process RSS limit. Bun ignores V8 flags; Windows Bun uses an owned process commit limit plus a 512 MiB runtime reserve, while other Bun hosts have no enforced memory limit.",+ ),+ analysis_timeout_ms: z+ .number()+ .int()+ .min(1)+ .max(2_147_483_647)+ .optional()+ .describe(+ "Maximum startup, analysis and result transfer time per captured script, in milliseconds; defaults to 30000. Timed-out scripts are explicit unknowns and other scripts may still be analyzed.",+ ),+ total_analysis_timeout_ms: z+ .number()+ .int()+ .min(1)+ .max(2_147_483_647)+ .optional()+ .describe(+ "Maximum time for all captured-script analysis, in milliseconds; defaults to 300000. Capture and optional source-map fetching have separate budgets. Unstarted scripts remain explicit unknowns.",+ ),});export type AnalyzeWebBundleInput = z.infer<typeof analyzeWebBundleInputSchema>;diff --git a/src/domain/webBundleAnalyzer.test.ts b/src/domain/webBundleAnalyzer.test.tsindex 291978c50..c1ad169ff 100644--- a/src/domain/webBundleAnalyzer.test.ts+++ b/src/domain/webBundleAnalyzer.test.ts@@ -2,8 +2,14 @@ import { describe, expect, it } from "vitest";import { webPageInspectionSchema } from "./browserObservationSchemas.js";import { analyzeJavaScriptStaticSource } from "./javascript/javascriptStaticAnalysis.js";-import { analyzeCapturedWebBundle } from "./webBundleAnalyzer.js";+import {+ analyzeCapturedWebBundle,+ analyzeCapturedWebScript,+} from "./webBundleAnalyzer.js";+import { buildCapturedWebBundleAnalysis } from "./webBundleAnalyzerResult.js";import { webBundleAnalysisSchema } from "./webBundleAnalysis.js";+import { isIncludedScript } from "./webBundleAnalyzerInspection.js";+import { webBundleScriptAnalysisSchema } from "./webBundleScriptAnalysis.js";import { createWebTextArtifact } from "./webContentArtifact.js";const origin = "https://app.example.test";@@ -1019,6 +1025,364 @@ const inspection = (source: string) =>limitations: [],});+describe("per-script web bundle analysis", () => {+ it("keeps parser failures as analyzed outcomes with their own coverage", () => {+ const captured = inspection("function broken( {");+ const script = captured.scripts.items.find(isIncludedScript);+ if (script === undefined)+ throw new Error("Missing included script fixture");++ expect(analyzeCapturedWebScript(script)).toMatchObject({+ status: "analyzed",+ script_key: script.script_key,+ parse_status: "failed",+ visited_ast_nodes: 0,+ observations: {+ edges: [],+ routes: [],+ endpoints: [],+ webmcp_declarations: [],+ },+ });+ });++ it("merges out-of-order worker outcomes in capture order and preserves exact unavailable keys", () => {+ const firstCapture = inspection("import './first.js'; fetch('/first');");+ const secondCapture = inspection("import './second.js'; fetch('/second');");+ const first = firstCapture.scripts.items.find(isIncludedScript);+ const second = secondCapture.scripts.items.find(isIncludedScript);+ if (first === undefined || second === undefined)+ throw new Error("Missing included script fixtures");+ const captured = firstCapture;+ captured.scripts.items.push({ ...second, script_key: "second-script" });+ captured.scripts.total += 1;++ const result = buildCapturedWebBundleAnalysis(+ captured,+ {+ status: "not_requested",+ requested: 0,+ processed: 0,+ items: [],+ },+ [+ {+ status: "unavailable",+ script_key: "second-script",+ reason: "deadline",+ detail: "Worker deadline expired.",+ },+ analyzeCapturedWebScript(first),+ ],+ );++ expect(+ result.observations.chunks.edges.map(({ specifier }) => specifier),+ ).toEqual(["./first.js"]);+ expect(result.observations.endpoints.map(({ value }) => value)).toEqual([+ "/first",+ ]);+ expect(result.unknowns).toContainEqual({+ dimension: "javascript_analysis",+ reason: expect.stringContaining("deadline"),+ affected_script_keys: ["second-script"],+ });+ expect(result.completeness).toMatchObject({+ status: "partial",+ parsed_scripts: 1,+ parse_failures: 0,+ });+ });++ it("does not count explicitly unstarted scripts as submitted and reports source budget omissions", () => {+ const captured = inspection("fetch('/started');");+ const script = captured.scripts.items.find(isIncludedScript);+ if (script === undefined)+ throw new Error("Missing included script fixture");+ const later = { ...script, script_key: "not-started-script" };+ captured.scripts.items.push(later);+ captured.scripts.total += 1;+ captured.completeness.excluded.push({+ section: "script_sources",+ reason: "resource_budget_exhausted",+ count: 2,+ });++ const result = buildCapturedWebBundleAnalysis(+ captured,+ {+ status: "not_requested",+ requested: 0,+ processed: 0,+ items: [],+ },+ [+ analyzeCapturedWebScript(script),+ {+ status: "unavailable",+ script_key: "not-started-script",+ reason: "not_started",+ },+ ],+ );++ expect(result.capture.scripts_analyzed).toBe(1);+ expect(result.completeness.status).toBe("partial");+ expect(result.unknowns).toContainEqual({+ dimension: "script_source",+ reason: expect.stringContaining("omitted 2 script source artifacts"),+ affected_script_keys: [],+ });+ expect(result.unknowns).toContainEqual({+ dimension: "javascript_analysis",+ reason: expect.stringContaining("not_started"),+ affected_script_keys: ["not-started-script"],+ });+ });+});++describe("unavailable web bundle analysis outcomes", () => {+ it("preserves distinct unavailable reasons and details with their exact script keys", () => {+ const captured = inspection("fetch('/started');");+ const first = captured.scripts.items.find(isIncludedScript);+ if (first === undefined) throw new Error("Missing included script fixture");+ const keys = ["deadline-second", "deadline-different", "resource-failure"];+ for (const script_key of keys)+ captured.scripts.items.push({ ...first, script_key });+ captured.scripts.total += keys.length;++ const result = buildCapturedWebBundleAnalysis(+ captured,+ {+ status: "not_requested",+ requested: 0,+ processed: 0,+ items: [],+ },+ [+ {+ status: "unavailable",+ script_key: first.script_key,+ reason: "not_started",+ detail: "Total analysis deadline expired after 50 ms.",+ },+ {+ status: "unavailable",+ script_key: "deadline-second",+ reason: "not_started",+ detail: "Total analysis deadline expired after 50 ms.",+ },+ {+ status: "unavailable",+ script_key: "deadline-different",+ reason: "deadline",+ detail: "Per-script deadline expired after 10 ms.",+ },+ {+ status: "unavailable",+ script_key: "resource-failure",+ reason: "resource_constraint",+ detail: "Worker result exceeded its byte budget.",+ },+ ],+ );++ expect(+ result.unknowns.filter(+ ({ dimension }) => dimension === "javascript_analysis",+ ),+ ).toEqual([+ {+ dimension: "javascript_analysis",+ reason:+ 'Analysis was unavailable for captured scripts (not_started); findings from those scripts are unknown. Worker detail: "Total analysis deadline expired after 50 ms."',+ affected_script_keys: [first.script_key, "deadline-second"],+ },+ {+ dimension: "javascript_analysis",+ reason:+ 'Analysis was unavailable for captured scripts (deadline); findings from those scripts are unknown. Worker detail: "Per-script deadline expired after 10 ms."',+ affected_script_keys: ["deadline-different"],+ },+ {+ dimension: "javascript_analysis",+ reason:+ 'Analysis was unavailable for captured scripts (resource_constraint); findings from those scripts are unknown. Worker detail: "Worker result exceeded its byte budget."',+ affected_script_keys: ["resource-failure"],+ },+ ]);+ });+});++it("requires every result reference to belong to its script key", () => {+ const captured = inspection(+ "import './module.js'; const routes = [{ path: '/known' }]; fetch('/api'); form.get('candidate'); document.modelContext.registerTool({ name: 'lookup' });",+ );+ const script = captured.scripts.items.find(isIncludedScript);+ if (script === undefined) throw new Error("Missing included script fixture");+ const outcome = analyzeCapturedWebScript(script);+ if (outcome.status !== "analyzed")+ throw new Error("Expected a completed script analysis fixture");+ const result = outcome;+ expect(webBundleScriptAnalysisSchema.parse(result)).toEqual(result);+ expect(result.observations.edges.length).toBeGreaterThan(0);+ expect(result.observations.routes.length).toBeGreaterThan(0);+ expect(result.observations.endpoints.length).toBeGreaterThan(0);+ expect(result.observations.webmcp_declarations.length).toBeGreaterThan(0);+ expect(result.inferences.length).toBeGreaterThan(0);++ const wrongEdgeSource = {+ ...result,+ observations: {+ ...result.observations,+ edges: result.observations.edges.map((edge, index) =>+ index === 0 ? { ...edge, from_script_key: "another-script" } : edge,+ ),+ },+ };+ const wrongEdgeLocation = {+ ...result,+ observations: {+ ...result.observations,+ edges: result.observations.edges.map((edge, index) =>+ index === 0+ ? {+ ...edge,+ location: { ...edge.location, script_key: "another-script" },+ }+ : edge,+ ),+ },+ };+ const wrongFindingLocation = {+ ...result,+ observations: {+ ...result.observations,+ endpoints: result.observations.endpoints.map((finding, index) =>+ index === 0+ ? {+ ...finding,+ location: {+ ...finding.location,+ script_key: "another-script",+ },+ }+ : finding,+ ),+ },+ };+ const wrongRouteLocation = {+ ...result,+ observations: {+ ...result.observations,+ routes: result.observations.routes.map((finding, index) =>+ index === 0+ ? {+ ...finding,+ location: {+ ...finding.location,+ script_key: "another-script",+ },+ }+ : finding,+ ),+ },+ };+ const wrongWebMcpLocation = {+ ...result,+ observations: {+ ...result.observations,+ webmcp_declarations: result.observations.webmcp_declarations.map(+ (declaration, index) =>+ index === 0+ ? {+ ...declaration,+ location: {+ ...declaration.location,+ script_key: "another-script",+ },+ }+ : declaration,+ ),+ },+ };+ const wrongInferenceBasis = {+ ...result,+ inferences: result.inferences.map((inference, inferenceIndex) =>+ inferenceIndex === 0+ ? {+ ...inference,+ basis: inference.basis.map((basis, basisIndex) =>+ basisIndex === 0+ ? { ...basis, script_key: "another-script" }+ : basis,+ ),+ }+ : inference,+ ),+ };++ expect(webBundleScriptAnalysisSchema.safeParse(wrongEdgeSource).success).toBe(+ false,+ );+ expect(+ webBundleScriptAnalysisSchema.safeParse(wrongEdgeLocation).success,+ ).toBe(false);+ expect(+ webBundleScriptAnalysisSchema.safeParse(wrongFindingLocation).success,+ ).toBe(false);+ expect(+ webBundleScriptAnalysisSchema.safeParse(wrongRouteLocation).success,+ ).toBe(false);+ expect(+ webBundleScriptAnalysisSchema.safeParse(wrongWebMcpLocation).success,+ ).toBe(false);+ expect(+ webBundleScriptAnalysisSchema.safeParse(wrongInferenceBasis).success,+ ).toBe(false);+});++it("rejects a failed parse that claims visited nodes or derived facts", () => {+ const malformed =+ inspection("function broken( {").scripts.items.find(isIncludedScript);+ const valid =+ inspection("fetch('/api');").scripts.items.find(isIncludedScript);+ if (malformed === undefined || valid === undefined)+ throw new Error("Missing parse result fixtures");+ const failedOutcome = analyzeCapturedWebScript(malformed);+ const parsedOutcome = analyzeCapturedWebScript(valid);+ if (+ failedOutcome.status !== "analyzed" ||+ parsedOutcome.status !== "analyzed"+ )+ throw new Error("Expected completed script analysis fixtures");+ const failed = failedOutcome;+ const parsed = parsedOutcome;++ expect(webBundleScriptAnalysisSchema.parse(failed)).toEqual(failed);+ expect(+ webBundleScriptAnalysisSchema.safeParse({+ ...failed,+ visited_ast_nodes: 1,+ }).success,+ ).toBe(false);+ expect(+ webBundleScriptAnalysisSchema.safeParse({+ ...failed,+ widened_return_references: true,+ }).success,+ ).toBe(false);+ expect(+ webBundleScriptAnalysisSchema.safeParse({+ ...failed,+ observations: {+ ...failed.observations,+ endpoints: parsed.observations.endpoints,+ },+ }).success,+ ).toBe(false);+});+it("recognizes expression-free template literals as route properties", () => {const result = analyzeCapturedWebBundle(inspection(`diff --git a/src/domain/webBundleAnalyzer.ts b/src/domain/webBundleAnalyzer.tsindex ddc4dc80d..2fa6cc4f2 100644--- a/src/domain/webBundleAnalyzer.ts+++ b/src/domain/webBundleAnalyzer.ts@@ -3,9 +3,38 @@ import {analyzeScript,emptyAccumulator,isIncludedScript,+ type IncludedScript,} from "./webBundleAnalyzerInspection.js";-import { buildWebBundleAnalysis } from "./webBundleAnalyzerResult.js";+import { buildCapturedWebBundleAnalysis } from "./webBundleAnalyzerResult.js";import type { WebBundleAnalysis } from "./webBundleAnalysis.js";+import {+ webBundleScriptAnalysisSchema,+ type WebBundleScriptAnalysis,+} from "./webBundleScriptAnalysis.js";++/** Analyze one selected captured script without executing its source. */+export const analyzeCapturedWebScript = (+ script: IncludedScript,+): WebBundleScriptAnalysis => {+ const accumulator = emptyAccumulator();+ analyzeScript(script, accumulator);+ const failed = accumulator.failedScripts.length > 0;+ const recovered = accumulator.recoveredScripts.length > 0;+ return webBundleScriptAnalysisSchema.parse({+ status: "analyzed",+ script_key: script.script_key,+ parse_status: failed ? "failed" : recovered ? "recovered" : "parsed",+ visited_ast_nodes: accumulator.visitedNodes,+ widened_return_references: accumulator.widenedScripts.length > 0,+ observations: {+ edges: accumulator.edges,+ routes: accumulator.routes,+ endpoints: accumulator.endpoints,+ webmcp_declarations: accumulator.webMcp,+ },+ inferences: accumulator.inferences,+ });+};/** Analyze selected captured JavaScript source without execution. */export const analyzeCapturedWebBundle = (@@ -17,13 +46,10 @@ export const analyzeCapturedWebBundle = (items: [],},): WebBundleAnalysis => {- const accumulator = emptyAccumulator();const sourceScripts = inspection.scripts.items.filter(isIncludedScript);- for (const script of sourceScripts) analyzeScript(script, accumulator);- return buildWebBundleAnalysis(+ return buildCapturedWebBundleAnalysis(inspection,- sourceScripts,sourceMaps,- accumulator,+ sourceScripts.map(analyzeCapturedWebScript),);};diff --git a/src/domain/webBundleAnalyzerResult.ts b/src/domain/webBundleAnalyzerResult.tsindex 903f5d686..94bf162ee 100644--- a/src/domain/webBundleAnalyzerResult.ts+++ b/src/domain/webBundleAnalyzerResult.ts@@ -8,17 +8,82 @@ import type {AnalysisAccumulator,IncludedScript,} from "./webBundleAnalyzerInspection.js";+import {+ webBundleScriptAnalysisSchema,+ type WebBundleScriptAnalysis,+} from "./webBundleScriptAnalysis.js";-export const buildWebBundleAnalysis = (+export const buildCapturedWebBundleAnalysis = (inspection: WebPageInspection,- sourceScripts: IncludedScript[],sourceMaps: WebBundleAnalysis["observations"]["source_maps"],- accumulator: AnalysisAccumulator,+ rawResults: readonly WebBundleScriptAnalysis[],): WebBundleAnalysis => {+ const results = rawResults.map((result) =>+ webBundleScriptAnalysisSchema.parse(result),+ );+ const byKey = new Map<string, WebBundleScriptAnalysis>();+ for (const result of results) {+ if (byKey.has(result.script_key))+ throw new TypeError(+ `Duplicate script analysis result: ${result.script_key}`,+ );+ byKey.set(result.script_key, result);+ }+ const sourceScripts = inspection.scripts.items.filter(+ (script): script is IncludedScript => script.source.included,+ );+ const expectedKeys = new Set(+ sourceScripts.map(({ script_key }) => script_key),+ );+ for (const key of byKey.keys())+ if (!expectedKeys.has(key))+ throw new TypeError(`Unexpected script analysis result: ${key}`);+ const orderedResults: WebBundleScriptAnalysis[] = sourceScripts.map(+ (script) =>+ byKey.get(script.script_key) ?? {+ status: "unavailable",+ script_key: script.script_key,+ reason: "worker_failure",+ detail: "No analysis result was returned for this captured script.",+ },+ );+ const unavailableAnalyses = orderedResults.filter(+ (+ result,+ ): result is Extract<+ WebBundleScriptAnalysis,+ { readonly status: "unavailable" }+ > => result.status === "unavailable",+ );+ const accumulator = mergeScriptResults(+ orderedResults.filter(+ (+ result,+ ): result is Extract<+ WebBundleScriptAnalysis,+ { readonly status: "analyzed" }+ > => result.status === "analyzed",+ ),+ );+ const attemptedScripts = orderedResults.filter(+ (result) =>+ !(result.status === "unavailable" && result.reason === "not_started"),+ ).length;const unavailable = inspection.scripts.items.filter((script) => !script.source.included).map(({ script_key }) => script_key);+ const unavailableSourceReasons = [+ ...new Set(+ inspection.scripts.items.flatMap((script) =>+ script.source.included ? [] : [script.source.reason],+ ),+ ),+ ].sort();const omittedScripts = captureBudgetOmission(inspection, "scripts");+ const omittedSourceScripts = captureBudgetOmission(+ inspection,+ "script_sources",+ );const omittedSourceMaps =sourceMaps.status === "not_requested"? undefined@@ -30,11 +95,17 @@ export const buildWebBundleAnalysis = (accumulator.recoveredScripts.length > 0 ||accumulator.widenedScripts.length > 0 ||unavailable.length > 0 ||+ unavailableAnalyses.length > 0 ||sourceMapIncomplete ||omittedScripts !== undefined ||+ omittedSourceScripts !== undefined ||omittedSourceMaps !== undefined;return webBundleAnalysisSchema.parse({- capture: buildCaptureObservation(inspection, sourceScripts),+ capture: buildCaptureObservation(+ inspection,+ sourceScripts,+ attemptedScripts,+ ),observations: {chunks: {nodes: sourceScripts.map(chunkNode),@@ -48,11 +119,14 @@ export const buildWebBundleAnalysis = (inferences: accumulator.inferences,unknowns: buildUnknowns({unavailable,+ unavailableSourceReasons,failedScripts: accumulator.failedScripts,recoveredScripts: accumulator.recoveredScripts,widenedScripts: accumulator.widenedScripts,+ unavailableAnalyses,sourceMaps,omittedScripts,+ omittedSourceScripts,omittedSourceMaps,}),completeness: buildCompleteness({@@ -65,13 +139,56 @@ export const buildWebBundleAnalysis = (});};+const mergeScriptResults = (+ results: readonly Extract<+ WebBundleScriptAnalysis,+ { readonly status: "analyzed" }+ >[],+): AnalysisAccumulator => {+ const accumulator: AnalysisAccumulator = {+ edges: [],+ routes: [],+ endpoints: [],+ webMcp: [],+ inferences: [],+ seen: new Set(),+ visitedNodes: 0,+ parsedScripts: 0,+ failedScripts: [],+ recoveredScripts: [],+ widenedScripts: [],+ };+ for (const result of results) {+ accumulator.visitedNodes += result.visited_ast_nodes;+ if (result.parse_status === "failed") {+ accumulator.failedScripts.push(result.script_key);+ continue;+ }+ accumulator.parsedScripts += 1;+ if (result.parse_status === "recovered")+ accumulator.recoveredScripts.push(result.script_key);+ if (result.widened_return_references)+ accumulator.widenedScripts.push(result.script_key);+ accumulator.edges.push(...result.observations.edges);+ accumulator.routes.push(...result.observations.routes);+ accumulator.endpoints.push(...result.observations.endpoints);+ accumulator.webMcp.push(...result.observations.webmcp_declarations);+ accumulator.inferences.push(...result.inferences);+ }+ return accumulator;+};+const buildCaptureObservation = (inspection: WebPageInspection,sourceScripts: IncludedScript[],+ attemptedScripts: number,) => ({target_url: inspection.target.url,scripts_observed: inspection.scripts.total,- scripts_analyzed: sourceScripts.length,+ // This preserves the historical meaning: source scripts submitted for+ // analysis, including worker/deadline failures; explicitly unstarted suffixes+ // are excluded. Successfully parsed scripts are counted separately below.+ scripts_analyzed: attemptedScripts,source_artifacts: sourceScripts.map(sourceArtifact),});@@ -93,11 +210,17 @@ const chunkNode = (script: IncludedScript) => {interface UnknownsInput {readonly unavailable: string[];+ readonly unavailableSourceReasons: readonly string[];readonly failedScripts: readonly string[];readonly recoveredScripts: readonly string[];readonly widenedScripts: readonly string[];+ readonly unavailableAnalyses: readonly Extract<+ WebBundleScriptAnalysis,+ { readonly status: "unavailable" }+ >[];readonly sourceMaps: WebBundleAnalysis["observations"]["source_maps"];readonly omittedScripts: number | null | undefined;+ readonly omittedSourceScripts: number | null | undefined;readonly omittedSourceMaps: number | null | undefined;}@@ -111,12 +234,27 @@ const buildUnknowns = (input: UnknownsInput): WebBundleAnalysis["unknowns"] => [affected_script_keys: [],},]),+ ...(input.omittedSourceScripts === undefined+ ? []+ : [+ {+ dimension: "script_source",+ reason: captureBudgetReason(+ "script source artifacts",+ input.omittedSourceScripts,+ ),+ affected_script_keys: [],+ },+ ]),...(input.unavailable.length === 0? []: [{dimension: "script_source" as const,- reason: "Source artifact was not captured",+ reason:+ input.unavailableSourceReasons.length === 0+ ? "Source artifact was not captured"+ : `Source artifacts were not captured: ${input.unavailableSourceReasons.join("; ")}`,affected_script_keys: input.unavailable,},]),@@ -129,6 +267,15 @@ const buildUnknowns = (input: UnknownsInput): WebBundleAnalysis["unknowns"] => [affected_script_keys: [...input.failedScripts],},]),+ ...(input.unavailableAnalyses.length === 0+ ? []+ : groupUnavailableAnalyses(input.unavailableAnalyses).map(+ ({ reason, detail, affectedScriptKeys }) => ({+ dimension: "javascript_analysis" as const,+ reason: analysisUnavailableReason(reason, detail),+ affected_script_keys: affectedScriptKeys,+ }),+ )),...(input.widenedScripts.length === 0? []: [@@ -179,7 +326,7 @@ const buildUnknowns = (input: UnknownsInput): WebBundleAnalysis["unknowns"] => [const captureBudgetOmission = (inspection: WebPageInspection,- section: "scripts" | "source_maps",+ section: "scripts" | "script_sources" | "source_maps",): number | null | undefined => {const exclusions = inspection.completeness.excluded.filter((exclusion) =>@@ -191,6 +338,42 @@ const captureBudgetOmission = (return exclusions.reduce((sum, { count }) => sum + (count ?? 0), 0);};+const groupUnavailableAnalyses = (+ unavailable: UnknownsInput["unavailableAnalyses"],+): {+ readonly reason: (typeof unavailable)[number]["reason"];+ readonly detail: string | undefined;+ readonly affectedScriptKeys: string[];+}[] => {+ const groups = new Map<+ (typeof unavailable)[number]["reason"],+ Map<string | undefined, string[]>+ >();+ for (const { reason, detail, script_key } of unavailable) {+ let byDetail = groups.get(reason);+ if (byDetail === undefined) {+ byDetail = new Map();+ groups.set(reason, byDetail);+ }+ const keys = byDetail.get(detail) ?? [];+ keys.push(script_key);+ byDetail.set(detail, keys);+ }+ return [...groups].flatMap(([reason, byDetail]) =>+ [...byDetail].map(([detail, affectedScriptKeys]) => ({+ reason,+ detail,+ affectedScriptKeys,+ })),+ );+};++const analysisUnavailableReason = (+ reason: UnknownsInput["unavailableAnalyses"][number]["reason"],+ detail: string | undefined,+): string =>+ `Analysis was unavailable for captured scripts (${reason}); findings from those scripts are unknown.${detail === undefined ? "" : ` Worker detail: ${JSON.stringify(detail)}`}`;+const captureBudgetReason = (label: string, count: number | null): string =>count === null? `Capture omitted an unknown number of ${label} because its resource budget was exhausted.`diff --git a/src/domain/webBundleScriptAnalysis.ts b/src/domain/webBundleScriptAnalysis.tsnew file mode 100644index 000000000..bed846dd9--- /dev/null+++ b/src/domain/webBundleScriptAnalysis.ts@@ -0,0 +1,122 @@+import { z } from "zod";++import { webBundleAnalysisSchema } from "./webBundleAnalysis.js";++const observationsSchema = z.strictObject({+ edges: webBundleAnalysisSchema.shape.observations.shape.chunks.shape.edges,+ routes: webBundleAnalysisSchema.shape.observations.shape.routes,+ endpoints: webBundleAnalysisSchema.shape.observations.shape.endpoints,+ webmcp_declarations:+ webBundleAnalysisSchema.shape.observations.shape.webmcp_declarations,+});++/** Serializable result for one captured script, suitable for worker transport. */+export const webBundleScriptAnalysisSchema = z+ .discriminatedUnion("status", [+ z.strictObject({+ status: z.literal("analyzed"),+ script_key: z.string(),+ parse_status: z.enum(["parsed", "recovered", "failed"]),+ visited_ast_nodes: z.number().int().min(0),+ widened_return_references: z.boolean(),+ observations: observationsSchema,+ inferences: webBundleAnalysisSchema.shape.inferences,+ }),+ z.strictObject({+ status: z.literal("unavailable"),+ script_key: z.string(),+ reason: z.enum([+ "worker_failure",+ "deadline",+ "resource_constraint",+ "cancelled",+ "not_started",+ ]),+ detail: z.string().optional(),+ }),+ ])+ .superRefine((result, context) => {+ if (result.status !== "analyzed") return;++ const checkScriptKey = (+ scriptKey: string,+ path: (string | number)[],+ ): void => {+ if (scriptKey !== result.script_key)+ context.addIssue({+ code: "custom",+ path,+ message: "Per-script analysis evidence must name its owning script",+ });+ };++ result.observations.edges.forEach((edge, index) => {+ checkScriptKey(edge.from_script_key, [+ "observations",+ "edges",+ index,+ "from_script_key",+ ]);+ checkScriptKey(edge.location.script_key, [+ "observations",+ "edges",+ index,+ "location",+ "script_key",+ ]);+ });+ for (const collection of ["routes", "endpoints"] as const)+ result.observations[collection].forEach((finding, index) =>+ checkScriptKey(finding.location.script_key, [+ "observations",+ collection,+ index,+ "location",+ "script_key",+ ]),+ );+ result.observations.webmcp_declarations.forEach((declaration, index) =>+ checkScriptKey(declaration.location.script_key, [+ "observations",+ "webmcp_declarations",+ index,+ "location",+ "script_key",+ ]),+ );+ result.inferences.forEach((inference, inferenceIndex) =>+ inference.basis.forEach((basis, basisIndex) =>+ checkScriptKey(basis.script_key, [+ "inferences",+ inferenceIndex,+ "basis",+ basisIndex,+ "script_key",+ ]),+ ),+ );++ if (result.parse_status === "failed") {+ const hasFindings =+ result.observations.edges.length > 0 ||+ result.observations.routes.length > 0 ||+ result.observations.endpoints.length > 0 ||+ result.observations.webmcp_declarations.length > 0 ||+ result.inferences.length > 0;+ if (+ result.visited_ast_nodes !== 0 ||+ result.widened_return_references ||+ hasFindings+ )+ context.addIssue({+ code: "custom",+ path: ["parse_status"],+ message:+ "A failed script parse cannot carry visited nodes or derived findings",+ });+ }+ });++export type WebBundleScriptAnalysis = z.infer<+ typeof webBundleScriptAnalysisSchema+>;diff --git a/src/process/OwnedWorkerRuntime.test.ts b/src/process/OwnedWorkerRuntime.test.tsindex 4f8eeb311..6b9f67a22 100644--- a/src/process/OwnedWorkerRuntime.test.ts+++ b/src/process/OwnedWorkerRuntime.test.ts@@ -243,3 +243,101 @@ it("binds a late cleanup projection to its released root epoch after runtime reuawait runtime.close();}});++it("routes shared cleanup retry through the registered higher-level owner", async () => {+ let failCleanup = true;+ let allowOwnerClose = false;+ let delegateCalls = 0;+ let runtime: OwnedWorkerRuntime;+ runtime = new OwnedWorkerRuntime(+ runtimeOptions({+ launcher: async (options) => {+ const spawned = await spawnOwnedProviderProcess(options);+ return {+ ...spawned,+ cleanup: async () => {+ if (failCleanup)+ return { cleaned: false, reason: "controlled delegated cleanup" };+ return spawned.cleanup === undefined+ ? cleanupOwnedProcessGroup(spawned.ownership)+ : spawned.cleanup();+ },+ };+ },+ retryCleanup: async () => {+ delegateCalls += 1;+ if (!allowOwnerClose)+ throw new Error("higher-level owner still retains a descriptor");+ await runtime.close();+ },+ }),+ );+ await runtime.start(startOptions());+ const rootPath = runtime.rootPath;+ try {+ await expect(runtime.stop()).resolves.toMatchObject({+ status: "incomplete",+ });+ await expect(OwnedWorkerRuntime.retryPending()).rejects.toThrow(+ "higher-level owner still retains a descriptor",+ );+ expect(delegateCalls).toBe(1);+ // A retained supervisor is not permission to bypass its dependent owner.+ await expect(runtime.start(startOptions())).rejects.toThrow(+ "higher-level owner still retains a descriptor",+ );+ expect(delegateCalls).toBe(2);+ expect(runtime.rootPath).toBe(rootPath);+ await access(rootPath as string);++ allowOwnerClose = true;+ failCleanup = false;+ await OwnedWorkerRuntime.retryPending();++ expect(delegateCalls).toBe(3);+ expect(runtime.rootPath).toBeUndefined();+ await expect(access(rootPath as string)).rejects.toThrow();+ } finally {+ allowOwnerClose = true;+ failCleanup = false;+ await runtime.close();+ }+});++it("runs deferred delegated cleanup before registering a pending start acquisition", async () => {+ let runtime: OwnedWorkerRuntime;+ let delegatedClose: Promise<void> | undefined;+ let delegateTimedOut = false;+ runtime = new OwnedWorkerRuntime(+ runtimeOptions({+ retryCleanup: async () => {+ await new Promise<void>((resolve) => setImmediate(resolve));+ delegatedClose = runtime.close();+ let timer: NodeJS.Timeout | undefined;+ const outcome = await Promise.race([+ delegatedClose.then(() => "closed" as const),+ new Promise<"timeout">((resolve) => {+ timer = setTimeout(() => resolve("timeout"), 250);+ }),+ ]);+ if (timer !== undefined) clearTimeout(timer);+ delegateTimedOut = outcome === "timeout";+ },+ }),+ );+ try {+ await runtime.start(startOptions());+ const stopped = await runtime.stop();+ expect(stopped.status).not.toBe("incomplete");+ runtime.retainForCleanup();++ await expect(runtime.start(startOptions())).rejects.toThrow(+ "Owned worker runtime is closing",+ );+ expect(delegateTimedOut).toBe(false);+ await delegatedClose;+ expect(runtime.rootPath).toBeUndefined();+ } finally {+ await runtime.close();+ }+});diff --git a/src/process/OwnedWorkerRuntime.ts b/src/process/OwnedWorkerRuntime.tsindex 150ecc01e..cda243d40 100644--- a/src/process/OwnedWorkerRuntime.ts+++ b/src/process/OwnedWorkerRuntime.ts@@ -14,6 +14,8 @@ export interface OwnedWorkerRuntimeOptions {readonly rootPrefix: string;readonly launcher?: typeof spawnOwnedProviderProcess;readonly supervisorOptions?: ProviderProcessSupervisorOptions;+ /** Let a higher-level owner release its dependent resources before this root. */+ readonly retryCleanup?: () => Promise<void>;}export class OwnedWorkerRuntimeCleanupError extends Error {@@ -95,6 +97,7 @@ export class OwnedWorkerRuntime {#supervisor: ProviderProcessSupervisor | undefined;#processId: number | null = null;#acquisition: Promise<void> | undefined;+ #cleanupRetryAttempt: Promise<void> | undefined;#stopAttempt: Promise<ProviderProcessStopResult> | undefined;#closeAttempt: Promise<void> | undefined;#closing = false;@@ -171,7 +174,20 @@ export class OwnedWorkerRuntime {if (this.#terminalCloseRequested || this.#closing)return Promise.reject(new Error("Owned worker runtime is closing"));if (this.#acquisition !== undefined) return this.#acquisition;- if (this.#supervisor !== undefined) return Promise.resolve();+ if (+ this.#supervisor !== undefined &&+ !OwnedWorkerRuntime.#pending.has(this)+ )+ return Promise.resolve();+ if (+ this.options.retryCleanup !== undefined &&+ OwnedWorkerRuntime.#pending.has(this)+ )+ return this.#retryOwnedCleanup().then(() => {+ if (this.#terminalCloseRequested || this.#closing)+ throw new Error("Owned worker runtime is closing");+ return this.start(spawnOptions, initialize);+ });const ownRetry = OwnedWorkerRuntime.#pending.has(this)? this.#retryPending(): Promise.resolve();@@ -226,6 +242,8 @@ export class OwnedWorkerRuntime {}async #retryPending(): Promise<void> {+ if (this.options.retryCleanup !== undefined)+ return this.#retryOwnedCleanup();if (this.#terminalCloseRequested) return this.close();this.#closing = true;if (this.#closeAttempt === undefined) {@@ -251,6 +269,27 @@ export class OwnedWorkerRuntime {}}+ #retryOwnedCleanup(): Promise<void> {+ if (this.#cleanupRetryAttempt !== undefined)+ return this.#cleanupRetryAttempt;+ const attempt = Promise.resolve()+ .then(() => this.options.retryCleanup?.())+ .then(() => {+ if (OwnedWorkerRuntime.#pending.has(this))+ throw this.#cleanupError(+ "Higher-level cleanup retry returned while ownership remains pending",+ );+ });+ this.#cleanupRetryAttempt = attempt;+ void attempt+ .finally(() => {+ if (this.#cleanupRetryAttempt === attempt)+ this.#cleanupRetryAttempt = undefined;+ })+ .catch(() => undefined);+ return attempt;+ }+async #start(spawnOptions: Omit<OwnedProviderProcessSpawnOptions, "cwd">,initialize:diff --git a/tests/acceptance/browser/webBundleContainmentCli.test.ts b/tests/acceptance/browser/webBundleContainmentCli.test.tsnew file mode 100644index 000000000..59d615907--- /dev/null+++ b/tests/acceptance/browser/webBundleContainmentCli.test.ts@@ -0,0 +1,98 @@+import { expect } from "vitest";+import { z } from "zod";++import { parseEvidence } from "../../../src/domain/evidence.js";+import { startFakeCdpBrowser } from "../../fixtures/fakeCdpBrowser.js";+import { cliTest } from "../../support/cli/cliFixture.js";++const capturedSource = `+ fetch("/api/orders");+ navigator.modelContext.registerTool({+ name: "search_orders",+ description: "Search orders",+ inputSchema: {+ type: "object",+ properties: { query: { type: "string" } }+ }+ });+`;++cliTest(+ "retains an aggregate web-analysis timeout and analyzes the next CLI request",+ async ({ cli }) => {+ const browser = await startFakeCdpBrowser({+ commandResult: ({ method }) =>+ method === "Debugger.getScriptSource"+ ? { scriptSource: capturedSource }+ : undefined,+ });+ const baseArguments = [+ "analyze-web-bundle",+ browser.endpoint,+ "allowed-page",+ "--allowed-origins",+ browser.allowedOrigin,+ "--observation-ms",+ "0",+ "--json",+ ];+ try {+ const interrupted = await cli.run({+ arguments: [+ ...baseArguments,+ "--max-heap-mb",+ "128",+ "--analysis-timeout-ms",+ "1",+ "--total-analysis-timeout-ms",+ "1",+ ],+ timeoutMs: 30_000,+ });+ expect(+ interrupted.exitCode,+ interrupted.stdout + interrupted.stderr,+ ).toBe(1);+ const timeout = z+ .object({+ code: z.literal("provider_timeout"),+ details: z.object({ partial_observation: z.unknown() }),+ })+ .parse(interrupted.json);+ const partial = parseEvidence(timeout.details.partial_observation);+ expect(partial.parameters).toMatchObject({+ max_heap_mb: 128,+ analysis_timeout_ms: 1,+ total_analysis_timeout_ms: 1,+ });+ expect(partial.normalized_result).toMatchObject({+ completeness: { status: "partial", parse_failures: 0 },+ unknowns: expect.arrayContaining([+ expect.objectContaining({ affected_script_keys: expect.any(Array) }),+ ]),+ });++ const recovered = await cli.run({+ arguments: baseArguments,+ timeoutMs: 30_000,+ });+ expect(recovered.exitCode, recovered.stdout + recovered.stderr).toBe(0);+ expect(recovered.json).toMatchObject({+ normalized_result: {+ observations: {+ endpoints: [expect.objectContaining({ value: "/api/orders" })],+ webmcp_declarations: [+ expect.objectContaining({+ name: "search_orders",+ trust: "page-declared-untrusted",+ }),+ ],+ },+ },+ });+ expect(browser.activeConnectionCount()).toBe(0);+ } finally {+ await browser.close();+ }+ },+);diff --git a/tests/boundary/mcp/webBundleContainmentMcp.test.ts b/tests/boundary/mcp/webBundleContainmentMcp.test.tsnew file mode 100644index 000000000..c4367ea8f--- /dev/null+++ b/tests/boundary/mcp/webBundleContainmentMcp.test.ts@@ -0,0 +1,149 @@+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";+import { afterEach, expect, it } from "vitest";+import { z } from "zod";++import { CdpBrowserProvider } from "../../../src/browser/CdpBrowserProvider.js";+import { parseEvidence } from "../../../src/domain/evidence.js";+import { ok as resultOk } from "../../../src/domain/result.js";+import { toolContract } from "../../../src/contracts/toolContracts.js";+import { createServer } from "../../../src/server/createServer.js";+import { createTestBinarySession } from "../../fixtures/binarySession.js";+import { observed } from "../../fixtures/analysisExecution.js";+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";+import { startFakeCdpBrowser } from "../../fixtures/fakeCdpBrowser.js";++const capturedSource = `+ fetch("/api/orders");+ navigator.modelContext.registerTool({+ name: "search_orders",+ description: "Search orders",+ inputSchema: {+ type: "object",+ properties: { query: { type: "string" } }+ }+ });+`;++const resources: Array<{ close(): Promise<unknown> }> = [];+const browsers: Array<{ close(): Promise<unknown> }> = [];++afterEach(async () => {+ await Promise.all(resources.splice(0).map((resource) => resource.close()));+ await Promise.all(browsers.splice(0).map((browser) => browser.close()));+});++it("retains timeout Evidence and recovers on the same MCP server", async () => {+ const browser = await startFakeCdpBrowser({+ commandResult: ({ method }) =>+ method === "Debugger.getScriptSource"+ ? { scriptSource: capturedSource }+ : undefined,+ });+ browsers.push(browser);+ const session = createTestBinarySession(() => ({+ execute: () => Promise.resolve(observed(null)),+ close: () => Promise.resolve(resultOk(null)),+ }));+ const server = createServer(+ { kind: "session", session },+ {+ browserObservation: new CdpBrowserProvider(),+ availabilityPolicy: () => ({+ processCaptureEnabled: false,+ investigationInputRoots: 0,+ }),+ },+ );+ const client = new Client({+ name: "web-bundle-containment-test",+ version: "1",+ });+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ resources.push(client, server, session);+ await server.connect(serverTransport);+ await client.connect(clientTransport);++ const interrupted = await client.callTool({+ name: "analyze_web_bundle",+ arguments: {+ cdp_endpoint: browser.endpoint,+ allowed_origins: [browser.allowedOrigin],+ target_id: "allowed-page",+ observation_ms: 0,+ max_heap_mb: 128,+ analysis_timeout_ms: 1,+ total_analysis_timeout_ms: 1,+ },+ });+ const timeout = parseMcpToolError(interrupted).error;+ expect(timeout.code).toBe("provider_timeout");+ const timeoutDetails = z+ .object({ partial_observation: z.unknown() })+ .passthrough()+ .parse(timeout.details);+ const partialReference = z+ .object({+ kind: z.literal("retained-evidence"),+ evidence_id: z.string(),+ })+ .parse(timeoutDetails.partial_observation);++ const retainedReply = await client.callTool({+ name: "get_evidence_bundle",+ arguments: {+ detail: "complete",+ },+ });+ expect(retainedReply.isError, JSON.stringify(retainedReply.content)).not.toBe(+ true,+ );+ const retainedBundle = toolContract("get_evidence_bundle").outputSchema.parse(+ retainedReply.structuredContent,+ ).result;+ if ("kind" in retainedBundle)+ throw new Error("Expected complete retained Evidence");+ const retained = parseEvidence(+ retainedBundle.records.find(+ (record) => record.evidence_id === partialReference.evidence_id,+ ),+ );+ expect(retained.evidence_id).toBe(partialReference.evidence_id);+ expect(retained.parameters).toMatchObject({+ max_heap_mb: 128,+ analysis_timeout_ms: 1,+ total_analysis_timeout_ms: 1,+ });+ expect(retained.normalized_result).toMatchObject({+ completeness: { status: "partial", parse_failures: 0 },+ unknowns: expect.arrayContaining([+ expect.objectContaining({ affected_script_keys: expect.any(Array) }),+ ]),+ });++ const recovered = await client.callTool({+ name: "analyze_web_bundle",+ arguments: {+ cdp_endpoint: browser.endpoint,+ allowed_origins: [browser.allowedOrigin],+ target_id: "allowed-page",+ observation_ms: 0,+ },+ });+ expect(recovered.isError, JSON.stringify(recovered.content)).not.toBe(true);+ expect(recovered.structuredContent).toMatchObject({+ normalized_result: {+ observations: {+ endpoints: [expect.objectContaining({ value: "/api/orders" })],+ webmcp_declarations: [+ expect.objectContaining({+ name: "search_orders",+ trust: "page-declared-untrusted",+ }),+ ],+ },+ },+ });+ await client.ping();+ expect(browser.activeConnectionCount()).toBe(0);+}, 60_000);