@dsh-plus/agent-preset-rea 0.0.0-stage → 0.1.0

package/skills/reverse-engineer-anything/references/javascript-applications.md

@@ -0,0 +1,175 @@
+# JavaScript and Electron application artifacts
+
+For captured or bundled JavaScript that needs readable source recovery, use
+`recover_javascript_sources` with an absolute `path` and absent
+`output_directory`. Supply related runtime/shared/lazy files in
+`additional_paths` when advertised, then analyze the returned `analysis_input`
+directory together. Each input retains its own snapshot, digest and byte-range
+provenance; inputs and recovered code are never executed. Recovery requires a
+caller-supplied Wakaru on Linux x64; see [the recovery guide](https://github.com/morluto/rea/blob/main/docs/javascript-recovery.md).
+
+Use `analyze_javascript_application` directly on the operator-supplied ASAR or
+extracted tree. When the question concerns known source paths and the connected
+schema advertises `source_paths`, select exact inventoried paths such as
+`["package.json", "main.js", "preload.js"]`. Include supporting manifests or
+source maps explicitly; dependencies are not implicitly analyzed. REA retains
+the complete artifact inventory and identity but reads source text and analyzes
+only selected files. The result and summary record `source_selection`; files
+outside scope and their relationships remain unknown, so partial application
+coverage does not mean the selected source failed. Use repeated `--source-path`
+on either static application CLI route. Omit the selection when the question
+requires complete application analysis. `detail: "summary"` reduces delivery
+and does not by itself reduce analysis work.
+
+Exact `#alias` specifiers resolve through the importer's
+enclosing package `imports` map to package-local files; nested `node_modules`
+packages use their own map. Wildcard, recursive, and external-package import
+targets stay unresolved with that limitation. When size is unknown or large and the connected schema advertises
+`detail`, request `detail: "summary"`. This returns an `inspect_analysis_view`
+Evidence record with a distinct ID and a `normalized_result.parent_evidence_id`
+for the complete retained application analysis. Source-map contents are part of
+that static analysis. Read findings, coverage, limitations and unknowns, then
+follow a specific unanswered question. Older servers without `detail` return
+the complete application Evidence inline when it fits.
+
+When the connected schema advertises `max_heap_mb` and `analysis_timeout_ms`,
+these select the isolated source analyzer's old-space heap and per-source
+deadline. Defaults are 1024 MiB and 300000 ms. They do not change the MCP
+process heap. A Bun-hosted REA does not enforce the heap choice; on Windows it
+instead limits the analyzer's committed memory to that choice plus a 512 MiB
+runtime reserve.
+Resource-limited analyses preserve completed static facts and
+report partial semantic coverage with specific unknown scopes; this does not
+mean the source is malformed. Inspect those limits before retrying a source.
+When expanded relationships exceed the parent's available memory, inspect the
+file's modules item view for retained `static_analysis` and
+`semantic_module_analysis`. Their facts remain available even when graph links
+are unknown. Cumulative result exhaustion can stop analysis before every file
+is examined; the inventory and remaining unknown scopes distinguish that case.
+Timeout or cancellation after source analysis begins retains partial Evidence
+in the same session. A returned `error.details.partial_observation` reference
+can be supplied directly to `inspect_analysis_view`. If the SDK cancels locally, retrieve its recorded ID from
+the Evidence bundle before inspecting the partial analysis.
+
+## Read a module without repeating analysis
+
+Use the actual returned parent ID, on the same connection, as `source.evidence_id`.
+The following IDs are placeholders to replace with returned values. When the
+module's node ID is not already known, page identities before selecting an item.
+Pages return only node IDs, paths and roles; choose a useful page size and follow
+`coverage.next_offset` when another page matters:
+
+```json
+{
+  "source": {
+    "kind": "retained-evidence",
+    "evidence_id": "ev_ACTUAL_PARENT_ID"
+  },
+  "view": { "kind": "page", "collection": "modules", "offset": 0, "limit": 16 }
+}
+```
+
+Select the relevant page entry by its exact `node_id` and recorded role:
+
+```json
+{
+  "source": {
+    "kind": "retained-evidence",
+    "evidence_id": "ev_ACTUAL_PARENT_ID"
+  },
+  "view": {
+    "kind": "item",
+    "collection": "modules",
+    "selector": { "node_id": "jag_node_ACTUAL_NODE_ID" }
+  }
+}
+```
+
+Module pages include asset, bundled and source module roles, so one path can
+identify several entries. Use `selector.path` only when uniqueness is established;
+the returned node ID avoids needing a complete inventory to prove uniqueness. On ambiguity,
+select the matching node ID from the page or the error's candidates. Follow
+`next_offset` when another page matters. An item exposes that module node's
+recorded observations, identity, hashes, exports and source ranges; it does not
+include every child syntax observation, related edge or original source file.
+An absent item fact is not evidence of absence from the whole application.
+
+## Trace only the remaining question
+
+Use `trace_application_feature` on the parent application Evidence for one
+literal node ID, route, string, API, IPC channel, module, or native export.
+Select `incoming` for relationships leading to the seed, `outgoing` for those
+leaving it, and `both` when the question needs both. Trace traversal includes
+containment relationships, so even a narrow seed can expand many nodes; a
+bidirectional trace can reach unrelated sibling modules. A module item or page
+is preferable when its observations already answer the question. Do not treat
+all reached nodes as participants in the feature.
+
+Reuse retained parent Evidence when the server advertises it, or supply complete
+Evidence inline. Include Hopper or Ghidra Evidence only when its artifact digest
+matches exactly.
+
+## Recover an oversized display
+
+An oversized response reports `resource_constraint` and
+`details.resource: "transport"`. Reuse
+`details.reported_limits.evidence_reference` with `inspect_analysis_view` for a
+summary, one module, or a stable page of module identities.
+`export_evidence_bundle` writes the complete canonical session to a
+caller-selected file. These workflows keep the original Evidence and coverage;
+a broad follow-up can also exceed framing.
+
+A client can truncate a successful result inside its text envelope without a
+REA `resource_constraint`. Treat a truncation notice or incomplete JSON as a
+display limitation; do not claim the full record was examined. Reuse the known
+parent ID for smaller views, or export complete Evidence to a selected file
+while the session remains open. If the parent ID was lost from the preview,
+use the prior analysis summary or explicit ledger entries to recover it; do
+not invent an ID or rerun analysis just to reproduce the same display.
+
+BrowserWindow preferences, preload and contextBridge surfaces, IPC
+registrations, utility processes, and native binding requests are static syntax
+observations. Only a unique exact literal IPC channel match supports an inferred
+pairing. Dynamic or ambiguous channels remain unresolved. A requested `.node`
+member is not a verified native export. Never claim runtime reachability,
+registration, defaults, or policy enforcement from static analysis.
+
+For version comparison, analyze each version once, then call
+`compare_application_versions`. Accept only its digest, source-map, structural
+fingerprint, or non-module semantic matches. Module ordinals and minified names
+are not persistent identity. Report added or removed only with complete
+opposite-side coverage; otherwise report unknown.
+
+When the question asks how one exact exported callable's returned object shape
+changed, analyze each version once and then call
+`compare_javascript_export_shapes` with explicit module paths and export names.
+Use the returned IDs on the same connection, or complete inline Evidence
+records, from both analysis calls. Accept variant
+pairing only through the tool's unique exact literal discriminant. Read
+`property_inventories` and each change's `presence` before treating `unknown` as
+"the name was not observed": inventories list observed property names even when
+values stay unknown, with a `source_range` for each paired or unpaired variant.
+Array holes and mutation-invalidated slots are not observed properties.
+Complete parent coverage reports presence-only
+`added`/`removed` independently of unresolved values. Cite the
+comparison Evidence and report JSON Pointer changes; dynamic values, ambiguous
+variants, and incomplete parent-property coverage stay unknown. This is static
+inference, not runtime behavior. When runtime semantics are needed, run
+behavioral probes against the relevant application versions and capture them
+through the available browser, Electron, or process workflows.
+
+## Reusing application Evidence
+
+When advertised by the connected server, application trace and compare tools
+accept complete inline Evidence or
+`{"kind":"retained-evidence","evidence_id":"ev_<64 lowercase hex characters>"}`
+for their application input (`application`, or `left`/`right`). `inspect_analysis_view`
+uses the same retained-reference form in `source`, or portable inline Evidence,
+to project a summary, module page, or one module with its recorded observations. This notation is
+a template: replace it with the actual returned ID. Versions before 4.1.0 accept only full
+inline Evidence. Use the exact ID
+returned by the producer on the same MCP connection. Resolution does not run
+analysis or select a provider; findings remain inline. Native observation
+arrays still take full Evidence. `close_binary` clears retained references;
+export a bundle before closing, or supply portable inline Evidence in another
+connection. A missing reference includes its ID and recovery guidance.

package/skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -0,0 +1,277 @@
+# Native, managed, and packaged artifacts
+
+## Go build metadata
+
+Use `inspect_go_binary` for an explicit local ELF, PE or thin Mach-O when the
+question concerns the embedded compiler version, module/dependency versions,
+local replacements or build settings. No `open_binary`, Go installation or
+target execution is required. The CLI equivalent is `inspect-go-binary PATH`.
+Preserve artifact SHA-256, original file ranges, framed module bytes and every
+unparsed module-text line. A missing record is an unknown, not proof of a
+non-Go binary; observed metadata does not authenticate its claims. Function,
+source and type recovery remain a separate native-analysis question.
+
+## Rust dependency metadata
+
+Use `inspect_rust_binary` for an explicit local ELF, PE, or thin Mach-O when
+the question concerns the cargo-auditable crate list embedded in `.dep-v0`
+(Mach-O: `__DATA,.dep-v0`). No `open_binary`, Rust installation, or target
+execution is required. The CLI equivalent is `inspect-rust-binary PATH`.
+Preserve artifact SHA-256, package order, dependency indices, and the section
+file range. A missing section is null metadata, not proof the binary has no
+dependencies. An omitted package kind stays null. A rustc commit hash is
+inferred from a read-only `/rustc/<40-hex>/` path and does not by itself
+identify the compiler. See [Rust binaries](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md).
+
+## SQLite snapshots
+
+Use `inspect_sqlite_database` with an explicit local database snapshot for its
+schema and optional rows from one exact ordinary table. It requires Node.js
+24.x >=24.15 or 26+ with the native `DatabaseSync.limits` API. It also consumes the
+existing sibling `-wal`; retain both original digests when citing its result.
+Default output is a compact inventory; a selected table expands only its own
+schema and samples 20 rows. Select `columns` to avoid irrelevant or large cells,
+and request `schema_scope: "database"` only for complete schema details.
+Choose `row_limit` when a finite sample is useful and keep truncation and
+unspecified row order explicit. Virtual tables, shadow tables and views are
+schema facts, not row-read targets. REA inspects private copies and leaves
+the source files untouched; obtain a coherent quiescent database/WAL snapshot
+before inspection. See [SQLite snapshots](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md).
+
+## Recorded Linux crashes
+
+Use `inspect_recorded_crash` with an explicit Linux x86-64 ELF core path to
+inspect historical thread registers, signals, raw notes and original file
+ranges. It is independent of the active disassembler target. Source-bound
+register values and note bytes are observations; missing notes, signal-thread
+association and current executable/library identity remain unknown. PIDs are
+historical metadata and never authorize live attach or control.
+
+The optional `include_debugger_context` facet adds mapping candidates through
+caller-supplied GDB/pwndbg in an owned core-only session. Display names do not
+establish current file identity; zero reported flags leave permissions unknown.
+Requested unavailable context fails with setup guidance. See
+[recorded crashes](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md)
+for exact upstream profiles, bounds and verification coverage.
+
+## Offline ELF layout
+
+Use `inspect_binary_layout` with an explicit local ELF path for file-backed
+sections, symbols, relocations, linkage names, and static mitigation inferences
+without opening a disassembler target. When that complete record is already
+retained, call `inspect_analysis_view` for a summary, mitigations or linkage
+facet, one section or symbol, or a stable page. Do not re-run the decoder to
+read a single object.
+
+## Offline WASM
+
+Use `inspect_wasm_artifact` with caller-supplied WABT for selected local bytes.
+For counts, validation and WAT identity, select `detail: "summary"` on the first
+MCP call. The complete original Evidence stays retained; use
+`normalized_result.parent_evidence_id` for exact exports or text pages. Omitted
+or complete detail keeps the existing complete result.
+For a completed result, use `inspect_analysis_view` with its reported retained
+reference for a summary or `view: {kind: "wasm", facet: "exports", offset: 0, limit: 32}`.
+Facets also include sections, imports, candidates, glue, WAT, headers, details
+and tool profile. Text offsets count UTF-16 code units; follow `next_offset`.
+The complete source remains retained after an oversized MCP reply. No target
+execution or network acquisition is implied, and WAT is decoded representation.
+
+## Native targets
+
+After `open_binary`, use focused search, procedure, or function tools directly.
+Use `binary_overview` when target metadata or inventory context helps answer the
+question. Prefer literal search, names, decompilation, callers, callees, and
+cross-references. Addresses and recovered pseudocode are analysis observations,
+not original source. Provider unavailability and unsupported metadata remain
+unknown rather than false.
+
+For a completed `analyze_function` dossier, use `inspect_analysis_view` with
+`view: {kind: "native", facet: "value_flow_operations", offset: 0, limit: 32}`
+and the exact retained Evidence ID to read selected facts without reanalysis.
+Native facets also include procedure, pseudocode, assembly, basic blocks,
+comments, callers/callees, references, unresolved calls, referenced strings and
+names, the native API record, and value-flow summaries. Pseudocode offsets and limits count UTF-16
+code units; use the returned `next_offset` for continuation. Provider limitations
+and unavailable facts remain explicit; the complete parent Evidence is retained.
+
+`inspect_macho` on a large framework returns megabytes of imports and exports.
+Select `detail: "summary"` for slice identity, UUID and per-collection counts,
+then page rows with `view: {kind: "macho", facet: "exports", offset: 0, limit: 64}`
+and `normalized_result.parent_evidence_id`. Facets are entrypoints,
+architectures, build_metadata, load_commands, dependencies, imports, exports,
+segments and provenance. `source_exhaustive: false` means unreturned symbols
+may exist.
+
+To see which functions or Objective-C methods a Mach-O actually calls in one
+run, use `observe_native_calls` with explicit breakpoints and a bounded
+`duration_ms`/`max_events`. It launches a new process under LLDB, so the target
+runs and may change files or use the network. Hardened-runtime targets need the
+`get-task-allow` entitlement.
+
+Use `binary_session` with no arguments to check the open target, selected
+provider, and alignment. Its default `result.tool_availability` carries a
+complete inventory grouped by shared facts. Expand each group's `names` and
+inherit the inventory-level client requirements unless a group overrides them;
+availability, reasons, remediation, modes, and flags remain inline. The
+`effects` and `annotations` arrays name true flags from fixed vocabularies, so an
+omitted known flag is false. `tools/list` remains the canonical source for full
+tool schemas when target or provider state changes.
+
+Provider capability groups carry provider identity and ordered limitations.
+Prepend each set's `shared_limitations` to a group's `limitations` to recover the
+operation's full ordered list. Candidate capabilities describe possible
+providers. Top-level session capabilities describe the current route, and
+`analysis_provider_binding` identifies the selected provider.
+
+## DOS MZ with Ghidra
+
+For an admitted DOS MZ target, use `inspect_native_load_image` to check measured
+loaded bytes, file mappings, relocations and the entry against the immutable
+snapshot. Keep `mismatch` and `unsupported` explicit. Verified import covers the
+reported static image, not runtime DOS or PC-98 hardware behavior.
+
+For Ghidra decompilation, `procedure_pseudo_code` also accepts `procedure: "file-offset:0x..."`; CLI `rea decompile <path> --file-offset=0x... --provider ghidra` resolves the source byte offset internally. An unresolved 0x-prefixed numeric procedure selector also falls back to a unique file mapping. Existing symbols and analysis addresses win; multiple mappings fail as ambiguous. Preserve the returned file-offset and address locations and raw selection observations. ELF virtual addresses are distinct from file offsets; never assume an arbitrary offset plus image base is an analysis address.
+
+Use `read_bytes` for initialized analysis memory and `address_to_file_offset` to
+anchor one observed address to original file bytes. Loader fixups can change a
+word; a source offset does not imply byte equality. Complete function body ranges
+use inclusive ends and can contain gaps. Do not treat the enclosing span as code.
+For packed targets, retain the original and separately derived artifact identities;
+decompiling an unpacking stub does not recover the unpacked program.
+
+When reading Objective-C dispatch metadata, distinguish class implementation
+methods from protocol requirements: class methods report null requirement
+flags, while decoded protocol declarations retain required and optional facts.
+Property attributes remain raw name/value tokens; use the property's
+`atomicity` field for the decoded `N` marker or the default atomic behavior.
+Null class/meta flags, ivar counts, atomicity, or read-only values mean the
+selected provider did not establish that fact. Symbol names alone do not prove
+that a class is a root class or has no ivars.
+
+## Managed PE/CLI
+
+Start with `inspect_managed_artifact`. REA's canonical managed inspection is
+execution-free: do not claim it loaded, reflected, executed, or resolved the
+assembly. Keep managed/native boundaries and unavailable reconstruction facts
+explicit. A bring-your-own reconstruction oracle is separate from the canonical
+parser and must not become an implicit setup dependency.
+
+For identity/classification questions, `inspect_managed_artifact` can explicitly
+select `detail: "summary"` on the first MCP call. It retains complete metadata
+and returns a linked overview with full classification/evidence, nullable
+module/MVID, frameworks, metadata coverage/issues/limitations and returned-row
+counts. Default complete requests remain unchanged. Read original rows with
+`inspect_analysis_view`, source `normalized_result.parent_evidence_id`, and
+`view: {kind: "managed", collection: "attributes", offset: 0, limit: 16}`.
+Collections are `references`, `resources` and `attributes`. Paging does not
+repeat parsing. Returned-row exhaustion
+does not prove complete metadata or absence under partial/unavailable coverage;
+preserve build-local tokens and their artifact/MVID scope.
+
+`inspect_managed_members` always returns the assembly-wide `member_refs`, even
+for one selected type. For questions about a selected type, select
+`detail: "summary"` with `type_names`; it returns the selection (with unmatched
+names), coverage and per-collection counts. Page rows with
+`view: {kind: "managed-members", collection: "call_edges", offset: 0, limit: 64}`
+over `types`, `exported_types`, `fields`, `methods`, `member_refs`, `call_edges`,
+`field_accesses` or `user_strings`.
+
+### .NET NativeAOT
+
+NativeAOT binaries contain native machine code, so ordinary CIL decompilers
+cannot recover the original method bodies. When managed metadata/CIL is absent,
+classify that as a native-analysis route rather than claiming source recovery.
+Open the native image with the selected deep provider and inspect functions,
+strings, calls, and references; describe decompiler output as pseudocode and
+inference.
+
+NativeAOT images can be PE/COFF, ELF, or Mach-O executables and shared
+libraries. Use file bytes and loader metadata rather than suffixes to identify
+them. For packaged apps, inventory/extract with REA's artifact tools and retain
+the exact contained image identity. PDB, ELF debug, or dSYM sidecars are
+additional evidence only when the provider accepts and matches them.
+
+REA has a built-in read-only snapshot parser for x64 PE targets with .NET 8 RTR
+9.1 metadata. An optional headless Ghidra adapter adds database annotations and
+broader metadata recovery on Linux; it requires an explicitly configured
+NativeAOT JAR. These are separate routes. The built-in parser also runs on
+Windows Ghidra P0; read frozen literals from its report, because
+`search_strings` does not include them. See the
+[NativeAOT guide](https://github.com/morluto/rea/blob/main/docs/ghidra-nativeaot.md)
+for setup, supported layouts, and host restrictions. Preserve binary identity
+and distinguish derived metadata from Ghidra database observations. Recovered
+types and native pseudocode are not original C# source. Windows Ghidra P0 has
+no database mutation authority.
+
+## Packages and extraction
+
+Use `inspect_artifact` for application bundles, archives, ZIP/APK/IPA/MSIX/AppX,
+ASAR, or DMG inputs when the artifact graph and findings help answer the
+question. It returns the complete artifact graph inline. Cite graph manifest
+IDs when using them.
+
+For an IPA or a macOS `.app`, ZIP, or DMG, pass the inventory Evidence to
+`project_apple_application_graph`. It reports application roots and nested
+bundles by path convention: app extensions, XPC services, frameworks, login
+items, system and driver extensions, and plug-ins. It also lists privileged
+helpers, launchd plists, symlinks, and each bundle's `info_plist_path` and
+executable candidates. Roles are path conventions, not parsed plists; read the
+listed plists with `inspect_plist`.
+
+After `open_binary` on a `.app` or Mach-O, use `trace_dylib_resolution` to see
+which file each `@rpath`, `@loader_path` and `@executable_path` load reaches for
+every executable in the bundle. It also lists missing or weak loads and earlier
+`@rpath` candidates that are absent. Narrow large bundles with `roots` or
+`architecture`. System paths stay undetermined because the dyld shared cache
+provides them.
+
+Use `extract_artifact` when materialized files are needed. It extracts the active
+target and accepts optional `integrity_policy`; see the [MCP contracts](https://github.com/morluto/rea/blob/main/docs/mcp-contracts.md).
+It materializes all regular files into a fresh temporary directory chosen by
+REA. Symlinks and encrypted entries are inventory facts, not extractable files.
+The result reports the materialized directory; callers do not choose the
+destination. No separate permission grant is needed.
+
+Native DMG traversal automatically uses a read-only mount on supported macOS
+hosts, with an owned temporary mount directory and cleanup. It needs no approval
+flag. Unsupported hosts or mount failures remain explicit limitations; do not
+claim child inventory when only root identity is available. Extraction is a
+separate filesystem-writing operation.
+
+For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI
+`--target-format dos-com`). Inspect the load image before trusting function
+analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment
+context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md).
+
+For other headerless images (embedded firmware without ELF/Mach-O/PE/MZ
+headers), open with `format: "raw-binary"`, `architecture` (`x86`, `x86_64`,
+`arm`, `arm64`, or `6502`), and `entry_point` (`0x` hex). File offset 0 is mapped at
+that address. Hopper and IDA refuse this interpretation; Ghidra uses
+`BinaryLoader` with a little-endian generic language. Big-endian, Thumb-only,
+and Cortex-M variants are unsupported. `6502` selects NMOS 6502; the entry and
+complete file mapping must fit within `0x0000..0xffff`. 65C02, 65816, cartridge
+containers, bank switching, and mapper semantics are unsupported. Windows
+Ghidra P0 admits raw images only for `6502`. See [raw binary guide](https://github.com/morluto/rea/blob/main/docs/raw-binary.md).
+
+### Function annotations in Ghidra
+
+Use `annotate_native_function` for one function name and/or entry comments, with at least one explicit change. Review its annotation readback and refreshed dossier inline. Changes are atomic and session-scoped; empty comments clear them, omitted fields preserve them. Later MCP calls observe edits until close. CLI `annotate-native-function` returns the updated analysis before discarding the session. Original executable bytes are unchanged; edits invalidate immutable snapshots. Windows P0 does not admit database mutations. For naming only, `set_address_name` / `set_addresses_names` also work with Ghidra: they name function entries or data addresses (primary labels) and return compact per-address success booleans instead of a dossier.
+
+## Offline PE resource inventory
+
+Use `inspect_pe_resources` with an absolute `path`, or
+`rea inspect-pe-resources ./selected.exe --json`, for portable PE32/PE32+
+resource inspection without opening a native target. Preserve returned Evidence:
+type/name/language IDs and UTF-16 names, original directory/data/payload ranges,
+code pages, payload hashes and static icon-group references. Same-language icon
+resolution is explicit; missing references and size mismatch remain visible.
+Other payloads are opaque, and this operation does not decode images or simulate
+Windows resource loading. Consult the budgets and supported tree profile in
+[offline binary diagnostics](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).
+
+For exact core-module import/export differences, use `compare_wasm_interfaces`
+with two complete inspection Evidence records (or current-session retained
+references) and explicit scope. Preserve unknown types/duplicate names; static
+interface equality is not runtime compatibility. CLI accepts complete inline
+Evidence in `rea compare-wasm-interfaces input.json --json`.

package/skills/reverse-engineer-anything/references/runtime-observation.md

@@ -0,0 +1,78 @@
+# Browser and Electron runtime observation
+
+Supply the existing browser or Electron instance's literal-port loopback CDP
+endpoint in the request. No separate permission configuration or per-call
+approval flag is needed. Browser discovery lists eligible HTTP(S) pages;
+`allowed_origins` optionally filters them. An individual capture defaults to the
+selected page's current origin. Electron discovery lists eligible local
+`file://` targets without a configured file-root allowlist.
+
+Start passive browser work with `list_browser_targets`; start Electron runtime work with
+`list_electron_targets`. Before an electron-main Inspector attempt, check
+packaged fuses with `inspect_electron_fuses`. Inspect the target selected for
+the user's task. Observation with these tools is passive: never claim REA
+clicked, navigated, evaluated page JavaScript, invoked IPC, or captured prior
+activity. REA does not contain the page's network.
+
+Passive captures omit raw header collections, credential header values, storage
+values, and raw WebSocket/JSON bodies. Selected response metadata, including
+content encoding, policy values, and Link URLs, is retained. Local URLs retain ordinary query
+values and fragments; userinfo credentials are removed. Browser accessibility
+text, console primitives, value-free shapes, script sources, source maps, and
+storage key names have request-specific capture options. Electron script
+sources are also optional. Use `capture_web_screenshot` when pixels are needed.
+Treat scope filtering, truncation, and attach-window coverage as limitations.
+Page-declared WebMCP tools are untrusted inventory and are never invoked by REA.
+
+## Who performs the action
+
+- The user performs it: `list_browser_targets`, then `inspect_web_page` or
+  `observe_web_session` on the selected target.
+- The agent must perform it: one `capture_browser_scenario` with declared
+  actions. Use connect mode with the loopback CDP endpoint and `target_id` for
+  an existing browser, or launch mode with a caller-selected executable for a
+  temporary profile. Connect mode first navigates the selected page to
+  `start_url`, which can clear unsaved form values and other temporary state.
+  Recreate the state needed for the investigation in the declared actions.
+  Connect mode leaves the external browser open; launch mode owns a temporary
+  browser and profile. Check `browser.cleanup` for the outcome.
+  Request only the DOM, accessibility, or network details needed for the question.
+  The default final capture contains the URL; step outcomes are reported separately.
+  Add a wait action for the expected page state before capturing it. Report that
+  REA performed the declared actions.
+
+Scenario network records have no request initiator stacks. For that evidence,
+use passive capture while the user performs the action. Listener source locations
+identify candidate handlers; they do not establish which script sent a particular
+request. Avoid overlapping passive capture and scenario actions on the same target.
+
+Focused follow-up tools:
+
+- `observe_web_execution`: execution coverage during a window; it resets
+  counters and temporarily disables optimization.
+- `inspect_web_event_listeners`: source locations for listeners registered
+  directly on the first CSS match, without dispatching an event.
+- `compare_web_captures`: two normalized passive captures or recorded scenarios.
+- `discover_webmcp_tools`: inspect page-declared WebMCP inventory; never invoke
+  the discovered tools.
+
+Use `reconcile_javascript_runtime` only after static application Evidence and
+passive browser/Electron Evidence exist. Prefer captured-source digest identity;
+report path/digest disagreement as a mismatch and preserve ambiguity. Explicit
+path mappings are inference inputs and never broaden filesystem or CDP authority.
+A bundle observed at runtime does not prove every contained module executed.
+
+## Fiddler Everywhere traffic debugging
+
+For large saved captures, request `detail: "summary"`, then page retained Evidence
+with `inspect_analysis_view` and `view: {kind: "capture", detail: "preview", offset: 0, limit: 20}`.
+Select complete record pages only for needed headers, metadata or payloads; views
+read the historical parent without repeating capture decoding.
+
+Inspect native `.saz` snapshots with `inspect_web_network_capture` and
+`format: "saz"`; encrypted archives are unsupported. For live
+traffic analysis, connect Everywhere's separate MCP server and use its
+advertised session tools with an explicit `sessionsSource` (`LiveTraffic` or
+`AgentCalls`). Preserve existing sessions and filters when inspecting a
+recorded run. See the [capture and MCP guide](https://github.com/morluto/rea/blob/main/docs/web-network-captures.md)
+for the workflow and Telerik's public setup and traffic-debugging skills.

package/src/client/card.tsx

@@ -0,0 +1,120 @@
+/**
+ * 「逆向工程」预设配置卡片：唯一字段是 persona 提示词。
+ *
+ * 经 injectPluginConfigCard 注册（插件页 plugins.row.config / plugins.bundle.config，
+ * view 分发 summary/page）；外壳与草稿语义走 @dsh-plus/shared/client 套件
+ * （CardChrome + useNamespaceDraft：staged 草稿、脏判定、revision fencing、
+ * Host 更新不覆盖在途编辑）。
+ *
+ * 为什么只有这一个字段：`Config` 里只有 `personaPrefix` 标了 `.volatile()`
+ * （对用户的承诺＝必须给编辑器）；MCP 参数、超时、附加 skill 根等属部署方平面，
+ * 由 profile 的 cordis.patch.yml 行级配置覆盖，因此卡片底部只作说明。
+ * 保存后 loader 原位提交活动引用并广播 `loader/volatile-update`，宿主半据此换代
+ * 注册预设声明——新建会话即用新提示词，已存在会话保持原装配。
+ * @module agent-preset-rea/client/card
+ */
+
+import {
+  type CardAction,
+  CardChrome,
+  CardLoading,
+  type NamespaceSettingsApi,
+  type PluginConfigViewProps,
+  type Scope,
+  useNamespaceDraft,
+} from '@dsh-plus/shared/client'
+import type { ReactElement } from 'react'
+import { type ConfigValue, type Draft, draftFromValue, toPatch } from './draft.ts'
+import type { Translate } from './i18n.ts'
+
+export interface CardProps extends PluginConfigViewProps {
+  t: Translate
+  scope: Scope
+  api: NamespaceSettingsApi
+}
+
+/** 卡片动作：放弃 / 保存（仅脏且可写时可用）。 */
+function cardActions(options: {
+  t: Translate
+  dirty: boolean
+  saving: boolean
+  disabled: boolean
+  onDiscard(): void
+  onSave(): void
+}): CardAction[] {
+  return [
+    {
+      key: 'discard',
+      label: options.t('discard'),
+      disabled: !options.dirty || options.saving,
+      onClick: options.onDiscard,
+    },
+    {
+      key: 'save',
+      label: options.t(options.saving ? 'saving' : 'save'),
+      variant: 'primary',
+      disabled: !options.dirty || options.saving || options.disabled,
+      onClick: options.onSave,
+    },
+  ]
+}
+
+export function ReaCard(props: CardProps): ReactElement | string | null {
+  const { t, scope, api } = props
+  const state = useNamespaceDraft<ConfigValue, Draft>({
+    scope,
+    api,
+    from: draftFromValue,
+    patch: toPatch,
+    saveFailedLabel: t('saveFailed'),
+  })
+
+  // 插件页 summary 视图只出一行简介（hooks 已全部落定，可安全提前返回）。
+  if (props.view === 'summary') return t('summaryLine')
+
+  const draft = state.draft
+  if (state.value === undefined || draft === null) {
+    return <CardLoading prefix="apr" text={t('loading')} />
+  }
+
+  const disabled = state.disabled
+  return (
+    <CardChrome
+      prefix="apr"
+      title={t('title')}
+      description={t('description')}
+      dirty={state.dirty}
+      dirtyLabel={t('unsaved')}
+      readOnlyNotice={disabled ? t('readOnly') : undefined}
+      status={state.status}
+      actions={cardActions({
+        t,
+        dirty: state.dirty,
+        saving: state.saving,
+        disabled,
+        onDiscard: state.reset,
+        onSave: state.save,
+      })}
+    >
+      <div className="apr-field">
+        <div className="apr-head">
+          <label className="apr-label" htmlFor="apr-prompt">
+            {t('prompt')}
+          </label>
+        </div>
+        <textarea
+          id="apr-prompt"
+          className="apr-textarea"
+          rows={10}
+          spellCheck={false}
+          placeholder={t('promptPlaceholder')}
+          value={draft.personaPrefix}
+          disabled={disabled}
+          onChange={(event) => state.edit({ personaPrefix: event.target.value })}
+        />
+        <p className="apr-hint">{t('promptHint')}</p>
+        {draft.personaPrefix.trim() === '' ? <p className="apr-hint">{t('promptEmpty')}</p> : null}
+      </div>
+    </CardChrome>
+  )
+}