rea-agents 6.3.0 → 6.5.0

package/dist/contracts/cutterToolContracts.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "./toolEffects.js";
+/** List live Cutter plugin bridge sessions. */
+export const cutterListInputSchema = z.strictObject({});
+/** Execute a command in a selected live Cutter instance and observed document generation. */
+export const cutterCommandInputSchema = z.strictObject({
+    session_id: z.string().uuid(),
+    expected_generation: z.number().int().nonnegative(),
+    command: z
+        .string()
+        .min(1)
+        .refine((value) => !/[\r\n]/u.test(value), "A single Rizin command line is required"),
+    json: z.boolean().default(false),
+});
+export const cutterSessionSchema = z.strictObject({
+    session_id: z.string().uuid(),
+    pid: z.number().int().positive(),
+    document_generation: z.number().int().nonnegative(),
+    current_file: z.string().nullable(),
+    cutter_version: z.string().nullable(),
+    identity_status: z.literal("partial"),
+});
+export const cutterCommandResultSchema = z.strictObject({
+    command: z.string(),
+    output: jsonValueSchema.nullable(),
+    execution_state: z.enum(["not_started", "complete", "failed", "unknown"]),
+    error: z.string().nullable(),
+    message: z.string().nullable(),
+    output_truncated: z.boolean(),
+    cutter_version: z.string().nullable(),
+    current_file: z.string().nullable(),
+    document_generation: z.number().int().nonnegative(),
+    identity_status: z.literal("partial"),
+});
+export const cutterDiscoverySchema = z.strictObject({
+    sessions: z.array(cutterSessionSchema),
+    bridge_directory: z.string(),
+    discovery_status: z.enum([
+        "sessions_found",
+        "no_live_bridge_found",
+        "bridge_directory_unavailable",
+        "bridge_directory_insecure",
+        "bridge_directory_capacity_exceeded",
+    ]),
+    bridge_directory_security: z.enum([
+        "private_verified",
+        "not_private",
+        "unverified_platform_acl",
+        "not_checked",
+    ]),
+});
+/** Live Cutter discovery and arbitrary Rizin command contracts. */
+export const CUTTER_TOOL_CONTRACTS = [
+    {
+        name: "list_cutter_sessions",
+        ...toolContractMetadata("list_cutter_sessions"),
+        kind: "native-provider",
+        description: "List live REA bridge sessions hosted by upstream Cutter instances, including observed document identity and bridge-directory security status. Discovery admits at most 256 descriptor candidates (16 MiB at the descriptor byte limit), reads and probes at most eight concurrently, and reports bridge_directory_capacity_exceeded rather than claiming no sessions when that budget is exceeded.",
+        inputSchema: cutterListInputSchema,
+        outputSchema: cutterDiscoverySchema,
+        examples: [{ title: "List open Cutter instances", input: {} }],
+    },
+    {
+        name: "cutter_command",
+        ...toolContractMetadata("cutter_command"),
+        kind: "native-provider",
+        description: "Run one arbitrary Rizin command in a selected live Cutter session. Commands may edit and persist analysis state or execute plugin-provided effects; completion uncertainty is returned as Evidence and must not be retried automatically. 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: cutterCommandInputSchema,
+        outputSchema: evidenceResultOf(cutterCommandResultSchema),
+        examples: [
+            {
+                title: "Inspect active binary metadata",
+                input: {
+                    session_id: "00000000-0000-4000-8000-000000000001",
+                    expected_generation: 0,
+                    command: "ij",
+                    json: true,
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/enhancedToolContracts.js

@@ -23,10 +23,10 @@ export const ENHANCED_TOOL_CONTRACTS = [
     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 Swift procedure names using their manglings or same-address Swift symbol aliases. Decodes legacy and literal modern nominal contexts into classes, structs, enums, protocols, and extensions. Preserves provider names and supporting mangled_names; unresolved categories appear in other and in unclassified, which remains inline even under category filters. Returns deduplicated procedure-name counts, not unique source types, plus identification limitations. Optionally select one category and/or apply a case-sensitive literal filter to provider names or supporting manglings; for example, use {category: "structs", pattern: "Pair"}.', 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),
+    enhanced("binary_overview", "Return the bound document and exhaustive procedure/string counts, plus every segment and segment_count when the provider supports segment enumeration. If segment fields are omitted, segment coverage is unavailable rather than empty. When every observed segment agrees on an analysis image base, return it as image_base so callers can relate provider addresses to their loader coordinates. 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 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_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. A requested goal is unknown when unresolved expansions prevent proving it absent; 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/evm/evmToolContracts.js

@@ -1,20 +1,35 @@
 import { inspectEvmInterfaceInputSchema, evmInterfaceSchema, } from "../../domain/evm/evmInterface.js";
 import { toolContractMetadata } from "../toolEffects.js";
-import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { analysisDetailSchema, analysisDetailOutputSchemaOf, } from "../analysisDetail.js";
+import { evmInterfaceSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
+/** Delivery selection leaves the existing provider input and original Evidence unchanged. */
+const evmInterfaceInspectionInputSchema = inspectEvmInterfaceInputSchema.extend({
+    detail: analysisDetailSchema.unwrap().optional(),
+});
 /** 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" },
+export const INSPECT_EVM_INTERFACE_CONTRACT = {
+    name: "inspect_evm_interface",
+    ...toolContractMetadata("inspect_evm_interface"),
+    kind: "artifact-provider",
+    description: 'Inspect explicit local flat EVM bytecode without target execution or chain/RPC access. Select raw or hex encoding explicitly. Omitted or complete detail returns original carrier and decoded identities, full bytecode and all inferred interface candidates inline. For all inferred selectors/offsets/arguments/mutability and identities without bytecode hex or duplicated stdout, select detail: "summary" on this first call: it retains unchanged complete Evidence and returns a distinct linked inspect_analysis_view summary. Read original function rows or bytecode_hex/stdout/stderr text pages using view kind evm and normalized_result.parent_evidence_id; original complete Evidence remains accessible. Bytecode kind, hardfork, deployed authenticity and discovery completeness stay unknown; summary coverage covers only producer-returned candidates. Unchanged bundled EVMole 0.9.3/WASM in an owned bounded worker is initially real-verified on Linux x64; EOF-style EF00 containers are unsupported. No signature lookup, wallet action or transaction broadcast.',
+    inputSchema: evmInterfaceInspectionInputSchema,
+    outputSchema: analysisDetailOutputSchemaOf(evmInterfaceSchema, evmInterfaceSummaryViewResultSchema),
+    examples: [
+        {
+            title: "Inspect a local runtime bytecode hex carrier",
+            input: { path: "/artifacts/runtime.hex", encoding: "hex" },
+        },
+        {
+            title: "Read every inferred interface candidate without bytecode text",
+            input: {
+                path: "/artifacts/runtime.hex",
+                encoding: "hex",
+                detail: "summary",
             },
-        ],
-    },
+        },
+    ],
+};
+/** Preserve the default catalog's exact operation and ordering. */
+export const EVM_TOOL_CONTRACTS = [
+    INSPECT_EVM_INTERFACE_CONTRACT,
 ];

package/dist/contracts/firmware/firmwareToolContracts.js

@@ -21,7 +21,7 @@ export const FIRMWARE_TOOL_CONTRACTS = [
         name: "extract_firmware",
         ...toolContractMetadata("extract_firmware"),
         kind: "firmware-provider",
-        description: "Extract caller-selected firmware bytes with Unblob 26.6.x (verified with 26.6.4) into an absent output directory. Returns verified child paths/digests, task derivations, unknown chunks and extraction diagnostics inline. Preserves the default sandbox; publishes regular files only. Linux, caller-supplied tool, format-specific extractors and util-linux prlimit required. No mounts or extracted-code execution. Select a returned native file with open_binary for Ghidra analysis; decompressed offsets are not original-file addresses.",
+        description: "Extract caller-selected firmware bytes with Unblob 26.6.x (verified with 26.6.4) into an absent output directory. Returns verified child paths/digests, task derivations, unknown chunks, extraction diagnostics and explicit extraction_gaps rows naming unextracted regions, missing extractor dependencies and a continuation_id referencing shared extraction_continuations recovery instructions. Preserves the default sandbox; publishes regular files only. Linux, caller-supplied tool, format-specific extractors and util-linux prlimit required. No mounts or extracted-code execution. Select a returned native file with open_binary for Ghidra analysis; decompressed offsets are not original-file addresses.",
         inputSchema: firmwareInputSchemas.extract_firmware,
         outputSchema: evidenceResultOf(firmwareResultSchemas.extract_firmware),
         examples: [

package/dist/contracts/flutter/flutterToolContracts.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { flutterInputSchemas, dartAotInspectionInputSchema, flutterResultSchemas, } from "../../domain/flutter/flutterBuildAnalysis.js";
+import { dartAotSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+/** Flutter build identification by pure APK parsing. */
+export const FLUTTER_TOOL_CONTRACTS = [
+    {
+        name: "identify_flutter_build",
+        ...toolContractMetadata("identify_flutter_build"),
+        description: "Identify a Flutter app's build facts by pure parsing: the Dart VM snapshot hash from every lib/<abi>/libapp.so AOT section (vm and isolate, cross-checked), per-ABI library digests, the engine library's GNU build-id, and any labeled Dart version or toolchain strings libflutter.so carries. The snapshot hash is the artifact that maps to a Dart SDK release through an external dataset; REA performs no lookup. No engine, no execution, no external tools.",
+        kind: "flutter-provider",
+        inputSchema: flutterInputSchemas.identify_flutter_build,
+        outputSchema: evidenceResultOf(flutterResultSchemas.identify_flutter_build),
+        examples: [
+            {
+                title: "Identify a Flutter build",
+                input: { path: "/targets/Example.apk" },
+            },
+        ],
+    },
+    {
+        name: "inspect_dart_aot",
+        ...toolContractMetadata("inspect_dart_aot"),
+        description: "Inspect one ABI's Dart AOT snapshot inside an APK: the four snapshot symbols located through the ELF dynamic symbol table with their offsets, sizes, and section headers (magic, kind, length), the snapshot hash, and a bounded string-pool projection from the isolate data section (package: source URIs, dart: SDK URIs, identifier-like tokens) exposing the app's dependency structure. String-pool entries are byte-pattern observations, not deserialized cluster semantics; typed class and function recovery needs an SDK-specific parser. Omitted or complete detail returns the full observation. Select detail: \"summary\" for target/ABI/library identity, all snapshot headers, coverage and original lower-bound counts without string lists. The complete source stays retained; read returned strings via inspect_analysis_view with parent_evidence_id and kind dart-aot, collection package_uris/dart_uris/class_like_tokens, offset and limit. Exhausting pages does not imply complete pool coverage. No engine, no execution.",
+        kind: "flutter-provider",
+        inputSchema: dartAotInspectionInputSchema,
+        outputSchema: evidenceResultOf(z.union([
+            flutterResultSchemas.inspect_dart_aot,
+            dartAotSummaryViewResultSchema,
+        ])),
+        examples: [
+            {
+                title: "Inspect the preferred ABI's AOT snapshot",
+                input: { path: "/targets/Example.apk" },
+            },
+            {
+                title: "Inspect one ABI explicitly",
+                input: { path: "/targets/Example.apk", abi: "arm64-v8a" },
+            },
+            {
+                title: "Inspect snapshot identity with retained string lists",
+                input: { path: "/targets/Example.apk", detail: "summary" },
+            },
+        ],
+    },
+];

package/dist/contracts/fridaRemoteAddress.js

@@ -0,0 +1,23 @@
+/** Accept a Frida host address, optionally with a TCP port, without URL credentials or paths. */
+export const isValidFridaRemoteAddress = (address) => {
+    if (address.length === 0 || address.length > 2048)
+        return false;
+    if (/[?@#\s\u0000-\u001f\u007f/]/u.test(address))
+        return false;
+    if (address.endsWith(":"))
+        return false;
+    try {
+        const parsed = new URL(`tcp://${address}`);
+        const port = parsed.port === "" ? undefined : Number(parsed.port);
+        return (parsed.hostname.length > 0 &&
+            (port === undefined || (port > 0 && port <= 65_535)) &&
+            parsed.username.length === 0 &&
+            parsed.password.length === 0 &&
+            (parsed.pathname === "" || parsed.pathname === "/") &&
+            parsed.search.length === 0 &&
+            parsed.hash.length === 0);
+    }
+    catch {
+        return false;
+    }
+};

package/dist/contracts/fridaToolContracts.js

@@ -0,0 +1,273 @@
+import { z } from "zod";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { isValidFridaRemoteAddress } from "./fridaRemoteAddress.js";
+export const FRIDA_KEEPALIVE_INTERVAL_DESCRIPTION = "Remote keepalive interval in seconds";
+const remoteConnection = z.strictObject({
+    address: z.string().min(1).max(2048).refine(isValidFridaRemoteAddress, {
+        message: "Expected a Frida host address, optionally followed by a port",
+    }),
+    token: z.string().min(1).optional(),
+    certificate: z.string().min(1).optional(),
+    origin: z.string().min(1).optional(),
+    keepalive_interval: z
+        .number()
+        .int()
+        .positive()
+        .describe(FRIDA_KEEPALIVE_INTERVAL_DESCRIPTION)
+        .optional(),
+});
+const deviceSelector = z.strictObject({
+    device_id: z.string().min(1).optional(),
+    remote: remoteConnection.optional(),
+});
+const exclusiveDeviceSelector = (schema) => schema.refine((value) => !(typeof value === "object" &&
+    value !== null &&
+    "device_id" in value &&
+    "remote" in value &&
+    value.device_id !== undefined &&
+    value.remote !== undefined), "Choose either device_id or remote, not both");
+const sessionId = z.string().uuid();
+const sessionOutput = z.strictObject({
+    session_id: sessionId,
+    device_id: z.string(),
+    target: z.string(),
+    pid: z.number().int().nonnegative(),
+    mode: z.enum(["attach", "spawn"]),
+    state: z.enum(["paused", "running", "detached"]),
+});
+const scriptOutput = z.strictObject({
+    script_id: z.string().uuid(),
+    source_kind: z.enum(["inline", "file"]),
+    source_path: z.string().nullable(),
+    source_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    messages: z.array(z.unknown()),
+    messages_truncated: z.boolean(),
+});
+/** Caller-facing Frida device, process, and instrumentation-session contracts. */
+export const FRIDA_TOOL_CONTRACTS = [
+    {
+        name: "list_frida_devices",
+        ...toolContractMetadata("list_frida_devices"),
+        kind: "native-provider",
+        description: "List Frida devices currently available to this host, optionally connecting to the caller-selected remote Frida endpoint. Remote authentication options are used for this call only and are never returned or recorded.",
+        inputSchema: z.strictObject({ remote: remoteConnection.optional() }),
+        outputSchema: z.strictObject({
+            devices: z.array(z.strictObject({
+                device_id: z.string(),
+                name: z.string(),
+                type: z.string(),
+            })),
+            cleanup_error: z.string().nullable(),
+        }),
+        examples: [{ title: "List Frida devices", input: {} }],
+    },
+    {
+        name: "list_frida_processes",
+        ...toolContractMetadata("list_frida_processes"),
+        kind: "native-provider",
+        description: "List processes observed on a selected Frida device or caller-supplied remote endpoint. A remote connection is closed after discovery; authentication values are never returned or recorded.",
+        inputSchema: exclusiveDeviceSelector(deviceSelector).refine((value) => value.device_id !== undefined || value.remote !== undefined, "Select a device_id or a remote endpoint"),
+        outputSchema: z.strictObject({
+            device_id: z.string(),
+            processes: z.array(z.strictObject({
+                pid: z.number().int().nonnegative(),
+                name: z.string(),
+                identifier: z.string().nullable(),
+            })),
+            cleanup_error: z.string().nullable(),
+        }),
+        examples: [
+            {
+                title: "List local Frida processes",
+                input: { device_id: "local" },
+            },
+        ],
+    },
+    {
+        name: "start_frida_session",
+        ...toolContractMetadata("start_frida_session"),
+        kind: "native-provider",
+        description: "Attach Frida to one selected process or spawn one selected target. Spawned targets remain paused until resume_frida_session, allowing scripts to load before execution. Closing a session detaches instrumentation; it does not kill the target.",
+        inputSchema: z
+            .strictObject({
+            mode: z.enum(["attach", "spawn"]),
+            ...deviceSelector.shape,
+            pid: z.number().int().positive().optional(),
+            program: z.string().min(1).optional(),
+            argv: z.array(z.string()).optional(),
+        })
+            .refine((value) => ((value.mode === "attach" &&
+            value.pid !== undefined &&
+            value.program === undefined &&
+            value.argv === undefined) ||
+            (value.mode === "spawn" &&
+                value.program !== undefined &&
+                value.pid === undefined)) &&
+            !(value.device_id !== undefined && value.remote !== undefined), "Select one device; attach requires pid; spawn requires program and rejects pid"),
+        outputSchema: sessionOutput,
+        examples: [
+            {
+                title: "Attach to a process",
+                input: { mode: "attach", device_id: "local", pid: 1234 },
+            },
+        ],
+    },
+    {
+        name: "load_frida_script",
+        ...toolContractMetadata("load_frida_script"),
+        kind: "native-provider",
+        description: "Load caller-supplied JavaScript into a Frida session. Scripts can read or change target memory and behavior and can access the target process's capabilities. Messages and script errors are returned inline as Evidence; source content is not persisted.",
+        inputSchema: z
+            .strictObject({
+            session_id: sessionId,
+            source_kind: z.enum(["inline", "file"]),
+            source: z.string().optional(),
+            path: z.string().min(1).optional(),
+        })
+            .refine((value) => (value.source_kind === "inline" &&
+            value.source !== undefined &&
+            value.path === undefined) ||
+            (value.source_kind === "file" &&
+                value.path !== undefined &&
+                value.source === undefined), "Inline source requires source; file source requires path"),
+        outputSchema: evidenceResultOf(scriptOutput),
+        examples: [
+            {
+                title: "Load an inline Frida script",
+                input: {
+                    session_id: "00000000-0000-4000-8000-000000000001",
+                    source_kind: "inline",
+                    source: "send(Process.id);",
+                },
+            },
+        ],
+    },
+    {
+        name: "resume_frida_session",
+        ...toolContractMetadata("resume_frida_session"),
+        kind: "native-provider",
+        description: "Resume the process created by a paused Frida spawn session. Attached processes are already running and cannot be resumed through this operation.",
+        inputSchema: z.strictObject({ session_id: sessionId }),
+        outputSchema: z.strictObject({ state: z.literal("running") }),
+        examples: [
+            {
+                title: "Resume an instrumented process",
+                input: { session_id: "00000000-0000-4000-8000-000000000001" },
+            },
+        ],
+    },
+    {
+        name: "unload_frida_script",
+        ...toolContractMetadata("unload_frida_script"),
+        kind: "native-provider",
+        description: "Unload one caller-selected Frida script from a live session. This removes that script's instrumentation from the target.",
+        inputSchema: z.strictObject({
+            session_id: sessionId,
+            script_id: z.string().uuid(),
+        }),
+        outputSchema: z.strictObject({ unloaded: z.literal(true) }),
+        examples: [
+            {
+                title: "Unload a script",
+                input: {
+                    session_id: "00000000-0000-4000-8000-000000000001",
+                    script_id: "00000000-0000-4000-8000-000000000002",
+                },
+            },
+        ],
+    },
+    {
+        name: "frida_session_status",
+        ...toolContractMetadata("frida_session_status"),
+        kind: "native-provider",
+        description: "Return observed Frida session state and queued script messages. Message history is bounded by the provider capture budget and reports truncation.",
+        inputSchema: z.strictObject({ session_id: sessionId }),
+        outputSchema: evidenceResultOf(z.strictObject({
+            session_id: sessionId,
+            device_id: z.string(),
+            state: z.enum(["paused", "running", "detached"]),
+            target: z.string(),
+            pid: z.number().int().nonnegative(),
+            mode: z.enum(["attach", "spawn"]),
+            scripts: z.array(z.strictObject({ script_id: z.string().uuid(), name: z.string() })),
+            messages: z.array(z.unknown()),
+            messages_truncated: z.boolean(),
+        })),
+        examples: [
+            {
+                title: "Check Frida session",
+                input: { session_id: "00000000-0000-4000-8000-000000000001" },
+            },
+        ],
+    },
+    {
+        name: "close_frida_session",
+        ...toolContractMetadata("close_frida_session"),
+        kind: "native-provider",
+        description: "Unload session scripts and detach REA's Frida session. If a spawned process is still paused, resume it before detaching so it is not left suspended. REA never kills the target; its final state is reported as unknown.",
+        inputSchema: z.strictObject({ session_id: sessionId }),
+        outputSchema: z.strictObject({ target_state: z.literal("unknown") }),
+        examples: [
+            {
+                title: "Close Frida session",
+                input: { session_id: "00000000-0000-4000-8000-000000000001" },
+            },
+        ],
+    },
+    {
+        name: "instrument_with_frida",
+        ...toolContractMetadata("instrument_with_frida"),
+        kind: "native-provider",
+        description: "Run one caller-authored Frida script against an explicitly selected process and detach when the observation window ends. The CLI and MCP share this ephemeral workflow; use MCP session operations for persistent sessions. Remote authentication is used only for this call and excluded from Evidence.",
+        inputSchema: z
+            .strictObject({
+            mode: z.enum(["attach", "spawn"]),
+            ...deviceSelector.shape,
+            pid: z.number().int().positive().optional(),
+            program: z.string().min(1).optional(),
+            argv: z.array(z.string()).optional(),
+            source_kind: z.enum(["inline", "file"]),
+            source: z.string().optional(),
+            path: z.string().min(1).optional(),
+            duration_ms: z.number().int().min(0).max(60_000).default(1_000),
+        })
+            .refine((value) => !(value.device_id !== undefined && value.remote !== undefined) &&
+            ((value.mode === "attach" &&
+                value.pid !== undefined &&
+                value.program === undefined &&
+                value.argv === undefined) ||
+                (value.mode === "spawn" &&
+                    value.program !== undefined &&
+                    value.pid === undefined)) &&
+            ((value.source_kind === "inline" &&
+                value.source !== undefined &&
+                value.path === undefined) ||
+                (value.source_kind === "file" &&
+                    value.path !== undefined &&
+                    value.source === undefined)), "Select one device and provide fields matching the mode and source_kind"),
+        outputSchema: evidenceResultOf(z.strictObject({
+            ...sessionOutput.shape,
+            scripts: z.array(z.strictObject({ script_id: sessionId, name: z.string() })),
+            messages: z.array(z.unknown()),
+            messages_truncated: z.boolean(),
+            source_kind: z.enum(["inline", "file"]),
+            source_path: z.string().nullable(),
+            source_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+            cleanup_error: z.string().nullable(),
+        })),
+        examples: [
+            {
+                title: "Instrument a selected process briefly",
+                input: {
+                    mode: "attach",
+                    device_id: "local",
+                    pid: 1234,
+                    source_kind: "inline",
+                    source: "send(Process.id);",
+                    duration_ms: 1_000,
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/functionComparisonExample.js

@@ -14,7 +14,7 @@ const dossier = (text) => jsonValueSchema.parse({
         locals: [],
     },
     pseudocode: text,
-    assembly: [],
+    assembly: ["ret"],
     comments: [],
     callers: [],
     callees: [],
@@ -25,6 +25,16 @@ const dossier = (text) => jsonValueSchema.parse({
     basic_blocks: [{ start: "0x1000", end: "0x1001", successors: [] }],
     native_api: null,
     native_value_flow: null,
+    facet_availability: {
+        pseudocode: { available: true },
+        assembly: { available: true },
+        comments: { available: true },
+        callers: { available: true },
+        callees: { available: true },
+        references: { available: true },
+        strings_names: { available: true },
+        cfg: { available: true },
+    },
     limitations: ["The fixture omits native API and value-flow observations."],
 });
 const observe = (digit, text) => createEvidence({
@@ -43,6 +53,7 @@ const observe = (digit, text) => createEvidence({
     result: dossier(text),
     confidence: "derived",
     authority: "shipped-artifact",
+    relationshipCoverage: { status: "complete" },
 });
 /** Canonical explicit function pair used in public contract examples. */
 export const FUNCTION_COMPARISON_EXAMPLE = {

package/dist/contracts/functionWorkflowToolContracts.js

@@ -24,6 +24,6 @@ const functionWorkflow = (name, description) => {
 };
 /** Function dossier and native API reconstruction workflow contracts. */
 export const FUNCTION_WORKFLOW_TOOL_CONTRACTS = [
-    functionWorkflow("analyze_function", "Build a dossier for one native function identified by symbol or provider-returned address. Returns identity with complete inclusive body ranges or explicit unknown, provider-specific pseudocode and assembly, comments, calls, references, referenced strings/names, local CFG blocks, and available native API boundary observations."),
+    functionWorkflow("analyze_function", "Build a dossier for one native function identified by symbol or provider-returned address. Returns identity with complete inclusive analyzed body ranges or explicit unknown, provider-specific pseudocode and assembly, comments, calls, references, referenced strings/names, local CFG blocks, and available native API boundary observations. Ghidra terminal-call assumptions that may cut the analyzed body are reported in limitations with available callee identities."),
     functionWorkflow("inspect_native_api", "Analyze a native API boundary in one function identified by symbol or provider-returned address. Returns confidence, evidence, jump-table dispatch/data/case mappings, separately evidenced default targets, unsupported branches, and residual unknowns. Null case values mean unresolved cases, never a known default."),
 ];