Files
rea/src/contracts/javascript/electronToolContracts.ts
T
880a603fe8 feat(mcp): derive an API surface view from retained web network captures (#1891)
* feat(mcp): derive an API surface view from retained web network captures

* fix(mcp): fail closed on sensitive parents and budget api-surface path expansion

* fix(mcp): keep recorded api-surface paths and budget only templated segments

* fix(mcp): read api-surface paths only from canonical URLs and charge new values once

* fix(mcp): reject authority-less api-surface URLs and key groups by rule positions

* fix(mcp): label api-surface confidence from all groups and cap transient path memory

* fix(mcp): budget api-surface dedup sets and narrow detail outputs

Charge retained deduplication sets before allocation, advertise only
each analysis operation's summary from its detail output, and document
that any templated group makes every API-surface page inferred.

* fix(mcp): bound api-surface path text and record limitations

Charge retained literal path copies before allocation, publish only
valid media-type essences, and deduplicate examined record limitations
onto the view.

* fix(mcp): keep api-surface refusals and path splits inside the reply budget

Sensitive-parent refusals now use the token sensitive_values_unretained so declared literals are not echoed. A later path split is charged against bytes already retained, and the published example includes the HAR record limitation with its matching digest.

* fix(mcp): budget api-surface method text before group keys

Charge method and origin text against the reply budget before the group key is serialized. Document that samples merge only when method, origin, and exact segment rules match.

* fix(mcp): bound api-surface copies and control-character authorities

Reject authorities containing a tab or newline so WHATWG cannot move userinfo into the recorded path. Charge four path copies, two method and origin copies, and each distinct content type against bytes already retained.

* fix(mcp): preflight combined api-surface group charges

Total path, method, origin, and segment charges before retaining a new group. Track content types in a set so distinct MIME essences are not compared quadratically.

* fix(mcp): charge api-surface content-type sets on first use

Create the per-group content-type set when the first essence is retained, and charge it before allocation. Groups with no content type no longer keep an empty set.

* refactor(analysis): centralize API-surface ownership and admission

Own grouping, deduplication, and combined retained/temporary resource admission in one accumulator. Charge fixed group storage before allocation and materialize only the requested page.

Share recorded URL parsing between capture redaction and projection, preserving source paths and excluding ambiguous credential fields. Cover resource admission invariants and the compiled HAR-to-view workflow.

* fix(analysis): admit capture schema clone before parsing

* fix(javascript): share Electron mutation proof with wrapped calls

* test(mcp): align graph and catalog checks with current contracts

* fix(analysis): admit and validate portable capture views

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-10-12 10:44:17 +08:00

151 lines
7.7 KiB
TypeScript

import type { ToolContract } from "../toolContractTypes.js";
import { toolContractMetadata } from "../toolEffects.js";
import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
import {
electronPageInspectionSchema,
electronTargetListSchema,
inspectElectronPageInputSchema,
listElectronTargetsInputSchema,
} from "../../domain/javascript/electronObservation.js";
import {
electronActiveObservationInputSchema,
electronActiveObservationResultSchema,
} from "../../domain/javascript/electronActiveObservation.js";
import { javascriptApplicationSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
import {
analysisDetailOutputSchemaOf,
analysisDetailSchema,
} from "../analysisDetail.js";
import {
analyzeJavaScriptApplicationInputSchema,
javascriptApplicationAnalysisResultSchema,
} from "../../domain/javascript/javascriptApplicationAnalysis.js";
import {
javascriptRuntimeReconciliationResultSchema,
reconcileJavaScriptRuntimeInputSchema,
} from "../../domain/javascript/javascriptRuntimeReconciliationSchemas.js";
import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "./javascriptRuntimeReconciliationExample.js";
const listOutputSchema = evidenceResultOf(electronTargetListSchema);
const inspectionOutputSchema = evidenceResultOf(electronPageInspectionSchema);
/** Caller-selected delivery of a completed JavaScript application analysis. */
export const analyzeJavaScriptApplicationRequestSchema =
analyzeJavaScriptApplicationInputSchema.extend({
detail: analysisDetailSchema,
});
const applicationOutputSchema = analysisDetailOutputSchemaOf(
javascriptApplicationAnalysisResultSchema,
javascriptApplicationSummaryViewResultSchema,
);
const reconciliationOutputSchema = evidenceResultOf(
javascriptRuntimeReconciliationResultSchema,
);
const endpoint = "http://127.0.0.1:9223";
const activeExample = {
executable_path: "/Applications/Electron.app/Contents/MacOS/Electron",
application_path: "/Applications/Example.app/Contents/Resources/main.js",
args: [],
actions: [{ step_id: "exercise-ipc", kind: "click", selector: "#run" }],
};
/** Endpoint-scoped Electron file-page discovery and inspection contracts. */
export const ELECTRON_TOOL_CONTRACTS = [
{
name: "list_electron_targets",
...toolContractMetadata("list_electron_targets"),
description:
"List every Electron file:// page target from a selected loopback CDP endpoint. Local file paths are canonicalized after symlink resolution. Selecting an endpoint exposes every eligible target and its local path metadata.",
kind: "electron-provider",
inputSchema: listElectronTargetsInputSchema,
outputSchema: listOutputSchema,
examples: [
{
title: "List Electron file pages",
input: {
cdp_endpoint: endpoint,
},
},
],
},
{
name: "inspect_electron_page",
...toolContractMetadata("inspect_electron_page"),
description:
"Passively inspect one Electron file page by supplying its loopback CDP endpoint and target ID. The provider rechecks that the target currently exists at that endpoint and is a local file page. Returns frames, DOM structure, resource paths, and scripts without evaluating renderer JavaScript or invoking Electron APIs. The selected endpoint exposes every local file page and its metadata to this tool.",
kind: "electron-provider",
inputSchema: inspectElectronPageInputSchema,
outputSchema: inspectionOutputSchema,
examples: [
{
title: "Inspect an Electron page",
input: {
cdp_endpoint: endpoint,
target_id: "TARGET_ID_FROM_LIST_ELECTRON_TARGETS",
},
},
],
},
{
name: "analyze_javascript_application",
...toolContractMetadata("analyze_javascript_application"),
description:
"Reconstruct one local ASAR or extracted JavaScript application as an inline application graph without executing it. Returns recovered graph nodes, edges, semantic relations, integrity contradictions, limitations, and coverage. Select source_paths to acquire and analyze only exact inventoried file paths; the complete artifact inventory and identity remain intact, and unselected sources remain explicit unknowns. Dependencies are not implicitly analyzed. Select detail summary to retain the complete analysis Evidence in this session and receive only its summary view, then inspect selected modules or pages with inspect_analysis_view. Summary detail reduces delivery, whereas source_paths bounds source analysis. Integrity mismatches fail by default; record-and-continue retains observed bytes as untrusted and marks graph coverage partial.",
kind: "electron-provider",
inputSchema: analyzeJavaScriptApplicationRequestSchema,
outputSchema: applicationOutputSchema,
examples: [
{
title: "Analyze one local JavaScript application",
input: {
input_path: "/Applications/Example.app/Contents/Resources/app.asar",
format: "auto",
integrity_policy: "fail",
},
},
{
title: "Analyze selected entry sources before unrelated vendor files",
input: {
input_path: "/Applications/Example.app/Contents/Resources/app.asar",
source_paths: ["package.json", "main.js", "preload.js"],
detail: "summary",
},
},
{
title: "Retain the complete analysis and return its summary view",
input: {
input_path: "/Applications/Example.app/Contents/Resources/app.asar",
detail: "summary",
},
},
],
},
{
name: "reconcile_javascript_runtime",
...toolContractMetadata("reconcile_javascript_runtime"),
description:
"Reconcile verified static JavaScript application graphs with existing passive web/Electron CDP, passive V8 Inspector, or provider-owned active Electron Evidence. Active Electron captures contribute an explicitly partial target-only runtime record; they never invent renderer scripts, frames, workers, or execution claims. Exact captured-source digests take priority over caller-declared file/URL mappings; target, frame, script, and worker ambiguity remains explicit, and source-map authority stays separate.",
kind: "electron-provider",
inputSchema: reconcileJavaScriptRuntimeInputSchema,
outputSchema: reconciliationOutputSchema,
examples: [
{
title: "Reconcile one passive Electron capture",
input: JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
},
],
},
{
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. 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),
examples: [
{ title: "Exercise an owned Electron application", input: activeExample },
],
},
] as const satisfies readonly ToolContract[];