rea-agents 6.3.0 → 6.5.0

package/dist/contracts/managed/managedWorkflowToolContracts.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { evidenceSchema } from "../../domain/evidence.js";
+import { managedNativeVerificationInputSchema } from "../../domain/managed/managedNativeVerificationSchemas.js";
 import { managedReconstructionImportInputSchema } from "../../domain/managed/managedReconstruction.js";
 import { managedWorkflowOutputSchemas } from "../toolOutputSchemaGroups.js";
 import { MANAGED_MEMBER_COMPARISON_EXAMPLE, MANAGED_NATIVE_VERIFICATION_EXAMPLE, MANAGED_APPLICATION_GRAPH_EXAMPLE, MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE, } from "./managedWorkflowExamples.js";
@@ -23,33 +24,6 @@ export const compareManagedMembersReferenceInputSchema = z
 export const managedReconstructionReferenceInputSchema = managedReconstructionImportInputSchema.extend({
     static_members: evidenceSchema,
 });
-/** Inline Evidence inputs for managed/native verification. */
-export const managedNativeVerificationReferenceInputSchema = z
-    .strictObject({
-    managed_boundaries: evidenceSchema,
-    native_observations: z
-        .array(evidenceSchema)
-        .min(1)
-        .describe("Native function or export Evidence records"),
-})
-    .superRefine((input, context) => {
-    const ids = new Set([input.managed_boundaries.evidence_id]);
-    for (const [index, evidence] of input.native_observations.entries()) {
-        if (evidence.evidence_id === input.managed_boundaries.evidence_id)
-            context.addIssue({
-                code: "custom",
-                path: ["native_observations", index],
-                message: "Native observation Evidence must be distinct from managed boundary Evidence",
-            });
-        if (ids.has(evidence.evidence_id))
-            context.addIssue({
-                code: "custom",
-                path: ["native_observations", index],
-                message: "Native observation Evidence IDs must be unique",
-            });
-        ids.add(evidence.evidence_id);
-    }
-});
 const managedApplicationGraphReferenceFacts = {};
 const managedApplicationGraphReferenceShape = z.strictObject({
     ...managedApplicationGraphReferenceFacts,
@@ -96,7 +70,7 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {
         name: "compare_managed_members",
         ...toolContractMetadata("compare_managed_members"),
-        description: "Compare two authenticated inspect_managed_members Evidence records using unique-only tiers: exact CIL/signature, exact declared type, name, and raw signature (decoded or not), and decoded structural method shape. Names alone are never a matching basis; a member whose signature was not decoded, or whose same-named counterpart's was not, stays unknown rather than added or removed. Metadata tokens remain build-local coordinates bound to each artifact SHA-256 and MVID, and the tuple digest does not itself remap them.",
+        description: "Compare two authenticated inspect_managed_members Evidence records using unique-only tiers: exact declared type, name, and CIL/signature; exact declared type, name, and raw signature (decoded or not); exact declared type, name, and decoded structural method shape; then exact CIL/signature or decoded structural method shape alone, which never takes a member whose own declared type and name remain unpaired on the other side or whose declaring type is unresolved. Names alone are never a matching basis; a member whose signature was not decoded, or whose same-named counterpart's was not, stays unknown rather than added or removed. Metadata tokens remain build-local coordinates bound to each artifact SHA-256 and MVID, and the tuple digest does not itself remap them.",
         kind: "application",
         inputSchema: compareManagedMembersReferenceInputSchema,
         outputSchema: comparisonOutputSchema,
@@ -113,9 +87,9 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {
         name: "verify_managed_native_boundaries",
         ...toolContractMetadata("verify_managed_native_boundaries"),
-        description: "Verify managed P/Invoke/native-boundary declarations against authenticated native export or function Evidence without executing managed code or translating managed metadata tokens into native addresses. The workflow preserves declaration-only, verified, inferred, contradicted, and unresolved states.",
+        description: "Verify managed P/Invoke/native-boundary declarations against authenticated native export or function Evidence without executing managed code or translating managed metadata tokens into native addresses. The workflow preserves declaration-only, verified, inferred, contradicted, and unresolved states; a name candidate with missing managed or native module identity remains unresolved with its candidate evidence retained.",
         kind: "application",
-        inputSchema: managedNativeVerificationReferenceInputSchema,
+        inputSchema: managedNativeVerificationInputSchema,
         outputSchema: nativeVerificationOutputSchema,
         examples: [
             {

package/dist/contracts/mobileApplicationGraphExamples.js

@@ -103,3 +103,15 @@ export const MACOS_APPLICATION_GRAPH_EXAMPLE = {
         }),
     ],
 };
+/** Catalog example for HarmonyOS application inventory projection. */
+export const HARMONY_APPLICATION_GRAPH_EXAMPLE = {
+    inventory_evidence: [
+        createEvidence({ path: "Fixture.hap", sha256: "d".repeat(64), format: "hap" }, provider, {
+            operation: "inventory_artifact",
+            parameters: {},
+            result: inventory("hap", "d"),
+            confidence: "observed",
+            authority: "shipped-artifact",
+        }),
+    ],
+};

package/dist/contracts/native/binaryDiagnosticsToolContracts.js

@@ -1,28 +1,51 @@
 import { inspectRecordedCrashInputSchema, recordedCrashSchema, } from "../../domain/native/recordedCrash.js";
 import { inspectBinaryLayoutInputSchema, binaryLayoutSchema, } from "../../domain/native/binaryLayout.js";
+import { binaryLayoutSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
+import { analysisDetailOutputSchemaOf, analysisDetailSchema, } from "../analysisDetail.js";
 import { toolContractMetadata } from "../toolEffects.js";
 import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { inspectPeResourcesInputSchema, peResourcesSchema, } from "../../domain/native/peResources.js";
+/** Caller-selected delivery of completed binary layout Evidence. */
+export const inspectBinaryLayoutRequestSchema = inspectBinaryLayoutInputSchema.extend({ detail: analysisDetailSchema });
 /** Offline binary diagnostics are independent of macOS process/UI providers. */
 export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [
+    {
+        name: "inspect_pe_resources",
+        ...toolContractMetadata("inspect_pe_resources"),
+        kind: "native-provider",
+        description: "Inspect one explicit local PE32/PE32+ image's complete bounded type/name/language resource tree without executing it or opening a disassembler. Returns numeric IDs versus original UTF-16 names, directory/data-entry file locations, payload RVA/file ranges, complete SHA-256 hashes and static RT_GROUP_ICON image-resource candidates. Language fallback, image decoding and actual shell/window loading remain unobserved. Reads a stable regular file; malformed or ambiguous mappings, non-identical overlapping ranges and exhausted budgets return no partial success. Portable on supported Node hosts; no Windows SDK or engine installation required.",
+        inputSchema: inspectPeResourcesInputSchema,
+        outputSchema: evidenceResultOf(peResourcesSchema),
+        examples: [
+            {
+                title: "Inspect PE resource identities and icon relationships",
+                input: { path: "/artifacts/application.exe" },
+            },
+        ],
+    },
     {
         name: "inspect_binary_layout",
         ...toolContractMetadata("inspect_binary_layout"),
         kind: "native-provider",
-        description: "Inspect an explicit local binary without launching it as a host process. Returns file-backed section/segment ranges, linked addresses, original symbol/REL/RELA table identities, complete encoded RELR tables and upstream-derived offsets with unknown per-word locations/addends, raw name bytes, dependency/interpreter names and static mitigation inferences inline with artifact SHA-256 Evidence. Initial profile: ELF64 x86-64 little-endian EXEC/DYN/REL on Linux x64 via caller-supplied Python with unchanged pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2. Runtime addresses/library paths, overall relocation inventory completeness and complete derived GOT/PLT coverage remain unknown. Zero executable entry values mean absence; relocatable entries are not applicable. Upstream can emulate PLT instructions with Unicorn for derived static maps. Uses bounded complete output and owned temporary files/processes; malformed, unsupported or oversized objects return no partial success.",
-        inputSchema: inspectBinaryLayoutInputSchema,
-        outputSchema: evidenceResultOf(binaryLayoutSchema),
+        description: "Inspect an explicit local binary without launching it as a host process. Returns file-backed section/segment ranges, linked addresses, original symbol/REL/RELA table identities, complete encoded RELR tables and upstream-derived offsets with unknown per-word locations/addends, raw name bytes, dependency/interpreter names and static mitigation inferences inline with artifact SHA-256 Evidence. Initial profile: ELF64 x86-64 little-endian EXEC/DYN/REL on Linux x64 via caller-supplied Python with unchanged pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2. Runtime addresses/library paths, overall relocation inventory completeness and complete derived GOT/PLT coverage remain unknown. Zero executable entry values mean absence; relocatable entries are not applicable. Upstream can emulate PLT instructions with Unicorn for derived static maps. Uses bounded complete output and owned temporary files/processes; malformed, unsupported or oversized objects return no partial success. Select detail summary to retain the complete layout Evidence in this session and receive only its summary view, then inspect sections, symbols, mitigations or linkage with inspect_analysis_view.",
+        inputSchema: inspectBinaryLayoutRequestSchema,
+        outputSchema: analysisDetailOutputSchemaOf(binaryLayoutSchema, binaryLayoutSummaryViewResultSchema),
         examples: [
             {
                 title: "Inspect ELF linked and file layout",
                 input: { path: "/artifacts/application.elf" },
             },
+            {
+                title: "Retain the complete layout and return its summary view",
+                input: { path: "/artifacts/application.elf", detail: "summary" },
+            },
         ],
     },
     {
         name: "inspect_recorded_crash",
         ...toolContractMetadata("inspect_recorded_crash"),
         kind: "native-provider",
-        description: "Inspect a supplied Linux ELF64 amd64 little-endian core without launching its target or attaching to any live PID. Returns all recorded segments, raw note owners/descriptors and source ranges, every Linux CORE PRSTATUS thread/register and SIGINFO fields inline with SHA-256 Evidence. Historical PID is recorded metadata; current process/file identity, note coverage and signal-thread associations stay unknown. Optionally add derived core-only GDB/pwndbg mapping candidates through explicit BYO configuration; zero map flags mean unknown permissions. Uses the same stable snapshot for both stages, bounded complete output and owned cleanup. Initial Linux x64 profile: unchanged pwntools 4.15.0/pyelftools 0.33/Unicorn 2.1.2; optional unchanged pwndbg 2026.09.15. No implicit executable/library pairing, GDB command language, host configuration changes or dependency installation.",
+        description: "Inspect a supplied Linux ELF64 amd64 or AArch64 little-endian core without launching its target or attaching to any live PID. Returns all recorded segments, raw note owners/descriptors and source ranges, every Linux CORE PRSTATUS thread/register and SIGINFO fields inline with SHA-256 Evidence. Historical PID is recorded metadata; current process/file identity, note coverage and signal-thread associations stay unknown. Optionally add derived core-only GDB/pwndbg mapping candidates through explicit BYO configuration; zero map flags mean unknown permissions. Uses the same stable snapshot for both stages, bounded complete output and owned cleanup. Linux x64 host profile: unchanged pwntools 4.15.0/pyelftools 0.33/Unicorn 2.1.2; optional unchanged pwndbg 2026.09.15. No implicit executable/library pairing, GDB command language, host configuration changes or dependency installation.",
         inputSchema: inspectRecordedCrashInputSchema,
         outputSchema: evidenceResultOf(recordedCrashSchema),
         examples: [

package/dist/contracts/native/nativeToolContracts.js

@@ -6,6 +6,7 @@ import { jsonValueSchema } from "../../domain/jsonValue.js";
 import { localPathStringSchema } from "../../domain/localPath.js";
 import { toolContractMetadata } from "../toolEffects.js";
 import { requireOutputSchema } from "../toolOutputSchemaPrimitives.js";
+import { analysisDetailSchema } from "../analysisDetail.js";
 const examples = {
     inspect_macho: {},
     inspect_signature: {},
@@ -53,20 +54,23 @@ const native = (name, description, inputSchema) => {
     };
 };
 /** Ordered single-line symbols; `swift-demangle` ends each result with LF. */
-export const swiftSymbolsSchema = z
-    .array(z
+export const swiftSymbolsSchema = z.array(z
     .string()
     .min(1)
     .regex(/^[^\n]*$/u, "Each Swift symbol must be one line.")
-    .regex(/^[^\x00]*$/u, "Swift symbols cannot contain NUL."))
-    .min(1);
+    .regex(/^[^\x00]*$/u, "Swift symbols cannot contain NUL."));
 /** Provider-neutral semantic operations backed initially by macOS utilities. */
 export const NATIVE_TOOL_CONTRACTS = [
     native("observe_native_ui", "Observe an already-running native app by PID and window ID, bound to the active Mach-O target. Captures a bounded accessibility tree and selected-window screenshot; OS permission denial fails without broad capture or target launch.", nativeUiObservationInputSchema),
     native("capture_native_ui_scenario", "Run selected-element press, increment/decrement scroll, AXValue text entry and bounded wait steps in one exact native app window. Returns ordered before/after captures and action/capture failures. Actions can change app data, network activity and persistent state; application state is left as-is and restoration is not attempted.", nativeUiScenarioInputSchema),
     native("observe_native_calls", "Launch the active Mach-O as an owned process under LLDB and record each entry into caller-selected functions or Objective-C methods: thread, module, symbol, load and file address, raw argument registers, selector, receiver class and optional caller frames. Every hit auto-continues. No expression is evaluated and no other process is attached. The process is killed when max_events or duration_ms is reached; exit status, captured stdout/stderr, unresolved breakpoints and limitations are returned inline. The process runs with the current user's permissions and may change files, show UI or use the network. A hardened-runtime target needs the get-task-allow entitlement.", nativeCallObservationInputSchema),
-    native("inspect_macho", "Inspect Mach-O slices, load commands, imports, exports, dependencies, build metadata, segments, sections, permissions, and exact command provenance without launching Hopper.", z.object({})),
-    native("inspect_signature", "Inspect the active artifact's code-signing identity, hashes, authorities, requirements, entitlements, hardened-runtime state, and exact command provenance.", z.object({})),
+    native("inspect_macho", "Inspect Mach-O slices, load commands, imports, exports, dependencies, build metadata, segments, sections, permissions, and exact command provenance without launching Hopper. Large frameworks return megabytes of symbols; detail summary retains the complete Evidence and returns slice identity with per-collection counts, then page rows with inspect_analysis_view kind macho.", z.object({
+        detail: analysisDetailSchema
+            .unwrap()
+            .optional()
+            .describe("Omitted or complete returns the complete inspection Evidence. summary retains that complete Evidence in this session and returns its inspect_analysis_view summary; use normalized_result.parent_evidence_id for macho pages."),
+    })),
+    native("inspect_signature", "Inspect the active Mach-O executable's code-signing identity, hashes, authorities, requirements, entitlements, hardened-runtime state, and exact command provenance.", z.object({})),
     native("inspect_plist", "Parse Info.plist from the active artifact by default, or pass any local plist path. Returns normalized JSON rather than plutil text.", z.object({
         path: localPathStringSchema.optional(),
     })),

package/dist/contracts/officialToolContracts.js

@@ -26,7 +26,7 @@ export const OFFICIAL_TOOL_CONTRACTS = [
     official("annotate_native_function", "Atomically update one function name and/or entry comments, read them back, and return a refreshed complete function dossier. Ghidra changes its ephemeral session analysis database only; original executable bytes remain unchanged. Empty comment text clears that comment. Edits remain available to subsequent MCP calls until close; CLI returns the updated dossier before discarding its session. Invalid edits roll back the entire operation. Windows P0 and providers without this capability are unsupported.", nativeFunctionAnnotationsInputSchema),
     official("inspect_native_load_image", "Verify the provider's loaded DOS MZ or explicitly selected COM image against its immutable target snapshot: complete original/modified source-byte digests, header/module file mappings and memory digests, relocations and external entry. Returns measured observations and independent checks with mismatch coordinates. COM verification includes its imposed entry register context and does not claim PSP/runtime coverage. Overlay and uninitialized coverage remain explicit; other formats return unsupported. Does not execute or modify the target.", z.strictObject({})),
     official("inspect_native_data_type", "Inspect one recovered type by exact database category path or defined typed data address. Returns observed size, alignment, packing, fields, bitfields, enum values, and child type identities; source-level authority and flexible-tail semantics remain unknown unless substantiated.", nativeDataTypeInputSchema),
-    official("inspect_native_instruction", "Inspect one exact instruction address: decoded bytes, mnemonic, ordered operand tokens, flow and typed references. Memory addressing decomposition is unavailable when the provider supplies only tokens. Data, interior instruction addresses and undecodable bytes are distinct outcomes.", nativeInstructionInputSchema),
+    official("inspect_native_instruction", "Inspect one exact code or data address: decoded bytes, mnemonic, ordered operand tokens, flow, outgoing instruction references and typed incoming references where available. Incoming references preserve source, access kind, operand index and analysis provenance even at data addresses; they do not prove runtime access. Memory addressing decomposition is unavailable when the provider supplies only tokens. Data, interior instruction addresses and undecodable bytes are distinct outcomes.", nativeInstructionInputSchema),
     official("resolve_native_call_targets", "Resolve one explicit static call site using typed provider call references. Preserves ambiguous targets as candidates and unresolved computed calls as unknown; does not execute code or traverse a call graph.", nativeInstructionInputSchema),
     official("address_name", "Resolve the primary analyzed name at a code or data address. Headless providers require an explicit address; GUI providers may default to their current cursor. Null means the provider has no primary name at that address.", z.object({ document, address: optionalAddress })),
     official("comment", "Read the regular analysis comment at an address, defaulting to the current cursor. This is read-only and returns null when no comment exists; use set_comment to persist a finding.", z.object({ document, address: optionalAddress })),
@@ -44,26 +44,26 @@ export const OFFICIAL_TOOL_CONTRACTS = [
     official("next_address", "Return the next analyzed object address after an explicit address or current cursor. This is a navigation primitive, not instruction-flow or CFG analysis.", z.object({ document, address: optionalAddress })),
     official("prev_address", "Return the previous analyzed object start before an explicit address or current cursor. This is a navigation primitive and may fail at document boundaries; data objects and instructions remain distinct from control flow.", z.object({ document, address: optionalAddress })),
     official("procedure_address", "Resolve an unambiguous procedure symbol name or provider-normalized address to its canonical entry address. External address spaces remain explicit.", z.object({ procedure, document })),
-    official("procedure_assembly", "Return assembly for one analyzed procedure identified by symbol or hexadecimal address. Use when pseudocode loses calling-convention or instruction-level detail; output is currently returned as one unpaginated string.", z.object({ procedure, document })),
-    official("procedure_callees", "Return the provider's resolved direct callees for one procedure identified by symbol or address. Unresolved indirect calls may be absent; use analyze_function and typed references to preserve available edge uncertainty.", z.object({ procedure, document })),
-    official("procedure_callers", "Return the provider's resolved direct callers for one procedure identified by symbol or address. Results reflect completed static analysis and may omit unresolved indirect references.", z.object({ procedure, document })),
-    official("procedure_info", "Return provider metadata for one procedure identified by symbol or address: entrypoint, signature, locals, size, block count, and complete inclusive body ranges when observed. Hopper locals preserve observed names and signed stack displacements; source types remain unknown. Body byte count and enclosing span remain distinct; unavailable extent is explicit.", z.object({ procedure, document })),
-    official("read_function_instructions", "Return every raw instruction for one analyzed procedure. Instruction text is provider-specific.", functionInstructionInputSchema),
+    official("procedure_assembly", "Return assembly for one analyzed procedure identified by symbol or hexadecimal address. Use when pseudocode loses calling-convention or instruction-level detail; output is currently returned as one unpaginated string. Ghidra terminal-call assumptions that may cut the analyzed body are reported in Evidence limitations.", z.object({ procedure, document })),
+    official("procedure_callees", "Return the provider's resolved direct callees for one procedure identified by symbol or address. Unresolved indirect calls may be absent; use analyze_function and typed references to preserve available edge uncertainty. Ghidra terminal-call assumptions that may cut the analyzed body are reported in Evidence limitations.", z.object({ procedure, document })),
+    official("procedure_callers", "Return the provider's resolved direct callers for one procedure identified by symbol or address. Results reflect completed static analysis and may omit unresolved indirect references. Ghidra terminal-call assumptions that may cut the analyzed body are reported in Evidence limitations.", z.object({ procedure, document })),
+    official("procedure_info", "Return provider metadata for one procedure identified by symbol or address: entrypoint, signature, locals, size, block count, and complete inclusive body ranges when observed. Extents reflect the provider's analyzed body; Ghidra terminal-call assumptions that may cut it are reported in Evidence limitations. Hopper locals preserve observed names and signed stack displacements; source types remain unknown. Body byte count and enclosing span remain distinct; unavailable extent is explicit.", z.object({ procedure, document })),
+    official("read_function_instructions", "Return every raw instruction for one analyzed procedure. Instruction text and body extent are provider-specific. Ghidra terminal-call assumptions that may cut the analyzed body are reported in limitations.", functionInstructionInputSchema),
     ...HOPPER_MEMORY_TOOL_DEFINITIONS.map(({ name, description, inputSchema }) => official(name, description, inputSchema)),
     official("procedure_references", "Return every raw incoming or outgoing reference edge for one procedure. Endpoint procedures are resolved only from provider containment. Ghidra preserves detailed reference flags. Hopper preserves native CallReference classifications and exact endpoints while leaving unavailable detailed flags explicit.", z.object({
         procedure,
         direction: z.enum(["incoming", "outgoing"]).default("outgoing"),
         document,
     })),
-    official("procedure_pseudo_code", "Decompile one analyzed procedure by symbol name or provider-normalized address. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters.", z.object({ procedure, document })),
+    official("procedure_pseudo_code", "Decompile one analyzed procedure by symbol name or provider-normalized address. Ghidra also accepts file-offset:0x... selectors and falls back to a unique source-file mapping when a 0x-prefixed number resolves to no procedure; existing analysis addresses take precedence and ambiguous mappings fail explicitly. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters. Ghidra no-return assumptions may cut the analyzed body; Evidence limitations report observed terminal calls and available callee identities.", z.object({ procedure, document })),
     official("resolve_containing_procedure", "Resolve an arbitrary address, including an interior instruction or exact external entry, to its provider-analyzed containing procedure. A negative result distinguishes outside segments from not in a procedure and is never guessed from nearby symbols.", z.object({ address, document })),
     official("search_procedures", "Search every analyzed procedure name using literal matching by default or regex when requested. Results are deterministic and complete. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.", z.object(analysisSearchInput)),
-    official("search_strings", "Search every analyzed string object using literal matching by default or regex when requested. Results are deterministic and complete over the native inventory. Hopper retains typed byte decoding, native display, and explicit decoding unknowns. Adjacent long-literal fragments match independently. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.", z.object(analysisSearchInput)),
+    official("search_strings", "Search every provider-defined string object using literal matching by default or regex when requested. Results are deterministic and complete over those defined objects, not every text sequence in artifact bytes. Ghidra may omit packed or undefined literals, including Rust strings; an empty result does not prove text is absent. If an address is known, read_bytes and xrefs inspect its bytes and references. Hopper retains typed byte decoding, native display, and explicit decoding unknowns. Adjacent long-literal fragments match independently. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.", z.object(analysisSearchInput)),
     official("set_address_name", "Assign an analyst name to one mapped hexadecimal address and report whether the native edit succeeded and exact readback matched. Hopper rejects symbol names exceeding 1024 UTF-16 code units before mutation, and rejects names owned by another address; use set_addresses_names to explicitly move or swap labels among selected addresses. This mutates analysis metadata.", z.object({ address, name: z.string(), document })),
     official("set_addresses_names", "Assign analyst names to multiple mapped addresses in one call and return per-address edit/readback success booleans. Hopper validates mapped destinations, native string representations, its 1024 UTF-16 code-unit symbol-name limit, and unique destinations/names before applying edits. Existing labels may move or swap only among explicitly selected addresses; unselected label owners remain unchanged. This mutates analysis metadata; verify failures individually.", z.object({ names: z.record(z.string(), z.string()), document })),
     official("set_bookmark", "Create or replace a bookmark at a mapped hexadecimal address and report success. This mutates navigation metadata; bookmarks are analyst-authored navigation aids, not binary evidence.", z.object({ address, name: z.string().optional(), document })),
     official("set_comment", "Write a regular analysis comment at a hexadecimal address and return whether readback matched. An empty comment clears it. This mutates the Hopper document; use comments to record evidence IDs or reasoning.", z.object({ address, comment: z.string(), document })),
     official("set_inline_comment", "Write an inline instruction comment at a hexadecimal address and return whether readback matched. An empty comment clears it; Hopper may flatten newlines, producing false on exact readback. This mutates analysis metadata.", z.object({ address, comment: z.string(), document })),
     official("unset_bookmark", "Remove the bookmark at a mapped hexadecimal address and return whether it is absent. Hopper also permits removing an existing legacy bookmark outside mapped memory. This mutates navigation metadata and does not alter binary bytes.", z.object({ address, document })),
-    official("xrefs", "Return analyzed references to a code or data address. Hopper may default to its current cursor; headless providers such as Ghidra require an explicit address. Use to connect strings, globals, selectors, and functions; bare addresses are untyped and indirect references may be incomplete.", z.object({ document, address: optionalAddress })),
+    official("xrefs", "Return analyzed references to a code or data address. Hopper may default to its current cursor; headless providers such as Ghidra require an explicit address. Use to connect strings, globals, selectors, and functions; bare addresses are untyped and indirect references may be incomplete. Use inspect_native_instruction at the target address for typed incoming references where supported.", z.object({ document, address: optionalAddress })),
 ];

package/dist/contracts/pcap/pcapToolContracts.js

@@ -0,0 +1,33 @@
+import { pcapInputSchemas, pcapResultSchemas, } from "../../domain/pcap/pcapAnalysis.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { analysisDetailSchema, analysisDetailOutputSchemaOf, } from "../analysisDetail.js";
+import { pcapCaptureSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
+/** Packet-capture analysis served by caller-supplied tshark and capinfos. */
+export const PCAP_TOOL_CONTRACTS = [
+    {
+        name: "inspect_pcap_client",
+        ...toolContractMetadata("inspect_pcap_client"),
+        description: "Inspect the caller-selected tshark and capinfos binaries: selected commands, selection sources, and versions. Both tools must be usable. Reads no capture file. REA never installs the Wireshark suite; select binaries with REA_TSHARK_COMMAND and REA_CAPINFOS_COMMAND (absolute) or from PATH.",
+        kind: "pcap-provider",
+        inputSchema: pcapInputSchemas.inspect_pcap_client,
+        outputSchema: evidenceResultOf(pcapResultSchemas.inspect_pcap_client),
+        examples: [{ title: "Check the analysis tools", input: {} }],
+    },
+    {
+        name: "inspect_pcap_capture",
+        ...toolContractMetadata("inspect_pcap_capture"),
+        description: "Request detail summary for capture identity/counts, then page retained facts with inspect_analysis_view kind pcap. Default detail complete preserves inline delivery. Inspect one saved pcap or pcapng capture through an owned snapshot: metadata, exact packet count, SHA-256, IPv4/IPv6 address counts, DNS questions and address values from the same single-question response, TLS SNI, protocol distribution and HTTP URIs. All derived inventories are retained within declared resource budgets; unknown DNS attribution and excluded credentials remain explicit. Linux requires util-linux prlimit; Windows uses owned Job Objects. Requires caller-supplied capinfos and tshark; REA never captures traffic.",
+        kind: "pcap-provider",
+        inputSchema: pcapInputSchemas.inspect_pcap_capture.extend({
+            detail: analysisDetailSchema,
+        }),
+        outputSchema: analysisDetailOutputSchemaOf(pcapResultSchemas.inspect_pcap_capture, pcapCaptureSummaryViewResultSchema),
+        examples: [
+            {
+                title: "Inspect a capture file",
+                input: { path: "/captures/session.pcap" },
+            },
+        ],
+    },
+];

package/dist/contracts/providerSelection.js

@@ -17,6 +17,7 @@ export const PROVIDER_REJECTION_CODES = [
     "not_configured",
     "executable_missing",
     "runtime_missing",
+    "runtime_unavailable",
     "unsupported_host",
     "unsupported_version",
     "target_kind_unsupported",

package/dist/contracts/reconstructionReadinessExample.js

@@ -1,6 +1,7 @@
 import { createEvidence } from "../domain/evidence.js";
 import { createEvidenceBundle } from "../domain/evidenceBundle.js";
 import { READINESS_REQUIRED_CHECKS, READINESS_STAGE_IDS, } from "../domain/reconstructionReadinessJourneyFindings.js";
+import { reconstructionObligationLedgerClosureDigest } from "../domain/reconstructionObligationLedgerIntegrity.js";
 const HASH = "a".repeat(64);
 const sourceEvidence = (variant) => createEvidence(undefined, {
     id: "rea-readiness-fixture",
@@ -59,6 +60,129 @@ const EVIDENCE_STATES = [
     "reviewed",
     "unknown",
 ];
+const READINESS_OBLIGATION_LEDGER = (() => {
+    const ledger = {
+        schema: "ReconstructionObligationLedger",
+        ledger_id: `rol_${HASH}`,
+        status: "ready",
+        coverage: {
+            status: "complete",
+        },
+        summary: {
+            total: 1,
+            required: 1,
+            verified: 1,
+            required_open: 0,
+            by_status: STATUSES.map((key) => ({
+                key,
+                count: key === "verified" ? 1 : 0,
+            })),
+            by_application_layer: LAYERS.map((key) => ({
+                key,
+                count: key === "process" ? 1 : 0,
+            })),
+            by_evidence_authority: EVIDENCE_STATES.map((key) => ({
+                key,
+                count: key === "observed" ? 1 : 0,
+            })),
+        },
+        reports: {
+            missing_owner_obligation_ids: [],
+            missing_verifier_obligation_ids: [],
+            contradicted_obligation_ids: [],
+            residual_unknown_ids: [],
+        },
+        ownership_graph: [
+            {
+                obligation_id: "obl.readiness",
+                module_path: "src/readiness.ts",
+                symbol: "runReadiness",
+            },
+        ],
+        dependency_graph: [],
+        obligations: [
+            {
+                obligation_id: "obl.readiness",
+                obligation_version: 1,
+                title: "Preserve the packaged readiness fixture lifecycle",
+                origin: "reviewed",
+                application_layer: "process",
+                family: "packaged-process-lifecycle",
+                target: {
+                    artifact_sha256: HASH,
+                    application_node_id: null,
+                    semantic_node_id: null,
+                    location: "/fixture",
+                },
+                authority_references: [
+                    {
+                        evidence_id: EVIDENCE_ID,
+                        authority: "controlled-replay",
+                        state: "observed",
+                        location: "/fixture",
+                    },
+                ],
+                source_state: "observed",
+                observed_cases: CASES.map((kind) => ({
+                    kind,
+                    evidence_id: EVIDENCE_ID,
+                    location: `/original/${kind}`,
+                })),
+                required: true,
+                required_case_kinds: [...CASES],
+                required_original_authority: "process",
+                required_fixture_authority: "packaged-process",
+                required_verifier_authority: "packaged-process",
+                requires_parser_type: false,
+                dependency_obligation_ids: [],
+                residual_unknown_ids: [],
+                unavailable_authority: [],
+                required_next_evidence: [],
+                binding: {
+                    obligation_id: "obl.readiness",
+                    owner: {
+                        module_path: "src/readiness.ts",
+                        symbol: "runReadiness",
+                        owner_sha256: HASH,
+                    },
+                    parser_type: null,
+                    original_cases: CASES.map((kind) => ({
+                        kind,
+                        evidence_id: EVIDENCE_ID,
+                        location: `/original/${kind}`,
+                    })),
+                    fixtures: CASES.map((kind) => ({
+                        fixture_id: `fixture.${kind}`,
+                        case_kind: kind,
+                        authority: "packaged-process",
+                        evidence_ids: [EVIDENCE_ID],
+                    })),
+                    verifier: {
+                        verifier_id: "verifier.readiness",
+                        claim_id: "claim.readiness",
+                        command: "npm run verify:readiness",
+                        authority: "packaged-process",
+                        status: "pass",
+                        result_evidence_id: EVIDENCE_ID,
+                        enumerated_obligation_ids: ["obl.readiness"],
+                        nondeterminism: {
+                            mode: "partial-order",
+                            specification: "Startup precedes teardown.",
+                        },
+                    },
+                },
+                status: "verified",
+                diagnostics: [],
+            },
+        ],
+        evidence_links: [EVIDENCE_ID],
+        limitations: [],
+    };
+    return {
+        ...ledger,
+        closure_digest: reconstructionObligationLedgerClosureDigest(ledger),
+    };
+})();
 /** Complete synthetic input shared by docs, tests, CLI, MCP, and verifier. */
 export const RECONSTRUCTION_READINESS_EXAMPLE = {
     identity: {
@@ -206,124 +330,7 @@ export const RECONSTRUCTION_READINESS_EXAMPLE = {
             evidence_ids: [EVIDENCE_ID, CONTRADICTING_SOURCE.evidence_id],
         },
     ],
-    obligation_ledger: {
-        schema: "ReconstructionObligationLedger",
-        ledger_id: `rol_${HASH}`,
-        closure_digest: HASH,
-        status: "ready",
-        coverage: {
-            status: "complete",
-        },
-        summary: {
-            total: 1,
-            required: 1,
-            verified: 1,
-            required_open: 0,
-            by_status: STATUSES.map((key) => ({
-                key,
-                count: key === "verified" ? 1 : 0,
-            })),
-            by_application_layer: LAYERS.map((key) => ({
-                key,
-                count: key === "process" ? 1 : 0,
-            })),
-            by_evidence_authority: EVIDENCE_STATES.map((key) => ({
-                key,
-                count: key === "observed" ? 1 : 0,
-            })),
-        },
-        reports: {
-            missing_owner_obligation_ids: [],
-            missing_verifier_obligation_ids: [],
-            contradicted_obligation_ids: [],
-            residual_unknown_ids: [],
-        },
-        ownership_graph: [
-            {
-                obligation_id: "obl.readiness",
-                module_path: "src/readiness.ts",
-                symbol: "runReadiness",
-            },
-        ],
-        dependency_graph: [],
-        obligations: [
-            {
-                obligation_id: "obl.readiness",
-                obligation_version: 1,
-                title: "Preserve the packaged readiness fixture lifecycle",
-                origin: "reviewed",
-                application_layer: "process",
-                family: "packaged-process-lifecycle",
-                target: {
-                    artifact_sha256: HASH,
-                    application_node_id: null,
-                    semantic_node_id: null,
-                    location: "/fixture",
-                },
-                authority_references: [
-                    {
-                        evidence_id: EVIDENCE_ID,
-                        authority: "controlled-replay",
-                        state: "observed",
-                        location: "/fixture",
-                    },
-                ],
-                source_state: "observed",
-                observed_cases: CASES.map((kind) => ({
-                    kind,
-                    evidence_id: EVIDENCE_ID,
-                    location: `/original/${kind}`,
-                })),
-                required: true,
-                required_case_kinds: [...CASES],
-                required_original_authority: "process",
-                required_fixture_authority: "packaged-process",
-                required_verifier_authority: "packaged-process",
-                requires_parser_type: false,
-                dependency_obligation_ids: [],
-                residual_unknown_ids: [],
-                unavailable_authority: [],
-                required_next_evidence: [],
-                binding: {
-                    obligation_id: "obl.readiness",
-                    owner: {
-                        module_path: "src/readiness.ts",
-                        symbol: "runReadiness",
-                        owner_sha256: HASH,
-                    },
-                    parser_type: null,
-                    original_cases: CASES.map((kind) => ({
-                        kind,
-                        evidence_id: EVIDENCE_ID,
-                        location: `/original/${kind}`,
-                    })),
-                    fixtures: CASES.map((kind) => ({
-                        fixture_id: `fixture.${kind}`,
-                        case_kind: kind,
-                        authority: "packaged-process",
-                        evidence_ids: [EVIDENCE_ID],
-                    })),
-                    verifier: {
-                        verifier_id: "verifier.readiness",
-                        claim_id: "claim.readiness",
-                        command: "npm run verify:readiness",
-                        authority: "packaged-process",
-                        status: "pass",
-                        result_evidence_id: EVIDENCE_ID,
-                        enumerated_obligation_ids: ["obl.readiness"],
-                        nondeterminism: {
-                            mode: "partial-order",
-                            specification: "Startup precedes teardown.",
-                        },
-                    },
-                },
-                status: "verified",
-                diagnostics: [],
-            },
-        ],
-        evidence_links: [EVIDENCE_ID],
-        limitations: [],
-    },
+    obligation_ledger: READINESS_OBLIGATION_LEDGER,
     operation_outcomes: [
         {
             sequence: 0,
@@ -393,7 +400,7 @@ export const RECONSTRUCTION_READINESS_EXAMPLE = {
         },
         {
             sequence: 1,
-            ledger_digest: HASH,
+            ledger_digest: READINESS_OBLIGATION_LEDGER.closure_digest,
             status: "ready",
             required_open: 0,
             newly_verified_obligation_ids: ["obl.readiness"],

package/dist/contracts/reverseEngineeringToolContracts.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { objdumpInputSchema, rizinInputSchema, } from "../domain/reverseEngineering.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "./toolEffects.js";
+const commandObservationSchema = z.strictObject({
+    stdout: z.string(),
+    stderr: z.string(),
+    exit_code: z.union([z.string(), z.number(), z.null()]),
+    signal: z.string().nullable(),
+    output_truncated: z.boolean(),
+    completion_status: z.enum(["complete", "unknown"]),
+    artifact_sha256_after: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    artifact_changed: z.boolean().nullable(),
+});
+/** Caller-selected GNU objdump and Rizin observations. */
+export const REVERSE_ENGINEERING_TOOL_CONTRACTS = [
+    {
+        name: "inspect_with_objdump",
+        ...toolContractMetadata("inspect_with_objdump"),
+        kind: "native-provider",
+        description: "Run caller-selected GNU objdump inspection against a local artifact, or request operation=architectures without a path to list BFD targets advertised by the installed binary. Preserves decoded stdout and stderr inline with SHA-256 Evidence for artifact inspections, up to a shared 16 MiB combined limit; invalid UTF-8 bytes are represented by replacement characters and flagged in Evidence limitations. output_truncated reports output beyond that limit and completion_status is unknown if buffer enforcement terminated the process. The raw output is authoritative and REA does not claim a stable normalized format. DWARF does not follow local debug links by default. Set follow_debug_links to true to follow them; identities of external debug files are not bound to Evidence. REA clears DEBUGINFOD_URLS for objdump so DWARF processing does not make debuginfod network requests. Architecture output is subjectless and does not establish support for any artifact.",
+        inputSchema: objdumpInputSchema,
+        outputSchema: evidenceResultOf(commandObservationSchema),
+        examples: [
+            {
+                title: "Disassemble code sections",
+                input: { path: "/tmp/program", operation: "disassemble" },
+            },
+            {
+                title: "List advertised BFD targets",
+                input: { operation: "architectures" },
+            },
+        ],
+    },
+    {
+        name: "execute_rizin_command",
+        ...toolContractMetadata("execute_rizin_command"),
+        kind: "native-provider",
+        description: "Execute one caller-selected Rizin command against a local artifact using the Rizin CLI profile that suppresses user settings and scripts while retaining plugins. Preserves decoded stdout and stderr inline with SHA-256 Evidence, up to a shared 16 MiB combined limit; invalid UTF-8 bytes are represented by replacement characters and flagged in Evidence limitations. output_truncated reports output beyond that limit and completion_status is unknown if buffer enforcement terminated the process. Rizin commands and retained plugins can execute foreign code, mutate files, access the network, and read files outside the selected artifact; identities and contents of those external inputs are not bound to Evidence. Command effects depend on the Rizin command and loaded plugins; JSON is command-specific and raw output remains authoritative. In a shared MCP server, this admitted command closes any active binary-analysis session; after its effects have settled, call open_binary before further analysis. Close an active Ghidra session explicitly first.",
+        inputSchema: rizinInputSchema,
+        outputSchema: evidenceResultOf(commandObservationSchema),
+        examples: [
+            {
+                title: "Inspect binary information",
+                input: { path: "/tmp/program", command: "iI" },
+            },
+        ],
+    },
+];