feat(browser): attribute native execution and listener sources (#917)

* feat(browser): attribute native execution and listener sources

Integrate finite native precise-coverage windows and direct DOM listener inspection through shared CLI/MCP workflows, exact session script identities, inline source evidence and owned instrumentation cleanup.

Refs #881, #774

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): preserve runtime identity and settle fixture cleanup

Retain complete reported initiator objects, reject changing loader availability, propagate the selected operation through main-frame authorization and complete effect/help inventories. Close only the synthetic owned Chrome via its native endpoint, await process-group settlement and preserve primary verification errors during cleanup.

Refs #881

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): settle invalid events and preserve document evidence

Accept same-document URL changes with proven stable loader identity, retain metadata without inventing ownership, terminate malformed event collection immediately, and sanitize known transport URLs without erasing sourceURL declarations.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): end detached target windows and sanitize coverage identities

Reuse the existing flat-session event matcher, retain prearming termination, and apply the source identity policy to coverage URLs. Add real MCP target-close verification and producer regressions for detachment orderings.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): retain final sample metadata and settle fatal protocol failures

Keep source inventory open through the resetting sample, propagate fatal wire failures without outstanding commands, and check listener collection failures after final document validation.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)

Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): require default execution worlds for website attribution

Preserve native context and world metadata without treating same-frame isolated or unknown contexts as website sources. Verify actual Chrome isolated function execution before excluding its coverage, and cover ambiguous world metadata with producer regressions.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)

Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): revalidate runtime source joins and selector failures

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
Ysopwnable
2026-10-07 21:45:07 +08:00
committed by GitHub
co-authored by morluto
parent ef1a0cc65a
commit b5afa5f91e
82 changed files with 5392 additions and 85 deletions
+6
View File
@@ -189,6 +189,12 @@ export const buildCapabilityInventory = (
};
const availabilityFor = (context: AvailabilityContext): Availability => {
// These built-in workflows accept a caller-selected endpoint; they do not load the optional passive provider.
if (
context.name === "observe_web_execution" ||
context.name === "inspect_web_event_listeners"
)
return { reason: "available", remediation: null };
if (context.name === "get_navigation_context")
return navigationContextAvailability(context.descriptors);
const javascriptApplication = javascriptApplicationAvailability(context);
+24
View File
@@ -0,0 +1,24 @@
import type { ExecutionOptions, ProviderIdentity } from "./AnalysisProvider.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { Result } from "../domain/result.js";
import type {
ObserveWebExecutionInput,
WebExecution,
} from "../domain/webExecution.js";
import type {
InspectWebEventListenersInput,
WebEventListeners,
} from "../domain/webEventListeners.js";
/** Provider-neutral live source attribution operations with distinct instrumentation authority. */
export interface WebRuntimePort {
identity(): ProviderIdentity;
observeExecution(
input: ObserveWebExecutionInput,
options?: ExecutionOptions,
): Promise<Result<WebExecution, AnalysisError>>;
inspectEventListeners(
input: InspectWebEventListenersInput,
options?: ExecutionOptions,
): Promise<Result<WebEventListeners, AnalysisError>>;
}
@@ -0,0 +1,90 @@
import type { WebRuntimePort } from "./WebRuntimePort.js";
import { ok } from "../domain/result.js";
import type { WebExecution } from "../domain/webExecution.js";
import type { WebEventListeners } from "../domain/webEventListeners.js";
const browser = {
product: "RecordingChrome/1",
protocol_version: "1.3",
revision: "fixture",
user_agent: "fixture",
js_version: "fixture",
};
const target = {
target_id: "selected-page",
initial_url: "http://127.0.0.1:9222/app",
origin: "http://127.0.0.1:9222",
frame_id: "main-frame",
loader_id: "fixture-document",
};
const at = "2026-01-01T00:00:00.000Z";
/** Immutable application-port result; it makes no real browser or socket claim. */
export const webExecutionFixture = (
targetId = target.target_id,
duration = 5,
): WebExecution => ({
browser,
target: { ...target, target_id: targetId },
window: {
armed_at: at,
ended_at: at,
requested_ms: duration,
end_reason: "window_elapsed",
producer_started_seconds: 1,
producer_sampled_seconds: 2,
},
coverage: {
state: "captured",
reason: null,
offset_units: "utf16-code-units",
end_offset: "exclusive",
scripts: [],
excluded_scripts: 0,
},
requests: [],
excluded_requests: 0,
sources: [],
script_inventory: {
main_document_scripts: 0,
not_reported_script_ids: [],
coverage_absence: "unknown",
},
instrumentation: {
resets_execution_counters: true,
disables_optimized_execution: true,
takes_one_resetting_sample: true,
executes_selected_code: false,
cleanup: "confirmed",
page_ownership: "external",
},
limitations: ["Recording port fixture, not real browser evidence."],
});
/** Immutable listener port result for application and SDK schema boundaries. */
export const webListenersFixture = (
targetId = target.target_id,
selector = "#selected",
): WebEventListeners => ({
browser,
target: { ...target, target_id: targetId },
inspected_at: at,
selected_node: { selector, match: "found", backend_node_id: 22 },
listeners: [],
sources: [],
cleanup: "confirmed",
limitations: ["Recording port fixture, not real listener evidence."],
});
/** Provider-neutral recording seam preserves the exact parsed caller target and window. */
export const recordingWebRuntimePort = (): WebRuntimePort => ({
identity: () => ({
id: "runtime-recording",
name: "Runtime recording fixture",
version: "1",
}),
observeExecution: async (input) =>
ok(webExecutionFixture(input.target_id, input.observation_ms)),
inspectEventListeners: async (input) =>
ok(webListenersFixture(input.target_id, input.selector)),
});
+61
View File
@@ -0,0 +1,61 @@
import { expect, it } from "vitest";
import { WebRuntimeService } from "./WebRuntimeService.js";
import {
recordingWebRuntimePort,
webListenersFixture,
} from "./WebRuntimeService.fixture.js";
import { err, ok } from "../domain/result.js";
import { AnalysisTimeoutError } from "../domain/analysisErrorCore.js";
it("rejects malformed input and prior cancellation without calling a provider", async () => {
const provider = recordingWebRuntimePort();
const service = new WebRuntimeService({
identity: () => provider.identity(),
observeExecution: () => {
throw new Error("Provider must not be called");
},
inspectEventListeners: () => {
throw new Error("Provider must not be called");
},
});
const malformed = await service.observe({
cdp_endpoint: "https://remote.example",
target_id: "page",
});
if (malformed.ok)
throw new Error("Invalid endpoint must fail before execution");
expect(malformed.error._tag).toBe("AnalysisInputError");
const cancelled = await service.inspect({}, { signal: AbortSignal.abort() });
if (cancelled.ok)
throw new Error("Prior cancellation must fail before inspection");
expect(cancelled.error._tag).toBe("AnalysisCancelledError");
});
it("preserves actual provider failures and rejects changed target/selector identities", async () => {
const provider = recordingWebRuntimePort();
const args = {
cdp_endpoint: "http://127.0.0.1:9222",
target_id: "selected-page",
selector: "#selected",
};
const captured = webListenersFixture();
const timeout = new AnalysisTimeoutError("observe_web_execution", 20_000);
const service = new WebRuntimeService({
identity: () => provider.identity(),
observeExecution: async () => err(timeout),
inspectEventListeners: async () =>
ok({
...captured,
selected_node: { ...captured.selected_node, selector: "#different" },
}),
});
const failed = await service.observe({
cdp_endpoint: args.cdp_endpoint,
target_id: args.target_id,
observation_ms: 5,
});
expect(failed).toEqual(err(timeout));
const changed = await service.inspect(args);
if (changed.ok) throw new Error("Changed selection must be rejected");
expect(changed.error._tag).toBe("AnalysisOutputError");
});
+146
View File
@@ -0,0 +1,146 @@
import { z } from "zod";
import type { ExecutionOptions } from "./AnalysisProvider.js";
import type { WebRuntimePort } from "./WebRuntimePort.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisCancelledError,
AnalysisInputError,
AnalysisOutputError,
} from "../domain/analysisErrorCore.js";
import { createEvidence, type Evidence } from "../domain/evidence.js";
import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
import { projectInputIssues } from "../domain/inputIssueProjection.js";
import { err, ok, type Result } from "../domain/result.js";
import {
observeWebExecutionInputSchema,
webExecutionSchema,
} from "../domain/webExecution.js";
import {
inspectWebEventListenersInputSchema,
webEventListenersSchema,
} from "../domain/webEventListeners.js";
/** Shared public workflows keep instrumentation and listener inspection independently selectable. */
export class WebRuntimeService {
constructor(readonly provider: WebRuntimePort) {}
/** Observe externally triggered execution; selection authorizes the declared instrumentation. */
async observe(
rawInput: unknown,
options?: ExecutionOptions,
): Promise<Result<Evidence, AnalysisError>> {
const operation = "observe_web_execution";
const parsed = parseInput(
observeWebExecutionInputSchema,
rawInput,
operation,
options,
);
if (!parsed.ok) return parsed;
const result = await this.provider.observeExecution(parsed.value, options);
if (!result.ok) return result;
const verified = webExecutionSchema.safeParse(result.value);
if (!verified.success)
return err(new AnalysisOutputError(operation, verified.error.message));
if (
verified.data.target.target_id !== parsed.value.target_id ||
verified.data.window.requested_ms !== parsed.value.observation_ms
)
return err(
new AnalysisOutputError(
operation,
"Provider changed the selected target or requested window.",
),
);
return this.evidence(operation, parsed.value, verified.data, options);
}
/** Inspect one selected node's listener declarations without dispatching an event. */
async inspect(
rawInput: unknown,
options?: ExecutionOptions,
): Promise<Result<Evidence, AnalysisError>> {
const operation = "inspect_web_event_listeners";
const parsed = parseInput(
inspectWebEventListenersInputSchema,
rawInput,
operation,
options,
);
if (!parsed.ok) return parsed;
const result = await this.provider.inspectEventListeners(
parsed.value,
options,
);
if (!result.ok) return result;
const verified = webEventListenersSchema.safeParse(result.value);
if (!verified.success)
return err(new AnalysisOutputError(operation, verified.error.message));
if (
verified.data.target.target_id !== parsed.value.target_id ||
verified.data.selected_node.selector !== parsed.value.selector
)
return err(
new AnalysisOutputError(
operation,
"Provider changed the selected target or node selector.",
),
);
return this.evidence(operation, parsed.value, verified.data, options);
}
private evidence(
operation: string,
input:
| z.infer<typeof observeWebExecutionInputSchema>
| z.infer<typeof inspectWebEventListenersInputSchema>,
result:
| z.infer<typeof webExecutionSchema>
| z.infer<typeof webEventListenersSchema>,
options?: ExecutionOptions,
): Result<Evidence, AnalysisError> {
if (options?.signal?.aborted)
return err(new AnalysisCancelledError(operation));
if (
input.allowed_origins.length > 0 &&
!input.allowed_origins.includes(result.target.origin)
)
return err(
new AnalysisOutputError(
operation,
"Provider returned a document outside the selected origin scope.",
),
);
return ok(
createEvidence(undefined, this.provider.identity(), {
predicateType: `rea.${operation.replaceAll("_", "-")}`,
operation,
parameters: jsonObjectSchema.parse(input),
result: jsonValueSchema.parse(result),
confidence: "observed",
authority: "external-service",
limitations: result.limitations,
}),
);
}
}
const parseInput = <T>(
schema: z.ZodType<T>,
rawInput: unknown,
operation: string,
options: ExecutionOptions | undefined,
): Result<T, AnalysisError> => {
if (options?.signal?.aborted)
return err(new AnalysisCancelledError(operation));
const parsed = schema.safeParse(rawInput);
return parsed.success
? ok(parsed.data)
: err(
new AnalysisInputError(
operation,
{ cause: parsed.error },
projectInputIssues(parsed.error.issues, rawInput),
),
);
};