fix(capture): retain Electron observations and HAR resource failures
This commit is contained in:
@@ -103,6 +103,8 @@ const metricSchema = z.strictObject({
|
||||
const windowMetadataSchema = z.strictObject({
|
||||
window_id: z.string(),
|
||||
web_contents_id: z.string(),
|
||||
url: z.string(),
|
||||
title: z.string(),
|
||||
visible: z.boolean().nullable(),
|
||||
destroyed: z.boolean(),
|
||||
});
|
||||
@@ -114,11 +116,6 @@ export type ElectronHookSnapshot = z.infer<typeof hookSnapshotSchema>;
|
||||
export type ElectronHookEvent = z.infer<typeof hookEventSchema>;
|
||||
export type ElectronMetrics = z.infer<typeof metricSchema>[];
|
||||
type ElectronWindowMetadata = z.infer<typeof windowMetadataSchema>;
|
||||
type ElectronPageSnapshot = {
|
||||
readonly index: number;
|
||||
readonly url: string;
|
||||
readonly title: string;
|
||||
};
|
||||
|
||||
/** Run explicit actions against provider-owned Electron windows. */
|
||||
export const runElectronActions = async (
|
||||
@@ -128,12 +125,12 @@ export const runElectronActions = async (
|
||||
): Promise<ElectronActions> => {
|
||||
const actions: ElectronActions = [];
|
||||
for (const action of input.actions) {
|
||||
if (options.signal?.aborted === true)
|
||||
throw new BrowserObservationError(OPERATION, "cancelled");
|
||||
const actionStartedAt = Date.now();
|
||||
const windowIndex = actionWindowIndex(action);
|
||||
let selectedWindow: Page | undefined;
|
||||
try {
|
||||
if (options.signal?.aborted === true)
|
||||
throw new BrowserObservationError(OPERATION, "cancelled");
|
||||
selectedWindow =
|
||||
windowIndex === null
|
||||
? undefined
|
||||
@@ -322,25 +319,23 @@ export const readApplicationState = async (
|
||||
readonly electronVersion: string;
|
||||
readonly hookSnapshot: ElectronHookSnapshot;
|
||||
}> => {
|
||||
const pages = application.windows();
|
||||
const pageSnapshotsPromise: Promise<ElectronPageSnapshot[]> = Promise.all(
|
||||
pages.map(async (page: Page, index): Promise<ElectronPageSnapshot> => ({
|
||||
index,
|
||||
url: page.url(),
|
||||
title: await page.title(),
|
||||
})),
|
||||
);
|
||||
const windowMetadataPromise: Promise<ElectronWindowMetadata[]> = application
|
||||
.evaluate(({ BrowserWindow }) =>
|
||||
BrowserWindow.getAllWindows().map(
|
||||
(window: {
|
||||
readonly id: number;
|
||||
readonly webContents: { readonly id: number };
|
||||
readonly webContents: {
|
||||
readonly id: number;
|
||||
getURL(): string;
|
||||
getTitle(): string;
|
||||
};
|
||||
isDestroyed(): boolean;
|
||||
isVisible(): boolean;
|
||||
}) => ({
|
||||
window_id: `window:${String(window.id)}`,
|
||||
web_contents_id: `webContents:${String(window.webContents.id)}`,
|
||||
url: window.webContents.getURL(),
|
||||
title: window.webContents.getTitle(),
|
||||
visible: window.isDestroyed() ? null : window.isVisible(),
|
||||
destroyed: window.isDestroyed(),
|
||||
}),
|
||||
@@ -392,33 +387,15 @@ export const readApplicationState = async (
|
||||
};
|
||||
})
|
||||
.then((value) => hookSnapshotSchema.parse(value));
|
||||
const [
|
||||
pageSnapshots,
|
||||
windowMetadata,
|
||||
processMetrics,
|
||||
electronVersion,
|
||||
hookSnapshot,
|
||||
] = await Promise.all([
|
||||
pageSnapshotsPromise,
|
||||
windowMetadataPromise,
|
||||
processMetricsPromise,
|
||||
electronVersionPromise,
|
||||
hookSnapshotPromise,
|
||||
]);
|
||||
const [windowMetadata, processMetrics, electronVersion, hookSnapshot] =
|
||||
await Promise.all([
|
||||
windowMetadataPromise,
|
||||
processMetricsPromise,
|
||||
electronVersionPromise,
|
||||
hookSnapshotPromise,
|
||||
]);
|
||||
return {
|
||||
windows: pageSnapshots.map((page) => {
|
||||
const metadata = windowMetadata[page.index];
|
||||
if (metadata === undefined)
|
||||
throw new BrowserObservationError(OPERATION, "window_metadata_missing");
|
||||
return {
|
||||
window_id: metadata.window_id,
|
||||
web_contents_id: metadata.web_contents_id,
|
||||
url: page.url,
|
||||
title: page.title,
|
||||
visible: metadata.visible,
|
||||
destroyed: metadata.destroyed,
|
||||
};
|
||||
}),
|
||||
windows: windowMetadata,
|
||||
metrics: processMetrics,
|
||||
electronVersion,
|
||||
hookSnapshot,
|
||||
|
||||
@@ -58,7 +58,10 @@ const eventFamily = (
|
||||
kind: ElectronHookEvent["kind"],
|
||||
processType: string | null,
|
||||
): string => {
|
||||
if (kind === "preload" && processType === "main")
|
||||
if (
|
||||
kind === "preload" &&
|
||||
(processType === "main" || processType === "browser")
|
||||
)
|
||||
return "preload-configuration";
|
||||
if (kind.startsWith("ipc-renderer"))
|
||||
return processType === "renderer" ? "renderer-ipc" : "ipc";
|
||||
@@ -163,6 +166,11 @@ export const projectElectronActiveCapture = (
|
||||
"IPC direction and sender/receiver identifiers are observed only where Electron exposes them at the hooked boundary.",
|
||||
"The runtime timeline records lifecycle, navigation, shell, permission, popup, download, protocol, preload, native-addon, process, and IPC events; activity before hook installation is unavailable.",
|
||||
"The preload and renderer process contexts are not instrumented by the main-process -r hook; preload configuration and contextBridge API-shape events are main-boundary observations, not proof of renderer-side execution.",
|
||||
...(!hookSnapshot.events.some(({ kind }) => kind === "preload")
|
||||
? [
|
||||
"Preload configuration was not exposed by the observed Electron window metadata. Preload paths and execution remain unavailable.",
|
||||
]
|
||||
: []),
|
||||
"Process metrics are an Electron API snapshot and do not prove hostile-local-user isolation.",
|
||||
...(hookSnapshot.dropped > 0
|
||||
? [
|
||||
|
||||
@@ -71,6 +71,12 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
|
||||
let application: ElectronApplication | undefined;
|
||||
let ownership: OwnedProcessGroup | undefined;
|
||||
let lineage: ProcessLineageObservation | undefined;
|
||||
let capture: ElectronActiveObservationResult | undefined;
|
||||
let paths: ElectronPaths | undefined;
|
||||
let initialState:
|
||||
| Awaited<ReturnType<typeof readApplicationState>>
|
||||
| undefined;
|
||||
let actions: ElectronActiveObservationResult["actions"] = [];
|
||||
let outcome: Result<ElectronActiveObservationResult, AnalysisError>;
|
||||
const runId = randomUUID();
|
||||
try {
|
||||
@@ -78,7 +84,7 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
|
||||
throw new BrowserObservationError(OPERATION, "cancelled");
|
||||
await prepareProcessOwnershipInspection(options.signal);
|
||||
const startupDeadline = Date.now() + STARTUP_TIMEOUT_MS;
|
||||
const paths = await canonicalPaths(input);
|
||||
paths = await canonicalPaths(input);
|
||||
const captureBaseline =
|
||||
await systemProcessOwnershipHost.captureBaseline?.(options.signal);
|
||||
if (options.signal?.aborted)
|
||||
@@ -109,24 +115,66 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
|
||||
sweepTokenOwnedProcesses: true,
|
||||
...(captureBaseline === undefined ? {} : { captureBaseline }),
|
||||
};
|
||||
const actions = await runElectronActions(application, input, options);
|
||||
lineage = await observeOwnedProcessLineage(ownership);
|
||||
initialState = await readApplicationState(application);
|
||||
actions = await runElectronActions(application, input, options);
|
||||
const state = await runWithExecutionLimits(
|
||||
readApplicationState(application),
|
||||
options.signal,
|
||||
undefined,
|
||||
options.signal?.aborted ? Date.now() + 5_000 : undefined,
|
||||
);
|
||||
outcome = ok(projectElectronActiveCapture(paths, actions, state));
|
||||
capture = projectElectronActiveCapture(paths, actions, state);
|
||||
outcome = options.signal?.aborted
|
||||
? err(
|
||||
new BrowserObservationError(OPERATION, "cancelled", {
|
||||
partialObservation: {
|
||||
kind: "electron-active-observation",
|
||||
capture,
|
||||
},
|
||||
}),
|
||||
)
|
||||
: ok(capture);
|
||||
} catch (cause: unknown) {
|
||||
if (
|
||||
options.signal?.aborted &&
|
||||
paths !== undefined &&
|
||||
initialState !== undefined
|
||||
) {
|
||||
const retainedCapture = projectElectronActiveCapture(
|
||||
paths,
|
||||
actions,
|
||||
initialState,
|
||||
);
|
||||
capture = {
|
||||
...retainedCapture,
|
||||
limitations: [
|
||||
...retainedCapture.limitations,
|
||||
`Final Electron state was unavailable after cancellation: ${cause instanceof Error ? cause.message : String(cause)}. Windows, metrics, IPC, and timeline are the snapshot collected before actions and may omit their effects.`,
|
||||
],
|
||||
};
|
||||
}
|
||||
outcome = err(
|
||||
options.signal?.aborted === true &&
|
||||
(cause === options.signal.reason ||
|
||||
(cause instanceof Error && cause.name === "AbortError"))
|
||||
? new BrowserObservationError(OPERATION, "cancelled", { cause })
|
||||
options.signal?.aborted === true
|
||||
? new BrowserObservationError(OPERATION, "cancelled", {
|
||||
cause,
|
||||
...(capture === undefined
|
||||
? {}
|
||||
: {
|
||||
partialObservation: {
|
||||
kind: "electron-active-observation" as const,
|
||||
capture,
|
||||
},
|
||||
}),
|
||||
})
|
||||
: providerError(cause),
|
||||
);
|
||||
}
|
||||
if (application !== undefined) {
|
||||
if (ownership !== undefined)
|
||||
lineage = await observeOwnedProcessLineage(ownership);
|
||||
if (ownership !== undefined) {
|
||||
const currentLineage = await observeOwnedProcessLineage(ownership);
|
||||
if (currentLineage.status === "verified" || lineage === undefined)
|
||||
lineage = currentLineage;
|
||||
}
|
||||
let closeError: unknown;
|
||||
try {
|
||||
await runWithExecutionLimits(
|
||||
@@ -146,13 +194,51 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
|
||||
: await cleanupElectronProcesses(ownership, lineage);
|
||||
if (!cleanup.cleaned)
|
||||
return err(
|
||||
providerError(
|
||||
new BrowserObservationError(OPERATION, "cleanup_failed", {
|
||||
cause: new Error(cleanup.reason),
|
||||
}),
|
||||
),
|
||||
new BrowserObservationError(OPERATION, "cleanup_failed", {
|
||||
cause: outcome.ok ? new Error(cleanup.reason) : outcome.error,
|
||||
detail: `Electron cleanup could not be verified: ${cleanup.reason}.${capture !== undefined ? " Collected observations are retained in partial_observation." : ""}${outcome.ok ? "" : ` Capture also failed: ${outcome.error.message}.`} Inspect the reported process resources before launching another capture.`,
|
||||
cleanup: {
|
||||
reason: cleanup.reason,
|
||||
resources:
|
||||
ownership === undefined
|
||||
? ["owned_process_group"]
|
||||
: [
|
||||
"owned_process_group",
|
||||
`run:${ownership.runId}`,
|
||||
`process-group:${String(ownership.processGroupId)}`,
|
||||
],
|
||||
},
|
||||
...(capture !== undefined
|
||||
? {
|
||||
partialObservation: {
|
||||
kind: "electron-active-observation" as const,
|
||||
capture: {
|
||||
...capture,
|
||||
application: {
|
||||
...capture.application,
|
||||
cleanup: "unverified" as const,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
: {}),
|
||||
}),
|
||||
);
|
||||
if (closeError !== undefined)
|
||||
return err(
|
||||
new BrowserObservationError(OPERATION, "cleanup_failed", {
|
||||
cause: outcome.ok ? closeError : outcome.error,
|
||||
detail: `Electron transport teardown failed after process cleanup: ${closeError instanceof Error ? closeError.message : String(closeError)}.${capture !== undefined ? " Collected observations are retained in partial_observation." : ""}${outcome.ok ? "" : ` Capture also failed: ${outcome.error.message}.`}`,
|
||||
...(capture !== undefined
|
||||
? {
|
||||
partialObservation: {
|
||||
kind: "electron-active-observation" as const,
|
||||
capture,
|
||||
},
|
||||
}
|
||||
: {}),
|
||||
}),
|
||||
);
|
||||
if (closeError !== undefined) return err(providerError(closeError));
|
||||
if (outcome.ok && cleanup.unverified !== undefined)
|
||||
outcome = ok({
|
||||
...outcome.value,
|
||||
@@ -294,5 +380,8 @@ const providerError = (cause: unknown): AnalysisError =>
|
||||
OPERATION,
|
||||
{
|
||||
cause,
|
||||
diagnostics: {
|
||||
message: cause instanceof Error ? cause.message : String(cause),
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisInputError,
|
||||
AnalysisOutputError,
|
||||
AnalysisResourceConstraintError,
|
||||
AnalysisTimeoutError,
|
||||
} from "../../domain/analysisErrorCore.js";
|
||||
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
|
||||
@@ -17,6 +18,7 @@ import {
|
||||
type InspectWebNetworkCaptureInput,
|
||||
} from "../../domain/webNetworkCapture.js";
|
||||
import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
|
||||
import { HAR_CAPTURE_HEAP_LIMITS } from "./CaptureRelease.js";
|
||||
const OPERATION = "inspect_web_network_capture";
|
||||
|
||||
/** Preserve the origin and typed cause of a historical capture failure. */
|
||||
@@ -55,6 +57,18 @@ export const historicalCaptureFailure = (
|
||||
);
|
||||
if (cause.reason === "output-limit")
|
||||
return new AnalysisOutputError(OPERATION, cause.message);
|
||||
if (
|
||||
phase === "decoder" &&
|
||||
input.format === "har" &&
|
||||
cause.reason === "process" &&
|
||||
cause.snapshot?.signal === "SIGABRT" &&
|
||||
/FATAL ERROR:[^\r\n]*heap out of memory/u.test(cause.snapshot.stderr.text)
|
||||
)
|
||||
return captureMemoryFailure(
|
||||
input,
|
||||
"The HAR decoder exhausted its fixed V8 heap",
|
||||
cause,
|
||||
);
|
||||
}
|
||||
if (options?.signal?.aborted) return new AnalysisCancelledError(OPERATION);
|
||||
if (
|
||||
@@ -144,3 +158,44 @@ export const historicalCaptureFailure = (
|
||||
},
|
||||
});
|
||||
};
|
||||
|
||||
/** Preserve a decoder's observed memory failure and its actual workload limits. */
|
||||
export const captureMemoryFailure = (
|
||||
input: InspectWebNetworkCaptureInput,
|
||||
reason: string,
|
||||
cause?: unknown,
|
||||
): AnalysisResourceConstraintError =>
|
||||
new AnalysisResourceConstraintError(
|
||||
OPERATION,
|
||||
"memory",
|
||||
`${reason}: ${input.capture_path}. No complete capture result is available.`,
|
||||
{
|
||||
boundary: "historical-capture-decoder",
|
||||
capture_path: input.capture_path,
|
||||
format: input.format,
|
||||
maximum_input_bytes: WEB_NETWORK_CAPTURE_LIMITS.inputBytes,
|
||||
maximum_reply_bytes: WEB_NETWORK_CAPTURE_LIMITS.outputBytes,
|
||||
...(input.format === "har"
|
||||
? {
|
||||
old_generation_heap_mib: HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB,
|
||||
semi_space_heap_mib: HAR_CAPTURE_HEAP_LIMITS.semiSpaceMiB,
|
||||
}
|
||||
: {}),
|
||||
...(cause instanceof OwnedCommandFailure
|
||||
? { observed_signal: cause.snapshot?.signal ?? null }
|
||||
: {}),
|
||||
},
|
||||
{
|
||||
cause,
|
||||
remediationAction: `Use a smaller capture exported by its producer, or another decoder with sufficient capacity for the original capture. Preserve the original for provenance; a subset does not establish complete-capture coverage.${input.format === "har" ? ` REA's HAR old-generation heap is fixed at ${HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB} MiB; inherited NODE_OPTIONS cannot raise it.` : ""}`,
|
||||
...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
|
||||
? {
|
||||
capturedOutput: {
|
||||
stdout: cause.snapshot.stdout.text,
|
||||
stderr: cause.snapshot.stderr.text,
|
||||
truncated: cause.snapshot.diagnosticTruncated ?? false,
|
||||
},
|
||||
}
|
||||
: {}),
|
||||
},
|
||||
);
|
||||
|
||||
@@ -5,6 +5,12 @@ export const HAR_CAPTURE_PROVIDER_IDENTITY = {
|
||||
version: "har-schema@2.0.0;jsonc-parser@3.3.1;lossless-json@4.3.1",
|
||||
} as const;
|
||||
|
||||
/** Fixed V8 heap settings used by the owned HAR decoder process. */
|
||||
export const HAR_CAPTURE_HEAP_LIMITS = {
|
||||
oldGenerationMiB: 192,
|
||||
semiSpaceMiB: 8,
|
||||
} as const;
|
||||
|
||||
/** Native executable profile verified with unchanged mitmproxy raw-state decoding. */
|
||||
export const MITMPROXY_CAPTURE_PROVIDER_IDENTITY = {
|
||||
id: "mitmproxy-native-tnetstring",
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
import { fileURLToPath } from "node:url";
|
||||
import type { HistoricalCaptureFormatAdapter } from "./HistoricalCaptureFormatAdapter.js";
|
||||
import { HAR_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
|
||||
import {
|
||||
HAR_CAPTURE_PROVIDER_IDENTITY,
|
||||
HAR_CAPTURE_HEAP_LIMITS,
|
||||
} from "./CaptureRelease.js";
|
||||
|
||||
/** HAR's parser/schema packages run in one bounded Node heap, without network or target execution. */
|
||||
export class HarCaptureAdapter implements HistoricalCaptureFormatAdapter {
|
||||
@@ -12,8 +15,8 @@ export class HarCaptureAdapter implements HistoricalCaptureFormatAdapter {
|
||||
return {
|
||||
command: process.execPath,
|
||||
arguments: [
|
||||
"--max-old-space-size=192",
|
||||
"--max-semi-space-size=8",
|
||||
`--max-old-space-size=${HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB}`,
|
||||
`--max-semi-space-size=${HAR_CAPTURE_HEAP_LIMITS.semiSpaceMiB}`,
|
||||
"--v8-pool-size=1",
|
||||
"--single-threaded",
|
||||
fileURLToPath(new URL("./HarCaptureProcess.js", import.meta.url)),
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
import { historicalCaptureFailure } from "./CaptureFailures.js";
|
||||
import {
|
||||
historicalCaptureFailure,
|
||||
captureMemoryFailure,
|
||||
} from "./CaptureFailures.js";
|
||||
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
|
||||
import type { HistoricalCaptureFormatAdapter } from "./HistoricalCaptureFormatAdapter.js";
|
||||
import { randomUUID } from "node:crypto";
|
||||
@@ -160,7 +163,9 @@ export class HistoricalCaptureDecoder {
|
||||
},
|
||||
},
|
||||
]);
|
||||
if (reply.reason === "decoder" || reply.reason === "resource-limit")
|
||||
if (reply.reason === "resource-limit")
|
||||
throw captureMemoryFailure(input, reply.message);
|
||||
if (reply.reason === "decoder")
|
||||
throw new ProviderAdapterError(input.format, OPERATION, {
|
||||
diagnostics: {
|
||||
phase: "decoder",
|
||||
|
||||
+35
-28
@@ -44,7 +44,7 @@ const registerElectronActiveCommand = (
|
||||
logger: Logger,
|
||||
): void => {
|
||||
cli.command(CLI_COMMANDS.captureElectronScenario, {
|
||||
description: "Run one bounded owned Electron scenario",
|
||||
description: "Run one owned Electron scenario with cancellable actions",
|
||||
args: z.object({
|
||||
inputJson: z
|
||||
.string()
|
||||
@@ -53,33 +53,40 @@ const registerElectronActiveCommand = (
|
||||
),
|
||||
}),
|
||||
run: ({ args }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.captureElectronScenario, async () => {
|
||||
const input = await parseCliJsonInput(
|
||||
args.inputJson,
|
||||
"capture_electron_scenario",
|
||||
);
|
||||
if (!input.ok) return input.error;
|
||||
const parsed = electronActiveObservationInputSchema.safeParse(
|
||||
resolveCliJsonPaths(input.value, [
|
||||
["executable_path"],
|
||||
["application_path"],
|
||||
["application_root"],
|
||||
]),
|
||||
);
|
||||
if (!parsed.success)
|
||||
return inputError(
|
||||
"capture_electron_scenario",
|
||||
parsed.error.issues,
|
||||
input.value,
|
||||
);
|
||||
const { createElectronScenarioProvider } =
|
||||
await import("../composition/electronScenario.js");
|
||||
const result = await captureElectronScenario(
|
||||
createElectronScenarioProvider(),
|
||||
parsed.data,
|
||||
);
|
||||
return result.ok ? result.value : cliError(result.error);
|
||||
}),
|
||||
withCommandCancellation((signal) =>
|
||||
logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.captureElectronScenario,
|
||||
async () => {
|
||||
const input = await parseCliJsonInput(
|
||||
args.inputJson,
|
||||
"capture_electron_scenario",
|
||||
);
|
||||
if (!input.ok) return input.error;
|
||||
const parsed = electronActiveObservationInputSchema.safeParse(
|
||||
resolveCliJsonPaths(input.value, [
|
||||
["executable_path"],
|
||||
["application_path"],
|
||||
["application_root"],
|
||||
]),
|
||||
);
|
||||
if (!parsed.success)
|
||||
return inputError(
|
||||
"capture_electron_scenario",
|
||||
parsed.error.issues,
|
||||
input.value,
|
||||
);
|
||||
const { createElectronScenarioProvider } =
|
||||
await import("../composition/electronScenario.js");
|
||||
const result = await captureElectronScenario(
|
||||
createElectronScenarioProvider(),
|
||||
parsed.data,
|
||||
{ signal },
|
||||
);
|
||||
return result.ok ? result.value : cliError(result.error);
|
||||
},
|
||||
),
|
||||
),
|
||||
});
|
||||
};
|
||||
|
||||
|
||||
@@ -112,7 +112,7 @@ export const ELECTRON_TOOL_CONTRACTS = [
|
||||
name: "capture_electron_scenario",
|
||||
...toolContractMetadata("capture_electron_scenario"),
|
||||
description:
|
||||
"Use this for a provider-owned Electron run when passive CDP or Inspector observation cannot exercise application behavior. REA owns startup and teardown, accepts caller-defined click/wait actions plus window-targeted renderer reload/crash and synthetic open-url/second-instance delivery, and returns correlated window/WebContents/process/preload/session/navigation/shell/IPC evidence without retaining payload values. Results identify observed and unavailable event families, coverage status, action targets, and truncation. External shell, navigation, permission, download, popup, updater, and OS-integration effects are blocked and recorded. Use passive Electron tools for observation-only work.",
|
||||
"Use this for a provider-owned Electron run when passive CDP or Inspector observation cannot exercise application behavior. REA owns startup and teardown, accepts caller-defined click/wait actions plus window-targeted renderer reload/crash and synthetic open-url/second-instance delivery, and returns correlated window/WebContents/process/preload/session/navigation/shell/IPC evidence without retaining payload values. Actions wait for completion or request cancellation; a missing click target can keep the request pending. Results identify observed and unavailable event families, coverage status, action targets, and truncation. Cleanup failures retain collected observations with explicit cleanup uncertainty. External shell, navigation, permission, download, popup, updater, and OS-integration effects are blocked and recorded. Use passive Electron tools for observation-only work.",
|
||||
kind: "electron-provider",
|
||||
inputSchema: electronActiveObservationInputSchema,
|
||||
outputSchema: evidenceResultOf(electronActiveObservationResultSchema),
|
||||
|
||||
@@ -86,9 +86,11 @@ import type {
|
||||
} from "./process/processCapture.js";
|
||||
import type { FileOffsetPartialObservation } from "./native/fileOffsetPartialObservation.js";
|
||||
import type { NativeCallPartialObservation } from "./native/nativeCallPartialObservation.js";
|
||||
import type { ElectronActivePartialObservation } from "./javascript/electronActiveObservation.js";
|
||||
|
||||
/** Provider-neutral evidence collected before a typed analysis failure. */
|
||||
export type AnalysisPartialObservation =
|
||||
| PartialProcessCaptureObservation
|
||||
| NativeCallPartialObservation
|
||||
| FileOffsetPartialObservation;
|
||||
| FileOffsetPartialObservation
|
||||
| ElectronActivePartialObservation;
|
||||
|
||||
@@ -96,7 +96,7 @@ export const analysisErrorCategory = (
|
||||
if (error._tag === "ProcessCaptureError")
|
||||
return error.userCategory ?? "execution_failure";
|
||||
if (error instanceof BrowserObservationError)
|
||||
return browserErrorCategory(error.reason);
|
||||
return error.userCategory ?? browserErrorCategory(error.reason);
|
||||
if (
|
||||
error instanceof HopperRemoteError &&
|
||||
error.diagnosticType === "invalid_request"
|
||||
@@ -117,6 +117,8 @@ export const analysisErrorCategory = (
|
||||
const browserErrorCategory = (
|
||||
reason: BrowserObservationError["reason"],
|
||||
): AnalysisErrorProjection["category"] => {
|
||||
if (reason === "cancelled") return "cancelled";
|
||||
if (reason === "timeout") return "timeout";
|
||||
if (reason === "payload_limit") return "truncated";
|
||||
if (
|
||||
reason === "target_not_found" ||
|
||||
|
||||
@@ -96,7 +96,9 @@ const underlyingErrorCode = (
|
||||
? "provider_unavailable"
|
||||
: "capability_unavailable";
|
||||
if (error instanceof BrowserObservationError)
|
||||
return browserErrorCode(error.reason);
|
||||
return error.userCategory === "cancelled"
|
||||
? "cancelled"
|
||||
: browserErrorCode(error.reason);
|
||||
if (error instanceof ArtifactOperationError)
|
||||
return artifactOperationCode(error);
|
||||
if (error instanceof EvidenceFileError) return evidenceFileCode(error.reason);
|
||||
@@ -109,6 +111,8 @@ const underlyingErrorCode = (
|
||||
const browserErrorCode = (
|
||||
reason: BrowserObservationError["reason"],
|
||||
): AnalysisErrorProjection["code"] => {
|
||||
if (reason === "cancelled") return "cancelled";
|
||||
if (reason === "timeout") return "provider_timeout";
|
||||
if (reason === "payload_limit") return "truncated";
|
||||
if (
|
||||
reason === "target_not_found" ||
|
||||
|
||||
@@ -2,7 +2,10 @@ import type {
|
||||
BrowserObservationFailureReason,
|
||||
BrowserObservationOperation,
|
||||
} from "./browserObservationErrors.js";
|
||||
import { AnalysisError } from "./analysisErrorBase.js";
|
||||
import {
|
||||
AnalysisError,
|
||||
type AnalysisErrorOptions,
|
||||
} from "./analysisErrorBase.js";
|
||||
import { AnalysisCancelledError } from "./analysisErrorCore.js";
|
||||
|
||||
/** A bounded passive browser observation failed at its CDP boundary. */
|
||||
@@ -16,16 +19,39 @@ export class BrowserObservationError extends AnalysisError {
|
||||
constructor(
|
||||
readonly operation: BrowserObservationOperation,
|
||||
readonly reason: BrowserObservationFailureReason,
|
||||
options?: ErrorOptions & { readonly detail?: string },
|
||||
options?: AnalysisErrorOptions & { readonly detail?: string },
|
||||
) {
|
||||
super(`Browser observation ${operation} failed: ${reason}`, options);
|
||||
this.userMessage = options?.detail;
|
||||
this.cleanupIncomplete = reason === "cleanup_failed";
|
||||
this.userMessage =
|
||||
options?.detail ?? observationFailureMessage(operation, reason);
|
||||
this.cleanupIncomplete =
|
||||
this.cleanup !== undefined || reason === "cleanup_failed";
|
||||
this.cleanupResources =
|
||||
reason === "cleanup_failed" ? ["browser_transport"] : [];
|
||||
this.cleanup?.resources ??
|
||||
(reason === "cleanup_failed" ? ["browser_transport"] : []);
|
||||
this.userCategory =
|
||||
reason === "cancelled" || options?.cause instanceof AnalysisCancelledError
|
||||
reason === "cancelled" ||
|
||||
options?.cause instanceof AnalysisCancelledError ||
|
||||
(options?.cause instanceof AnalysisError &&
|
||||
options.cause.userCategory === "cancelled")
|
||||
? "cancelled"
|
||||
: undefined;
|
||||
}
|
||||
}
|
||||
|
||||
const observationFailureMessage = (
|
||||
operation: BrowserObservationOperation,
|
||||
reason: BrowserObservationFailureReason,
|
||||
): string | undefined => {
|
||||
if (reason === "cancelled")
|
||||
return `${operation} was cancelled. Collected observations and cleanup status are reported when available.`;
|
||||
if (reason === "timeout")
|
||||
return `${operation} exceeded its execution deadline. Review the target's responsiveness and retained observations before retrying.`;
|
||||
if (reason === "endpoint_unreachable")
|
||||
return `${operation} could not reach the selected loopback debugging endpoint. Verify that the target process is running with debugging enabled and that the endpoint's port matches it, then retry.`;
|
||||
if (reason === "target_not_found")
|
||||
return `${operation} could not find the selected target at the debugging endpoint. Refresh target discovery for that endpoint and retry with a returned target ID.`;
|
||||
if (reason === "disconnected")
|
||||
return `${operation} lost its debugging connection. Verify that the target process is still running, refresh target discovery, and retry the observation.`;
|
||||
return undefined;
|
||||
};
|
||||
|
||||
@@ -5,6 +5,7 @@ import {
|
||||
AnalysisInputError,
|
||||
AnalysisOutputError,
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisResourceConstraintError,
|
||||
} from "./analysisErrorCore.js";
|
||||
import { redactExplicitText } from "./explicitSensitiveValues.js";
|
||||
import type { JsonValue } from "./jsonValue.js";
|
||||
@@ -118,6 +119,28 @@ export const redactExplicitFailure = (
|
||||
: { userMessage: text(error.userMessage) }),
|
||||
},
|
||||
);
|
||||
if (error instanceof AnalysisResourceConstraintError)
|
||||
return new AnalysisResourceConstraintError(
|
||||
error.operation,
|
||||
error.resource,
|
||||
text(error.reason),
|
||||
error.reportedLimits === null ? null : diagnostics(error.reportedLimits),
|
||||
{
|
||||
cause: error,
|
||||
...(error.remediationAction === undefined
|
||||
? {}
|
||||
: { remediationAction: text(error.remediationAction) }),
|
||||
...(error.capturedOutput === undefined
|
||||
? {}
|
||||
: {
|
||||
capturedOutput: {
|
||||
stdout: text(error.capturedOutput.stdout),
|
||||
stderr: text(error.capturedOutput.stderr),
|
||||
truncated: error.capturedOutput.truncated,
|
||||
},
|
||||
}),
|
||||
},
|
||||
);
|
||||
if (error instanceof ProviderCleanupError)
|
||||
return new ProviderCleanupError(
|
||||
error.providerId,
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import { isAbsoluteLocalPath } from "../localPath.js";
|
||||
import { isAbsoluteLocalPath, localPathStringSchema } from "../localPath.js";
|
||||
|
||||
const pathInputSchema = z.string().trim().min(1).refine(isAbsoluteLocalPath, {
|
||||
const pathInputSchema = localPathStringSchema.refine(isAbsoluteLocalPath, {
|
||||
message:
|
||||
"Electron executable, application, and root paths must be absolute local filesystem paths (for example /Applications/Electron.app/Contents/MacOS/Electron)",
|
||||
});
|
||||
@@ -76,7 +76,11 @@ export const electronActiveObservationInputSchema = z.strictObject({
|
||||
.describe(
|
||||
"Absolute local filesystem root for application-relative paths; omit to derive it from the application path. Relative paths are rejected.",
|
||||
),
|
||||
args: z.array(z.string()).default([]),
|
||||
args: z
|
||||
.array(
|
||||
z.string().regex(/^[^\0]*$/u, "Electron arguments must not contain NUL"),
|
||||
)
|
||||
.default([]),
|
||||
actions: z.array(actionSchema).default([]),
|
||||
});
|
||||
export type ElectronActiveObservationInput = z.infer<
|
||||
@@ -309,3 +313,16 @@ export const electronActiveObservationResultSchema = z.strictObject({
|
||||
export type ElectronActiveObservationResult = z.infer<
|
||||
typeof electronActiveObservationResultSchema
|
||||
>;
|
||||
|
||||
/** Observations collected before an Electron capture failed its cleanup boundary. */
|
||||
export interface ElectronActivePartialObservation {
|
||||
readonly kind: "electron-active-observation";
|
||||
readonly capture: Omit<ElectronActiveObservationResult, "application"> & {
|
||||
readonly application: Omit<
|
||||
ElectronActiveObservationResult["application"],
|
||||
"cleanup"
|
||||
> & {
|
||||
readonly cleanup: "unverified" | "terminated-owned-process";
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user