rea-agents 5.0.0 → 6.1.0

package/dist/composition/webNetworkCaptures.js

@@ -0,0 +1,6 @@
+import { WebNetworkCaptureService } from "../application/WebNetworkCaptureService.js";
+import { HistoricalCaptureDecoder } from "../browser/history/HistoricalCaptureDecoder.js";
+import { HarCaptureAdapter } from "../browser/history/HarCaptureAdapter.js";
+import { MitmproxyCaptureAdapter } from "../browser/history/MitmproxyCaptureAdapter.js";
+/** Compose offline format adapters without import-time reads, installation or process startup. */
+export const createWebNetworkCaptureService = (environment = process.env) => new WebNetworkCaptureService(new HistoricalCaptureDecoder([new HarCaptureAdapter(), new MitmproxyCaptureAdapter(environment)], environment));

package/dist/config/environment.js

@@ -3,8 +3,11 @@ import { isAbsolute } from "node:path";
 import { ConfigurationError } from "../domain/configurationErrors.js";
 import { err, ok } from "../domain/result.js";
 import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
+import { ghidraStartupTimeoutSchema } from "./ghidraStartupTimeout.js";
+import { mcpResponseBudgetSchema } from "./mcpResponseBudget.js";
 const environmentSchema = z.object({
     REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),
+    REA_MCP_MAX_RESPONSE_BYTES: mcpResponseBudgetSchema.optional(),
     REA_IDA_MCP_CONFIG: z
         .string()
         .min(1)
@@ -25,6 +28,7 @@ const environmentSchema = z.object({
         .min(1)
         .refine(isAbsolute, "REA_GHIDRA_NATIVEAOT_JAR must be absolute")
         .optional(),
+    REA_GHIDRA_STARTUP_TIMEOUT_MS: ghidraStartupTimeoutSchema,
     REA_ILSPY_CMD_PATH: z
         .string()
         .min(1)

package/dist/config/ghidraStartupTimeout.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/** Default absolute deadline for Ghidra import, analysis, bridge, and readiness. */
+export const DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS = 330_000;
+// Node schedules delays above this signed 32-bit boundary as a 1 ms timer.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Parse the optional setting without reading the ambient process environment. */
+export const ghidraStartupTimeoutSchema = z
+    .string()
+    .optional()
+    .transform((raw) => {
+    const value = Number(raw);
+    return Number.isSafeInteger(value) &&
+        value > 0 &&
+        value <= MAX_TIMER_DELAY_MS
+        ? value
+        : DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS;
+});

package/dist/config/mcpResponseBudget.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { err, ok } from "../domain/result.js";
+// This override supports clients with larger frames. Keep the configuration
+// parser independent of the SDK's eager server imports; conformance verifies
+// this floor against the pinned SDK's actual default receive-buffer size.
+const MINIMUM_RESPONSE_BYTES = 10 * 1024 * 1024;
+/** Optional stdio response budget, including room for the protocol envelope. */
+export const mcpResponseBudgetSchema = z
+    .string()
+    .regex(/^[1-9]\d*$/u)
+    .transform(Number)
+    .pipe(z.number().int().safe().min(MINIMUM_RESPONSE_BYTES));
+/** Parse only the MCP-specific budget without loading unrelated provider settings. */
+export const parseMcpResponseBudget = (value) => {
+    if (value === undefined)
+        return ok(undefined);
+    const parsed = mcpResponseBudgetSchema.safeParse(value);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new ConfigurationError(`REA_MCP_MAX_RESPONSE_BYTES must be a decimal safe integer at least ${String(MINIMUM_RESPONSE_BYTES)} bytes, the default stdio receive-buffer size.`));
+};

package/dist/config/parseConfig.js

@@ -16,7 +16,7 @@ const executableAvailable = (path) => {
         return false;
     }
 };
-export const defaultHopperLauncherPath = (platform = process.platform, homeDirectory = homedir(), executable = executableAvailable) => {
+const defaultHopperLauncherPath = (platform = process.platform, homeDirectory = homedir(), executable = executableAvailable) => {
     if (platform !== "linux")
         return DEFAULT_HOPPER_LAUNCHER_PATH;
     if (executable(SYSTEM_LINUX_HOPPER))
@@ -43,6 +43,7 @@ export const parseConfig = (environment) => {
             : { idaMcpConfigPath: env.REA_IDA_MCP_CONFIG }),
         ghidraInstallDir: env.GHIDRA_INSTALL_DIR,
         ghidraJavaHome: env.JAVA_HOME,
+        ghidraStartupTimeoutMs: env.REA_GHIDRA_STARTUP_TIMEOUT_MS,
         ...(env.REA_GHIDRA_NATIVEAOT_JAR === undefined
             ? {}
             : { ghidraNativeAotJar: env.REA_GHIDRA_NATIVEAOT_JAR }),

package/dist/contracts/artifactToolContracts.js

@@ -4,6 +4,7 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
 import { appleAssetCatalogInputSchema } from "../domain/apple/appleAssetCatalog.js";
+import { dylibResolutionInputSchema } from "../domain/apple/dylibResolution.js";
 import { keyedArchiveInputSchema } from "../domain/apple/keyedArchive.js";
 /** Exact caller boundary for deterministic artifact inventory. */
 export const artifactInventoryInputSchema = z.strictObject({
@@ -22,6 +23,10 @@ const examples = {
     decode_interface_builder: {},
     inspect_asset_catalog: { offset: 0, limit: 1000 },
     inspect_keyed_archive: { path: "Contents/Resources/Model.plist" },
+    trace_dylib_resolution: {
+        roots: ["Contents/MacOS/App"],
+        architecture: "arm64",
+    },
 };
 const artifact = (name, description, inputSchema) => {
     const outputSchema = requireOutputSchema(artifactOutputSchemas, name);
@@ -51,6 +56,7 @@ export const ARTIFACT_TOOL_CONTRACTS = [
     })),
     artifact("inspect_keyed_archive", "Inspect one Foundation NSKeyedArchiver plist in the active app bundle as original object-table nodes, class descriptors, named roots, and UID edges. Preserves shared and cyclic references without instantiating classes. The path is relative to the bundle; root selection and object pagination preserve original identities.", keyedArchiveInputSchema),
     artifact("inspect_asset_catalog", "Inspect compiled Assets.car metadata in an active Apple app bundle. Returns stable paginated catalog and rendition records with raw assetutil metadata and catalog digests; rendition bytes are not extracted.", appleAssetCatalogInputSchema),
+    artifact("trace_dylib_resolution", "Trace how dyld would resolve each Mach-O dylib load for the active Mach-O, or for every executable in the active .app bundle (the main app, XPC services, extensions, login items, helpers). Expands @executable_path, @loader_path, and @rpath through each process's LC_RPATH stack in dependents-first load order, and reports every candidate path with its outcome, the resolved image and digest, weak, re-export, and upward flags, and derived findings such as unresolved required loads or absent earlier @rpath candidates. Pure header parsing: nothing is executed, and absolute or system paths outside the analyzed root stay undetermined. Select roots or one architecture to narrow large bundles.", dylibResolutionInputSchema),
 ];
 /** Provider operations; inventory remains an internal primitive of inspection. */
 export const ARTIFACT_ANALYSIS_OPERATIONS = [

package/dist/contracts/browserCaptureToolInputSchema.js

@@ -0,0 +1,43 @@
+import { browserCaptureComparisonInputSchema } from "../domain/browserCaptureComparison.js";
+import { browserScenarioCaptureSchema } from "../domain/browserScenarioCapture.js";
+import { captureSnapshotSchema } from "../domain/webCaptureDiffSchemas.js";
+// Captures are complete producer results to pass back unchanged, rather than
+// analyst-authored options. Describe that boundary without embedding the entire
+// inspection result schema in every comparison input. The cloned parser still
+// validates every nested field using the canonical domain schemas.
+const passiveCaptureInputSchema = captureSnapshotSchema.clone(captureSnapshotSchema.def);
+passiveCaptureInputSchema._zod.toJSONSchema = () => ({
+    type: "object",
+    properties: {
+        inspection: {
+            type: "object",
+            description: "Complete result object returned by inspect_web_page. Pass the entire result unchanged, including capture identity, observations, completeness, and limitations. Every nested field is validated by REA.",
+        },
+        webmcp: {
+            anyOf: [{ type: "object" }, { type: "null" }],
+            default: null,
+            description: "Complete result object returned by discover_webmcp_tools for this capture, or null when it was not recorded. Pass the entire result unchanged. Every nested field is validated by REA.",
+        },
+    },
+    required: ["inspection"],
+});
+const scenarioCaptureInputSchema = browserScenarioCaptureSchema.clone(browserScenarioCaptureSchema.def);
+scenarioCaptureInputSchema._zod.toJSONSchema = () => ({
+    type: "object",
+    description: "Complete result object returned by capture_browser_scenario. Pass the entire result unchanged, including browser and scenario identity, steps, events, artifact contents and digests, completeness, and limitations. Every nested field is validated by REA.",
+});
+/** Advertise capture round trips while retaining full runtime validation. */
+export const browserCaptureToolInputSchema = browserCaptureComparisonInputSchema.safeExtend({
+    before: passiveCaptureInputSchema
+        .optional()
+        .describe("Earlier passive web-page capture with complete producer results."),
+    after: passiveCaptureInputSchema
+        .optional()
+        .describe("Later passive web-page capture with complete producer results."),
+    before_scenario: scenarioCaptureInputSchema
+        .optional()
+        .describe("Earlier complete result object returned by capture_browser_scenario."),
+    after_scenario: scenarioCaptureInputSchema
+        .optional()
+        .describe("Later complete result object returned by capture_browser_scenario."),
+});

package/dist/contracts/browserToolContracts.js

@@ -2,10 +2,11 @@ import { browserTargetListSchema, inspectWebPageInputSchema, listBrowserTargetsI
 import { analyzeWebBundleInputSchema, webBundleAnalysisSchema, } from "../domain/webBundleAnalysis.js";
 import { observeWebSessionInputSchema, webObservationSessionSchema, } from "../domain/browserSession.js";
 import { discoverWebMcpToolsInputSchema, webMcpDiscoverySchema, } from "../domain/webMcpDiscovery.js";
-import { browserCaptureComparisonInputSchema, browserCaptureComparisonSchema, } from "../domain/browserCaptureComparison.js";
+import { browserCaptureComparisonSchema } from "../domain/browserCaptureComparison.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, webScreenshotDiffSchema, webScreenshotSchema, } from "../domain/webScreenshot.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemas.js";
+import { browserCaptureToolInputSchema } from "./browserCaptureToolInputSchema.js";
 const evidenceResult = evidenceResultOf;
 const listOutputSchema = evidenceResult(browserTargetListSchema);
 const inspectionOutputSchema = evidenceResult(webPageInspectionSchema);
@@ -181,9 +182,9 @@ export const BROWSER_TOOL_CONTRACTS = [
     {
         name: "compare_web_captures",
         ...toolContractMetadata("compare_web_captures"),
-        description: "Compare passive web captures by providing before and after, or compare recorded scenarios by providing before_scenario and after_scenario with an optional normalization policy. Use exactly one input group. Scenario comparison aligns exact step IDs, records deterministic literal normalization, and returns every artifact-level difference plus alignment failures inline. Missing or truncated evidence never proves equality.",
+        description: "Compare passive web captures by providing before and after, each with the complete inspect_web_page result in inspection and an optional complete discover_webmcp_tools result in webmcp; or compare recorded scenarios by passing complete capture_browser_scenario results in before_scenario and after_scenario with an optional normalization policy. Use exactly one input group. Scenario comparison aligns exact step IDs, records deterministic literal normalization, and returns every artifact-level difference plus alignment failures inline. Missing or truncated evidence never proves equality.",
         kind: "browser-provider",
-        inputSchema: browserCaptureComparisonInputSchema,
+        inputSchema: browserCaptureToolInputSchema,
         outputSchema: captureDiffOutputSchema,
         examples: [
             {

package/dist/contracts/enhancedInputs.js

@@ -18,7 +18,9 @@ export const enhancedInputSchemas = {
             .default([]),
     }),
     get_call_graph: z.strictObject({
-        address: z.string().describe("A provider-normalized procedure address"),
+        address: z
+            .string()
+            .describe("A procedure symbol or address to resolve to its canonical entry"),
         direction: z.enum(["forward", "backward"]).default("forward"),
     }),
     analyze_swift_types: z.strictObject({
@@ -41,10 +43,10 @@ export const enhancedInputSchemas = {
     }),
     trace_feature: traceLiteralInputSchema,
     trace_call_path: z.strictObject({
-        start: z.string().describe("A provider-normalized procedure address"),
+        start: z.string().describe("A starting procedure symbol or address"),
         goal: z
             .string()
-            .describe("An optional provider-normalized destination address")
+            .describe("An optional destination procedure symbol or address")
             .optional(),
         direction: z.enum(["forward", "backward"]).default("forward"),
     }),

package/dist/contracts/enhancedToolContracts.js

@@ -19,13 +19,13 @@ export const ENHANCED_TOOL_CONTRACTS = [
     enhanced("get_objc_classes", "Discover and deduplicate Objective-C class labels, optionally filtering by literal substring.", enhancedInputSchemas.get_objc_classes),
     enhanced("get_objc_protocols", "Discover and deduplicate Objective-C and Swift protocol labels.", enhancedInputSchemas.get_objc_protocols),
     enhanced("batch_decompile", "Decompile each explicit procedure symbol or address concurrently. Returns ordered per-item success or error results and aggregate counts.", enhancedInputSchemas.batch_decompile),
-    enhanced("get_call_graph", "Traverse the bound provider's caller or callee relationships from one symbol or address until the reachable graph is exhausted. Every node has an ok/error status and failures use safe typed projections; unresolved indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
+    enhanced("get_call_graph", "Resolve one symbol or address to its canonical procedure entry, then traverse the bound provider's caller or callee relationships until the reachable graph is exhausted. Every node uses a canonical address and has an ok/error status; failures use safe typed projections. Unresolved indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
     enhanced("analyze_swift_types", 'Categorize analyzed procedure names into Swift classes, structs, enums, protocols, extensions, and other symbols. Returns deduplicated names grouped with counts. Optionally select one category and/or apply a case-sensitive literal name filter; for example, use {category: "classes", pattern: "Account"} to find matching class symbols.', enhancedInputSchemas.analyze_swift_types),
     enhanced("find_xrefs_to_name", "Resolve an exact name against the bound provider's name inventory and return a resolved or unresolved result. Unresolved names use the stable name_not_found reason; this xref workflow returns address-only projections.", enhancedInputSchemas.find_xrefs_to_name),
     enhanced("binary_overview", "Return native-binary metadata, every segment with its length, and exhaustive procedure/string counts. Use search_procedures, list_procedures, or analyze_function directly when you already know which procedure to inspect.", enhancedInputSchemas.binary_overview),
     ...FUNCTION_WORKFLOW_TOOL_CONTRACTS,
-    enhanced("trace_feature", "Trace a literal feature query through every matching string and procedure, their xrefs, and truthful containing-procedure resolution. Returns observations, operation count, and residual unknowns without inferring reference kinds.", enhancedInputSchemas.trace_feature),
-    enhanced("trace_call_path", "Trace direct callers or callees from one exact procedure address until the graph is exhausted or the optional goal is reached. Returns visited nodes, direct-call edges, a shortest traversal path, provider failures, and residual unknowns; unresolved indirect calls remain unknown.", enhancedInputSchemas.trace_call_path),
+    enhanced("trace_feature", "Trace the complete literal query, preserving spaces, through every matching string and procedure, their xrefs, and truthful containing-procedure resolution. Returns observations, operation count, and residual unknowns without inferring reference kinds.", enhancedInputSchemas.trace_feature),
+    enhanced("trace_call_path", "Resolve start and optional goal symbols or addresses to canonical procedure entries, then trace direct callers or callees until the graph is exhausted or the goal is reached. Results use canonical addresses; Evidence preserves supplied selectors. Returns visited nodes, direct-call edges, a shortest traversal path, provider failures, and residual unknowns; unresolved indirect calls remain unknown.", enhancedInputSchemas.trace_call_path),
     enhanced("trace_native_ui_action", "Trace one unique compiled UI action, object ID, native symbol or exact function address through authored connections, encoded or symbolized Objective-C handlers, and bounded static call references. Typed direct and resolved indirect calls, ambiguous candidates, inferred untyped provider callees, and targetless sites remain distinct. Runtime reachability is unknown; use trace_native_values for recovered value dependencies.", enhancedInputSchemas.trace_native_ui_action),
     enhanced("trace_native_values", "Trace a bounded static dependency graph from one explicit native procedure. Includes high-p-code def-use, constants, operators, memory and branch operations, resolved call edges, and derived argument/parameter and return/output bindings. Missing bindings, alias semantics, persistent state and RNG roles remain unknown. Budgets bound depth, decompilations, graph size and payloads; nodes are paginated.", enhancedInputSchemas.trace_native_values),
 ];

package/dist/contracts/errorSchemas.js

@@ -1,11 +1,14 @@
 import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 const categorySchema = z.enum([
     "invalid_input",
     "unsupported_provider",
+    "unsupported_target",
     "integrity_mismatch",
     "truncated",
     "cancelled",
     "timeout",
+    "resource_constraint",
     "unavailable",
     "execution_failure",
 ]);
@@ -20,17 +23,21 @@ const common = {
     retryable: z.boolean(),
     remediation: remediationSchema,
 };
-const genericDetails = z.record(z.string(), z.json()).optional();
+const genericDetails = z.record(z.string(), jsonValueSchema).optional();
 const generic = (code) => z
     .object({ code: z.literal(code), ...common, details: genericDetails })
     .strict();
 /** Stable discriminated schema shared by every CLI and MCP error surface. */
 export const analysisErrorProjectionSchema = z.discriminatedUnion("code", [
     generic("invalid_request"),
+    generic("access_denied"),
+    generic("artifact_changed"),
     generic("unreadable_output"),
     generic("capability_unavailable"),
+    generic("unsupported_target"),
     generic("provider_unavailable"),
     generic("provider_timeout"),
+    generic("resource_constraint"),
     generic("cancelled"),
     z
         .object({

package/dist/contracts/evm/evmToolContracts.js

@@ -0,0 +1,20 @@
+import { inspectEvmInterfaceInputSchema, evmInterfaceSchema, } from "../../domain/evm/evmInterface.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemas.js";
+/** Target-free EVM capabilities are independent of archive/Apple artifact providers. */
+export const EVM_TOOL_CONTRACTS = [
+    {
+        name: "inspect_evm_interface",
+        ...toolContractMetadata("inspect_evm_interface"),
+        kind: "artifact-provider",
+        description: "Inspect an explicit local flat EVM bytecode carrier and infer dispatch selectors, argument strings and mutability without executing the target or accessing a chain/RPC endpoint. Choose raw or hex encoding explicitly. Returns original carrier and decoded-byte SHA-256, full bytecode and interface candidates inline as inferred Evidence; bytecode kind, hardfork, deployed authenticity and discovery completeness remain unknown. Initial real-verified Linux x64 profile uses unchanged bundled EVMole 0.9.3/WASM in a bounded owned worker; EOF-style EF00 containers are unsupported. No signature lookup, wallet action or transaction broadcast.",
+        inputSchema: inspectEvmInterfaceInputSchema,
+        outputSchema: evidenceResultOf(evmInterfaceSchema),
+        examples: [
+            {
+                title: "Inspect a local runtime bytecode hex carrier",
+                input: { path: "/artifacts/runtime.hex", encoding: "hex" },
+            },
+        ],
+    },
+];

package/dist/contracts/hopperMemoryContracts.js

@@ -1,8 +1,5 @@
 import { z } from "zod";
-const document = z.string().optional().describe("The document name");
-const address = z
-    .string()
-    .describe("A provider-normalized address; default memory uses 0x-prefixed hexadecimal");
+import { address, document } from "./toolContractHelpers.js";
 /** Hopper memory and file-mapping contracts. */
 export const HOPPER_MEMORY_TOOL_DEFINITIONS = [
     {
@@ -16,7 +13,7 @@ export const HOPPER_MEMORY_TOOL_DEFINITIONS = [
     },
     {
         name: "address_to_file_offset",
-        description: "Map one provider-normalized virtual address to its original nonnegative file offset. Unmapped addresses fail explicitly, and providers without an authoritative mapping API return typed capability unavailability.",
+        description: "Map one provider-normalized virtual address to its original nonnegative file offset. Hopper verifies the original bytes against the selected executable digest and translates FAT image-relative offsets using the loaded header. Results preserve the provider coordinate, image base, and source path. Unmapped addresses fail explicitly; changed or unavailable sources return typed errors retaining native mapping facts as partial evidence.",
         inputSchema: z.object({ address, document }),
     },
 ];

package/dist/contracts/investigationExamples.js

@@ -1,9 +1,9 @@
 import { compareFunctions } from "../domain/functionComparison.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-import { compareProcessCaptures, parseProcessCapture, } from "../domain/processCapture.js";
+import { compareProcessCaptures, parseProcessCapture, } from "../domain/process/processCapture.js";
 import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js";
-import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
+import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./process/processCaptureExample.js";
 const comparison = compareFunctions(FUNCTION_COMPARISON_EXAMPLE.left, FUNCTION_COMPARISON_EXAMPLE.right);
 export const FUNCTION_COMPARISON_EVIDENCE = createEvidence(undefined, {
     id: "rea-function-comparison",

package/dist/contracts/javascript/electronToolContracts.js

@@ -85,7 +85,7 @@ export const ELECTRON_TOOL_CONTRACTS = [
     {
         name: "capture_electron_scenario",
         ...toolContractMetadata("capture_electron_scenario"),
-        description: "Use this for a provider-owned Electron run when passive CDP or Inspector observation cannot exercise application behavior. REA owns startup and teardown, accepts caller-defined click/wait actions plus window-targeted renderer reload/crash and synthetic open-url/second-instance delivery, and returns correlated window/WebContents/process/preload/session/navigation/shell/IPC evidence without retaining payload values. Results identify observed and unavailable event families, coverage status, action targets, and truncation. External shell, navigation, permission, download, popup, updater, and OS-integration effects are blocked and recorded. Use passive Electron tools for observation-only work.",
+        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),

package/dist/contracts/managed/managedToolContracts.js

@@ -2,13 +2,15 @@ import { z } from "zod";
 import { managedOutputSchemas } from "../toolOutputSchemas.js";
 import { toolContractMetadata } from "../toolEffects.js";
 import { requireOutputSchema } from "../toolOutputSchemaPrimitives.js";
+import { isAbsoluteLocalPath, localPathStringSchema, } from "../../domain/localPath.js";
 /** Exact caller boundary for execution-free PE/CLI triage and identity. */
-const managedTargetInputSchema = z.object({
-    path: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("Explicit managed PE/CLI path; omit to reuse the previously selected managed target"),
+const managedTargetInputSchema = z.strictObject({
+    path: localPathStringSchema
+        .refine(isAbsoluteLocalPath, {
+        message: "path must be an absolute local filesystem path (for example /tmp/Example.dll or C:\\Example.dll)",
+    })
+        .describe("Explicit absolute managed PE/CLI path; omit to reuse the previously selected managed target")
+        .optional(),
 });
 export const managedArtifactInputSchema = managedTargetInputSchema;
 /** Exact caller boundary for execution-free metadata/signature/IL inspection. */

package/dist/contracts/native/binaryDiagnosticsToolContracts.js

@@ -0,0 +1,42 @@
+import { inspectRecordedCrashInputSchema, recordedCrashSchema, } from "../../domain/native/recordedCrash.js";
+import { inspectBinaryLayoutInputSchema, binaryLayoutSchema, } from "../../domain/native/binaryLayout.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemas.js";
+/** Offline binary diagnostics are independent of macOS process/UI providers. */
+export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [
+    {
+        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),
+        examples: [
+            {
+                title: "Inspect ELF linked and file layout",
+                input: { path: "/artifacts/application.elf" },
+            },
+        ],
+    },
+    {
+        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.",
+        inputSchema: inspectRecordedCrashInputSchema,
+        outputSchema: evidenceResultOf(recordedCrashSchema),
+        examples: [
+            {
+                title: "Inspect recorded registers and signal evidence",
+                input: { path: "/artifacts/crash.core" },
+            },
+            {
+                title: "Add core-only debugger mapping candidates",
+                input: {
+                    path: "/artifacts/crash.core",
+                    include_debugger_context: true,
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/native/nativeToolContracts.js

@@ -1,7 +1,9 @@
 import { z } from "zod";
+import { nativeCallObservationInputSchema } from "../../domain/native/nativeCallObservation.js";
 import { nativeUiObservationInputSchema, nativeUiScenarioInputSchema, } from "../../domain/native/nativeUiObservation.js";
 import { nativeOutputSchemas } from "../toolOutputSchemas.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
+import { localPathStringSchema } from "../../domain/localPath.js";
 import { toolContractMetadata } from "../toolEffects.js";
 import { requireOutputSchema } from "../toolOutputSchemaPrimitives.js";
 const examples = {
@@ -16,15 +18,29 @@ const examples = {
         steps: [{ kind: "wait", milliseconds: 100 }],
     },
     demangle_swift: { symbols: ["$s4Test3fooyyF"] },
+    observe_native_calls: {
+        breakpoints: [
+            {
+                kind: "objc-method",
+                class_name: "NSURLSession",
+                selector: "dataTaskWithRequest:completionHandler:",
+            },
+            { kind: "function", name: "open", module: "libsystem_kernel.dylib" },
+        ],
+        arguments: ["--help"],
+        duration_ms: 5000,
+        backtrace_frames: 4,
+    },
 };
 const native = (name, description, inputSchema) => {
     const outputSchema = requireOutputSchema(nativeOutputSchemas, name);
+    const strictInputSchema = inputSchema.strict();
     return {
         name,
         ...toolContractMetadata(name),
         description,
         kind: "native-provider",
-        inputSchema,
+        inputSchema: strictInputSchema,
         outputSchema,
         examples: [
             {
@@ -41,16 +57,18 @@ export const swiftSymbolsSchema = z
     .array(z
     .string()
     .min(1)
-    .regex(/^[^\n]*$/u, "Each Swift symbol must be one line."))
+    .regex(/^[^\n]*$/u, "Each Swift symbol must be one line.")
+    .regex(/^[^\0]*$/u, "Swift symbols cannot contain NUL."))
     .min(1);
 /** 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_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: z.string().min(1).optional(),
+        path: localPathStringSchema.optional(),
     })),
     native("list_architectures", "List thin or universal Mach-O slices with offsets, sizes, alignment, explicit coverage, and native-tool provenance.", z.object({})),
     native("demangle_swift", "Demangle an ordered list of single-line Swift symbols without requiring Hopper. Each input returns demangled, unchanged, or invalid status.", z.object({

package/dist/contracts/officialToolContracts.js

@@ -8,15 +8,18 @@ import { nativeInstructionInputSchema } from "../domain/native/nativeInstruction
 import { functionInstructionInputSchema } from "./functionInstructionContract.js";
 import { HOPPER_MEMORY_TOOL_DEFINITIONS } from "./hopperMemoryContracts.js";
 import { analysisSearchInput } from "./analysisSearchContract.js";
-const official = (name, description, inputSchema) => ({
-    name,
-    ...toolContractMetadata(name),
-    description,
-    kind: "official-proxy",
-    inputSchema,
-    outputSchema: requireOutputSchema(officialOutputSchemas, name),
-    examples: examplesFor(name, inputSchema),
-});
+const official = (name, description, inputSchema) => {
+    const strictInputSchema = inputSchema.strict();
+    return {
+        name,
+        ...toolContractMetadata(name),
+        description,
+        kind: "official-proxy",
+        inputSchema: strictInputSchema,
+        outputSchema: requireOutputSchema(officialOutputSchemas, name),
+        examples: examplesFor(name, strictInputSchema),
+    };
+};
 /** Bridge operations exposed without additional application composition. */
 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),
@@ -29,38 +32,37 @@ export const OFFICIAL_TOOL_CONTRACTS = [
     official("current_address", "Return Hopper's current cursor address for the selected document. Use only for interactive navigation state; prefer explicit addresses in reproducible investigations.", z.object({ document })),
     official("current_procedure", "Return the analyzed procedure containing Hopper's current cursor. This uses GUI cursor state and is not a procedure-name lookup.", z.object({ document })),
     official("current_document", "Return the document currently selected by REA's Hopper bridge.", z.object({})),
-    official("goto_address", "Move Hopper's GUI cursor to a hexadecimal address and return the resolved address. This changes navigation state but not analysis data; use explicit-address tools for headless workflows.", z.object({ address, document })),
+    official("goto_address", "Move Hopper's GUI cursor to a mapped address and return the observed cursor address. Interior coordinates snap to the containing analyzed object's start. Unmapped destinations fail without moving the cursor. This changes navigation state but not analysis data; use explicit-address tools for headless workflows.", z.object({ address, document })),
     official("inline_comment", "Read the inline instruction comment at an address, defaulting to the current cursor. Returns null when absent; use set_inline_comment to write one.", z.object({ document, address: optionalAddress })),
-    official("list_bookmarks", "List every bookmark in the selected Hopper document as address and name pairs. Use bookmarks as analyst-authored navigation aids; this does not discover code references.", z.object({ document })),
+    official("list_bookmarks", "List every bookmark in the selected Hopper document as address and name pairs; unnamed bookmarks retain a null name. Use bookmarks as analyst-authored navigation aids; this does not discover code references.", z.object({ document })),
     official("list_documents", "List provider program or document identities. Hopper may expose several documents; a Ghidra headless session contains exactly its one imported Program.", z.object({})),
     official("list_names", "List every analyzed memory and external symbol as address/value pairs. Provider metadata distinguishes Ghidra primary, dynamic, external, type, and source facts when available.", z.object({ document, address: optionalAddress })),
     official("list_procedures", "List every analyzed procedure as address/value pairs after provider analysis. Ghidra metadata distinguishes thunks and external functions; use returned addresses in later function operations.", z.object({ document })),
     official("list_segments", "List segments or memory blocks using exclusive end addresses. Ghidra reports block permissions, address space, image base, initialization, and overlay facts; Hopper marks unavailable permissions explicitly.", z.object({ document })),
-    official("list_strings", "List every provider-defined string, or filter to one address, as address/value pairs. Ghidra also reports encoding, terminator status, and byte length.", z.object({ document, address: optionalAddress })),
+    official("list_strings", "List every provider-defined string object, or filter to one address, as address/value pairs with encoding, terminator status, and byte length when available. Hopper reads complete typed objects and retains its original display text as provider_value; long literals may span adjacent unterminated objects.", z.object({ document, address: optionalAddress })),
     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 instruction start before an explicit address or current cursor. This is a navigation primitive and may fail at document boundaries.", 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. Body byte count and enclosing span remain distinct; unavailable extent is explicit.", 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),
     ...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 observed reference kinds while providers without kind authority mark them unavailable.", z.object({
+    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("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.", z.object(analysisSearchInput)),
-    official("search_strings", "Search every analyzed string using literal matching by default or regex when requested. Results are deterministic and complete.", z.object(analysisSearchInput)),
-    official("set_address_name", "Assign an analyst name to one hexadecimal address and report Hopper's boolean result. This mutates analysis metadata.", z.object({ address, name: z.string(), document })),
-    official("set_addresses_names", "Assign analyst names to multiple addresses in one call and return per-address success booleans. 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 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. This mutates the Hopper document; use comments to record evidence IDs or reasoning.", z.object({ address, comment: z.string(), document })),
-    official("set_current_document", "Select an already-open Hopper document by exact document name. This changes subsequent default-document routing; list_documents can supply names when needed, while explicit document inputs keep calls reproducible.", z.object({ document: z.string() })),
-    official("set_inline_comment", "Write an inline instruction comment at a hexadecimal address and return whether readback matched. This mutates analysis metadata.", z.object({ address, comment: z.string(), document })),
-    official("unset_bookmark", "Remove the bookmark at a hexadecimal address and return whether it is absent. This mutates navigation metadata and does not alter binary bytes.", 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("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 })),
 ];

package/dist/contracts/process/processCaptureExample.js

@@ -0,0 +1,2 @@
+/** Minimal valid process capture retained as a public contract example. */
+export { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../domain/process/processCaptureExample.js";

package/dist/contracts/promptContracts.js

@@ -46,7 +46,7 @@ export const PROMPT_CONTRACTS = [
         arguments: {
             feature: required("Feature, behavior, string, or symbol to investigate"),
             target_path: optional("Absolute target path; omit when the intended target is already open"),
-            document: optional("Open Hopper document to inspect", "document"),
+            document: optional("Active target's provider document name", "document"),
             procedure: optional("Known procedure name or address to prioritize", "procedure"),
             provider_id: optional("Configured provider identity to prefer when its capability is available", "provider"),
         },
@@ -56,8 +56,8 @@ export const PROMPT_CONTRACTS = [
                 instruction: "For a JavaScript/Electron application directory, call analyze_javascript_application with input_path=target_path directly; no open_binary call is needed. For a file or macOS app bundle, open target_path only when the required target is not active.",
             },
             {
-                tools: ["list_documents", "set_current_document"],
-                instruction: "Select a document only when needed for the requested analysis.",
+                tools: ["current_document"],
+                instruction: "Analysis stays bound to the active target's provider document. Use open_binary to switch targets; document names never select another artifact.",
             },
             {
                 tools: ["search_strings", "search_procedures", "procedure_address"],