Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

feat(analysis): add bounded memory and call tracing

morluto8e7709d35ae0
diff --git a/bridge/hopper_bridge.py b/bridge/hopper_bridge.py
index 1a9d03c00..249d7ce1b 100644
--- a/bridge/hopper_bridge.py
+++ b/bridge/hopper_bridge.py
@@ -11,20 +11,86 @@ import os
import re
import sre_parse
import socket
+from typing import Any, Optional, Protocol, Sequence
MAX_LINE_BYTES = 10 * 1024 * 1024
+MAX_READ_BYTES = 4096
BAD_ADDRESSES = (-1, 0xFFFFFFFFFFFFFFFF, None)
_selected_document = None
_search_inventory_cache = {}
_pseudocode_cache = {}
+_hopper_api = None
MAX_SEARCH_PATTERN_LENGTH = 256
MAX_SEARCH_VALUE_LENGTH = 4096
+class HopperDocument(Protocol):
+ """Typed minimum used by the provider-neutral Hopper API facade."""
+
+ def getDocumentName(self) -> str: ...
+
+ def getExecutableFilePath(self) -> Optional[str]: ...
+
+ def getDatabaseFilePath(self) -> Optional[str]: ...
+
+ def backgroundProcessActive(self) -> bool: ...
+
+
+class HopperDocumentProvider(Protocol):
+ """Hopper's injected global document provider."""
+
+ @classmethod
+ def getAllDocuments(cls) -> Sequence[HopperDocument]: ...
+
+ @classmethod
+ def getCurrentDocument(cls) -> Optional[HopperDocument]: ...
+
+
+class HopperApiFacade:
+ """Small injected boundary around Hopper globals for standalone tests."""
+
+ def __init__(self, document_provider: HopperDocumentProvider):
+ self._document_provider = document_provider
+
+ def documents(self) -> Sequence[HopperDocument]:
+ return self._document_provider.getAllDocuments()
+
+ def current_document(self) -> Optional[HopperDocument]:
+ return self._document_provider.getCurrentDocument()
+
+ def require_analysis_complete(
+ self, document: HopperDocument, operation: str
+ ) -> None:
+ if document.backgroundProcessActive():
+ raise CapabilityUnavailableError(
+ "%s requires completed Hopper background analysis" % operation
+ )
+
+
+def _configure_hopper_api(document_provider):
+ """Inject Hopper's document provider or a standalone test facade."""
+ global _hopper_api
+ _hopper_api = HopperApiFacade(document_provider)
+
+
+def _api():
+ """Resolve Hopper globals lazily so importing this module needs no Hopper."""
+ global _hopper_api
+ if _hopper_api is not None:
+ return _hopper_api
+ document_provider = globals().get("Document")
+ if document_provider is None:
+ raise CapabilityUnavailableError(
+ "Hopper Document API is unavailable outside the Hopper runtime"
+ )
+ _hopper_api = HopperApiFacade(document_provider)
+ return _hopper_api
+
+
def _session_document():
"""Find only the document opened for this authenticated REA session."""
target = os.path.realpath(REA_TARGET_PATH)
- for document in Document.getAllDocuments():
+ for document in _api().documents():
paths = (document.getExecutableFilePath(), document.getDatabaseFilePath())
for path in paths:
if path and os.path.realpath(path) == target:
@@ -37,6 +103,31 @@ MAX_REGEX_CANDIDATE_LENGTH = 4096
MAX_REGEX_SEARCH_WORK_UNITS = 1000000
+class CapabilityUnavailableError(Exception):
+ """The active Hopper build lacks one admitted public API operation."""
+
+
+EXHAUSTIVE_ANALYSIS_METHODS = frozenset(
+ (
+ "analyze_function",
+ "list_names",
+ "list_procedures",
+ "list_strings",
+ "procedure_address",
+ "procedure_assembly",
+ "procedure_callees",
+ "procedure_callers",
+ "procedure_info",
+ "procedure_pseudo_code",
+ "procedure_references",
+ "read_function_instructions",
+ "resolve_containing_procedure",
+ "search_procedures",
+ "search_strings",
+ )
+)
+
+
def _hex(value):
return "0x%x" % value
@@ -55,7 +146,8 @@ def _json_safe(value):
def _document(name=None):
"""Resolve an explicit or session-selected document without changing Hopper UI."""
global _selected_document
- documents = Document.getAllDocuments()
+ api = _api()
+ documents = api.documents()
if name is not None:
for candidate in documents:
if candidate.getDocumentName() == name:
@@ -65,7 +157,7 @@ def _document(name=None):
for candidate in documents:
if candidate.getDocumentName() == _selected_document:
return candidate
- current = Document.getCurrentDocument()
+ current = api.current_document()
if current is None:
raise ValueError("No Hopper document is loaded")
return current
@@ -762,11 +854,54 @@ def _dispatch(method, params):
return _selected_document
document = _document(params.get("document"))
+ if method in EXHAUSTIVE_ANALYSIS_METHODS:
+ _api().require_analysis_complete(document, method)
if method == "analyze_function":
return _analyze_function(document, params)
if method == "read_function_instructions":
return _read_function_instructions(document, params)
+ if method == "read_bytes":
+ length = params.get("length", 256)
+ if isinstance(length, bool) or not isinstance(length, int):
+ raise ValueError("Byte-read length must be an integer")
+ if length < 1 or length > MAX_READ_BYTES:
+ raise ValueError("Byte-read length must be between 1 and 4096")
+ reader = getattr(document, "readBytes", None)
+ if not callable(reader):
+ raise CapabilityUnavailableError(
+ "Hopper's public Python API does not expose readBytes"
+ )
+ address = _address(document, params.get("address"))
+ value = reader(address, length)
+ if not isinstance(value, (bytes, bytearray)):
+ raise CapabilityUnavailableError(
+ "Hopper's public Python API returned an unsupported byte representation"
+ )
+ data = bytes(value)
+ return {
+ "address": _hex(address),
+ "requested_bytes": length,
+ "returned_bytes": len(data),
+ "bytes_hex": data.hex(),
+ "complete": len(data) == length,
+ }
+ if method == "address_to_file_offset":
+ mapper = getattr(document, "getFileOffsetFromAddress", None)
+ if not callable(mapper):
+ raise CapabilityUnavailableError(
+ "Hopper's public Python API does not expose getFileOffsetFromAddress"
+ )
+ address = _address(document, params.get("address"))
+ offset = mapper(address)
+ if (
+ isinstance(offset, bool)
+ or not isinstance(offset, int)
+ or offset in BAD_ADDRESSES
+ or offset < 0
+ ):
+ raise ValueError("Address has no authoritative file-offset mapping")
+ return {"address": _hex(address), "file_offset": offset}
if method == "resolve_containing_procedure":
address = _address(document, params.get("address"))
procedure, reason = _containing_procedure(document, address)
@@ -935,6 +1070,8 @@ def _serve_connection(connection):
def _diagnostic_type(error):
+ if isinstance(error, CapabilityUnavailableError):
+ return "capability_unavailable"
if isinstance(error, PermissionError):
return "authorization"
if isinstance(error, (ValueError, TypeError, KeyError)):
@@ -961,4 +1098,5 @@ def _run():
# Hopper's public objects are bound to its dedicated Python execution thread.
# Keep dispatch on that thread; moving calls to an arbitrary worker can deadlock.
-_run()
+if __name__ == "__main__":
+ _run()
diff --git a/scripts/verify-real-hopper.mjs b/scripts/verify-real-hopper.mjs
index 34de6507c..847ce498b 100644
--- a/scripts/verify-real-hopper.mjs
+++ b/scripts/verify-real-hopper.mjs
@@ -150,12 +150,53 @@ const verifyRelationships = async (client, options, procedure) => {
return related;
};
+const verifyByteAccess = async (client, options, firstAddress) => {
+ const byteRead = requireSuccessfulTool(
+ await client.callTool(
+ { name: "read_bytes", arguments: { address: firstAddress, length: 16 } },
+ options,
+ ),
+ "read_bytes",
+ );
+ if (
+ byteRead?.address !== firstAddress ||
+ byteRead.requested_bytes !== 16 ||
+ byteRead.returned_bytes !== 16 ||
+ byteRead.complete !== true ||
+ !/^[a-f0-9]{32}$/u.test(byteRead.bytes_hex)
+ ) {
+ throw new Error("read_bytes returned an invalid bounded byte window");
+ }
+ const mappedOffset = requireSuccessfulTool(
+ await client.callTool(
+ {
+ name: "address_to_file_offset",
+ arguments: { address: firstAddress },
+ },
+ options,
+ ),
+ "address_to_file_offset",
+ );
+ if (
+ mappedOffset?.address !== firstAddress ||
+ !Number.isSafeInteger(mappedOffset.file_offset) ||
+ mappedOffset.file_offset < 0
+ ) {
+ throw new Error("address_to_file_offset returned an invalid mapping");
+ }
+ return {
+ byteReadCount: byteRead.returned_bytes,
+ mappedFileOffset: mappedOffset.file_offset,
+ };
+};
+
const verifyCurrentTarget = async (client, options) => {
const procedures = requireSuccessfulTool(
await client.callTool({ name: "list_procedures", arguments: {} }, options),
"list_procedures",
);
const firstAddress = firstProcedureAddress(procedures);
+ const byteAccess = await verifyByteAccess(client, options, firstAddress);
const basics = await verifyHopperFunctionBasics(
client,
options,
@@ -217,6 +258,7 @@ const verifyCurrentTarget = async (client, options) => {
xrefCount: relationships.xrefs.length,
outgoingReferenceCount: basics.outgoingReferenceCount,
instructionWindowCount: basics.instructionWindowCount,
+ ...byteAccess,
};
};
diff --git a/src/application/CallPathTracing.ts b/src/application/CallPathTracing.ts
new file mode 100644
index 000000000..7840cece6
--- /dev/null
+++ b/src/application/CallPathTracing.ts
@@ -0,0 +1,244 @@
+import type { AnalysisOperation } from "./AnalysisProvider.js";
+import { projectAnalysisError, type AnalysisError } from "../domain/errors.js";
+import { parseRelatedAddresses } from "../domain/hopperValues.js";
+import type { JsonValue } from "../domain/jsonValue.js";
+import { ok, type Result } from "../domain/result.js";
+import type { EnhancedResult } from "./EnhancedToolTypes.js";
+
+type AnalysisCall = (
+ name: AnalysisOperation,
+ arguments_: Readonly<Record<string, JsonValue>>,
+ signal?: AbortSignal,
+) => Promise<Result<JsonValue, AnalysisError>>;
+
+export interface CallPathTraceInput {
+ readonly start: string;
+ readonly goal?: string | undefined;
+ readonly direction: "forward" | "backward";
+ readonly max_depth: number;
+ readonly max_nodes: number;
+ readonly max_operations: number;
+}
+
+interface TraceState {
+ readonly visited: Map<
+ string,
+ { readonly depth: number; readonly path: string[] }
+ >;
+ readonly queue: string[];
+ readonly edges: Map<
+ string,
+ {
+ readonly source_address: string;
+ readonly target_address: string;
+ readonly discovery_depth: number;
+ }
+ >;
+ readonly failures: Array<{
+ readonly address: string;
+ readonly error: ReturnType<typeof projectAnalysisError>;
+ }>;
+ readonly frontier: Set<string>;
+ readonly residual: Set<string>;
+ operations: number;
+ queueIndex: number;
+ traversalPath: string[];
+}
+
+interface AddressExpansion {
+ readonly input: CallPathTraceInput;
+ readonly state: TraceState;
+ readonly address: string;
+ readonly current: { readonly depth: number; readonly path: string[] };
+ readonly signal?: AbortSignal;
+}
+
+interface DiscoveredEdge {
+ readonly address: string;
+ readonly relatedAddress: string;
+ readonly discoveryDepth: number;
+}
+
+/** Trace one deterministic bounded direct caller/callee path. */
+export const traceCallPath = async (
+ call: AnalysisCall,
+ input: CallPathTraceInput,
+ signal?: AbortSignal,
+): EnhancedResult => {
+ const state = createTraceState(input);
+ while (
+ state.queueIndex < state.queue.length &&
+ state.traversalPath.length === 0
+ ) {
+ const address = state.queue[state.queueIndex++];
+ if (address === undefined) break;
+ const current = state.visited.get(address);
+ if (current === undefined) continue;
+ if (current.depth >= input.max_depth) {
+ state.frontier.add(address);
+ state.residual.add("Call-path traversal reached the depth limit.");
+ continue;
+ }
+ if (state.operations >= input.max_operations) {
+ recordPendingFrontier(state, input);
+ state.residual.add("Call-path traversal reached the operation budget.");
+ break;
+ }
+ state.operations += 1;
+ const found = await expandAddress(call, {
+ input,
+ state,
+ address,
+ current,
+ ...(signal === undefined ? {} : { signal }),
+ });
+ if (found) break;
+ }
+ return ok(projectTrace(input, state));
+};
+
+const createTraceState = (input: CallPathTraceInput): TraceState => ({
+ visited: new Map([[input.start, { depth: 0, path: [input.start] }]]),
+ queue: [input.start],
+ edges: new Map(),
+ failures: [],
+ frontier: new Set(),
+ residual: new Set(),
+ operations: 0,
+ queueIndex: 0,
+ traversalPath: input.goal === input.start ? [input.start] : [],
+});
+
+const expandAddress = async (
+ call: AnalysisCall,
+ expansion: AddressExpansion,
+): Promise<boolean> => {
+ const { input, state, address, current, signal } = expansion;
+ const relation = input.direction === "forward" ? "callees" : "callers";
+ const tool =
+ input.direction === "forward" ? "procedure_callees" : "procedure_callers";
+ const result = await call(tool, { procedure: address }, signal);
+ if (!result.ok) {
+ state.failures.push({
+ address,
+ error: projectAnalysisError(result.error),
+ });
+ state.residual.add(`Call relationships were unavailable for ${address}.`);
+ return false;
+ }
+ const related = parseRelatedAddresses(result.value, relation);
+ if (!related.ok) {
+ state.failures.push({
+ address,
+ error: projectAnalysisError(related.error),
+ });
+ state.residual.add(`Call relationships were unreadable for ${address}.`);
+ return false;
+ }
+ for (const relatedAddress of sortedUniqueAddresses(related.value)) {
+ recordEdge(input, state, {
+ address,
+ relatedAddress,
+ discoveryDepth: current.depth + 1,
+ });
+ const path = state.visited.get(relatedAddress)?.path ?? [
+ ...current.path,
+ relatedAddress,
+ ];
+ if (state.visited.has(relatedAddress)) {
+ if (relatedAddress === input.goal) {
+ state.traversalPath = path;
+ return true;
+ }
+ continue;
+ }
+ if (state.visited.size >= input.max_nodes) {
+ if (state.frontier.size < input.max_nodes)
+ state.frontier.add(relatedAddress);
+ state.residual.add("Call-path traversal reached the node limit.");
+ continue;
+ }
+ state.visited.set(relatedAddress, {
+ depth: current.depth + 1,
+ path,
+ });
+ if (relatedAddress === input.goal) {
+ state.traversalPath = path;
+ return true;
+ }
+ state.queue.push(relatedAddress);
+ }
+ return false;
+};
+
+const recordEdge = (
+ input: CallPathTraceInput,
+ state: TraceState,
+ edge: DiscoveredEdge,
+): void => {
+ const sourceAddress =
+ input.direction === "forward" ? edge.address : edge.relatedAddress;
+ const targetAddress =
+ input.direction === "forward" ? edge.relatedAddress : edge.address;
+ const edgeKey = `${sourceAddress}\u0000${targetAddress}`;
+ if (state.edges.has(edgeKey) || state.edges.size >= input.max_nodes) return;
+ state.edges.set(edgeKey, {
+ source_address: sourceAddress,
+ target_address: targetAddress,
+ discovery_depth: edge.discoveryDepth,
+ });
+};
+
+const recordPendingFrontier = (
+ state: TraceState,
+ input: CallPathTraceInput,
+): void => {
+ for (const pending of state.queue.slice(state.queueIndex - 1))
+ if (state.frontier.size < input.max_nodes) state.frontier.add(pending);
+};
+
+const projectTrace = (input: CallPathTraceInput, state: TraceState) => ({
+ start: input.start,
+ goal: input.goal ?? null,
+ direction: input.direction,
+ goal_status:
+ input.goal === undefined
+ ? "not_requested"
+ : state.traversalPath.length > 0
+ ? "reached"
+ : "not_reached",
+ nodes: [...state.visited.entries()]
+ .map(([address, { depth }]) => ({ address, depth }))
+ .sort(
+ (left, right) =>
+ left.depth - right.depth || compareAddress(left.address, right.address),
+ ),
+ edges: [...state.edges.values()].sort(
+ (left, right) =>
+ left.discovery_depth - right.discovery_depth ||
+ compareAddress(left.source_address, right.source_address) ||
+ compareAddress(left.target_address, right.target_address),
+ ),
+ traversal_path: state.traversalPath,
+ failures: state.failures,
+ frontier: [...state.frontier].sort(compareAddress),
+ limits: {
+ max_depth: input.max_depth,
+ max_nodes: input.max_nodes,
+ max_operations: input.max_operations,
+ nodes_visited: state.visited.size,
+ operations_used: state.operations,
+ },
+ truncated: state.residual.size > 0,
+ residual_unknowns: [...state.residual],
+ limitations: [
+ "Direct provider call relationships may omit unresolved indirect calls.",
+ "A not_reached goal is only absent from this bounded traversal, not from the complete program.",
+ ],
+});
+
+const compareAddress = (left: string, right: string): number =>
+ left < right ? -1 : left > right ? 1 : 0;
+
+const sortedUniqueAddresses = (addresses: readonly string[]): string[] =>
+ [...new Set(addresses)].sort(compareAddress);
diff --git a/src/application/EnhancedLiteralTracing.ts b/src/application/EnhancedLiteralTracing.ts
new file mode 100644
index 000000000..026afc85e
--- /dev/null
+++ b/src/application/EnhancedLiteralTracing.ts
@@ -0,0 +1,185 @@
+import type { AnalysisOperation } from "./AnalysisProvider.js";
+import { AnalysisOutputError, type AnalysisError } from "../domain/errors.js";
+import { parseAddressedPage } from "../domain/hopperValues.js";
+import type { JsonValue } from "../domain/jsonValue.js";
+import { err, ok, type Result } from "../domain/result.js";
+import type {
+ EnhancedResult,
+ TraceMatch,
+ TraceReference,
+} from "./EnhancedToolTypes.js";
+
+type AnalysisCall = (
+ name: AnalysisOperation,
+ arguments_: Readonly<Record<string, JsonValue>>,
+ signal?: AbortSignal,
+) => Promise<Result<JsonValue, AnalysisError>>;
+
+type LiteralSearchSource = readonly [
+ "list_strings" | "list_procedures",
+ "string" | "procedure",
+];
+
+interface ReferenceTraceRequest {
+ readonly matches: readonly TraceMatch[];
+ readonly limit: number;
+ readonly operationBudget: number;
+ readonly signal?: AbortSignal;
+}
+
+const FEATURE_SEARCH_SOURCES: readonly LiteralSearchSource[] = [
+ ["list_strings", "string"],
+ ["list_procedures", "procedure"],
+];
+const STRING_SEARCH_SOURCES: readonly LiteralSearchSource[] = [
+ ["list_strings", "string"],
+];
+
+export interface LiteralTraceInput {
+ readonly query: string;
+ readonly case_sensitive: boolean;
+ readonly limit: number;
+ readonly max_operations: number;
+}
+
+/** Trace a bounded feature or string literal through provider xrefs. */
+export const traceLiteralFeature = async (
+ call: AnalysisCall,
+ input: LiteralTraceInput,
+ scope: "feature" | "string",
+ signal?: AbortSignal,
+): EnhancedResult => {
+ const sources =
+ scope === "feature" ? FEATURE_SEARCH_SOURCES : STRING_SEARCH_SOURCES;
+ const searched = await literalMatches(call, input, sources, signal);
+ if (!searched.ok) return searched;
+ const residual = new Set<string>();
+ const traced = await traceReferences(call, {
+ matches: searched.value.matches,
+ limit: input.limit,
+ operationBudget: input.max_operations - searched.value.operations,
+ ...(signal === undefined ? {} : { signal }),
+ });
+ if (!traced.ok) return traced;
+ for (const reason of traced.value.residual) residual.add(reason);
+ const operations = searched.value.operations + traced.value.operations;
+ if (operations >= input.max_operations)
+ residual.add("Investigation reached the operation budget.");
+ if (searched.value.matches.length >= input.limit)
+ residual.add("Literal matches reached the configured limit.");
+ return ok({
+ query: input.query,
+ search_mode: "literal",
+ operations_used: operations,
+ operation_budget: input.max_operations,
+ matches: searched.value.matches,
+ references: traced.value.references,
+ truncated: residual.size > 0,
+ residual_unknowns: [...residual],
+ });
+};
+
+const literalMatches = async (
+ call: AnalysisCall,
+ input: LiteralTraceInput,
+ sources: readonly LiteralSearchSource[],
+ signal?: AbortSignal,
+): Promise<
+ Result<{ matches: TraceMatch[]; operations: number }, AnalysisError>
+> => {
+ let operations = 0;
+ const matches: TraceMatch[] = [];
+ const needle = input.case_sensitive ? input.query : input.query.toLowerCase();
+ for (const [tool, type] of sources) {
+ let offset = 0;
+ while (operations < input.max_operations && matches.length < input.limit) {
+ operations += 1;
+ const result = await call(tool, { offset, limit: 500 }, signal);
+ if (!result.ok) return result;
+ const page = parseAddressedPage(result.value);
+ if (!page.ok) return page;
+ for (const item of page.value.items) {
+ const haystack = input.case_sensitive
+ ? item.name
+ : item.name.toLowerCase();
+ if (haystack.includes(needle))
+ matches.push({ type, address: item.address, value: item.name });
+ if (matches.length >= input.limit) break;
+ }
+ if (!page.value.hasMore || page.value.nextOffset === null) break;
+ offset = page.value.nextOffset;
+ }
+ }
+ return ok({ matches, operations });
+};
+
+const traceReferences = async (
+ call: AnalysisCall,
+ request: ReferenceTraceRequest,
+): Promise<
+ Result<
+ { references: TraceReference[]; operations: number; residual: string[] },
+ AnalysisError
+ >
+> => {
+ let operations = 0;
+ const references: TraceReference[] = [];
+ const residual = new Set<string>();
+ for (const match of request.matches) {
+ if (operations >= request.operationBudget) {
+ residual.add("Reference traversal stopped at the operation budget.");
+ break;
+ }
+ operations += 1;
+ const xrefs = await call(
+ "xrefs",
+ { address: match.address },
+ request.signal,
+ );
+ if (!xrefs.ok) return xrefs;
+ if (!Array.isArray(xrefs.value))
+ return err(
+ new AnalysisOutputError(
+ "xrefs",
+ "provider returned a non-array result",
+ ),
+ );
+ for (const source of xrefs.value) {
+ if (typeof source !== "string")
+ return err(
+ new AnalysisOutputError(
+ "xrefs",
+ "provider returned a non-address value",
+ ),
+ );
+ if (operations >= request.operationBudget) {
+ residual.add(
+ "Containing-procedure resolution stopped at the operation budget.",
+ );
+ break;
+ }
+ operations += 1;
+ const resolved = await call(
+ "resolve_containing_procedure",
+ { address: source },
+ request.signal,
+ );
+ if (!resolved.ok) return resolved;
+ references.push({
+ target_address: match.address,
+ source_address: source,
+ containing_procedure: resolved.value,
+ });
+ if (references.length >= request.limit) {
+ residual.add("Reference results reached the configured limit.");
+ break;
+ }
+ }
+ if (references.length >= request.limit) break;
+ }
+ return ok({
+ references,
+ operations,
+ residual: [...residual],
+ });
+};
diff --git a/src/application/EnhancedTools.ts b/src/application/EnhancedTools.ts
index 12c4539ff..96cf7ed6f 100644
--- a/src/application/EnhancedTools.ts
+++ b/src/application/EnhancedTools.ts
@@ -12,7 +12,6 @@ import {
} from "../domain/errors.js";
import {
addressDistance,
- parseAddressedPage,
parseDocuments,
parseFunctionDossier,
parseListCount,
@@ -31,11 +30,11 @@ import type { JsonValue } from "../domain/jsonValue.js";
import {
invalidEnhancedInput,
type EnhancedResult,
- type TraceMatch,
- type TraceReference,
type ValidatedEnhancedCall,
} from "./EnhancedToolTypes.js";
import { readAllAddressed } from "./EnhancedToolPagination.js";
+import { traceCallPath } from "./CallPathTracing.js";
+import { traceLiteralFeature } from "./EnhancedLiteralTracing.js";
export type { ValidatedEnhancedCall } from "./EnhancedToolTypes.js";
/**
@@ -52,6 +51,12 @@ export class EnhancedTools {
input: unknown,
signal?: AbortSignal,
): EnhancedResult {
+ if (
+ name === "trace_feature" ||
+ name === "find_code_for_string" ||
+ name === "trace_call_path"
+ )
+ return this.#executeTracing(name, input, signal);
switch (name) {
case "swift_classes": {
const parsed = enhancedInputSchemas.swift_classes.safeParse(input);
@@ -99,12 +104,6 @@ export class EnhancedTools {
? this.executeValidated({ name, input: parsed.data }, signal)
: invalidEnhancedInput(name, parsed.error);
}
- case "trace_feature": {
- const parsed = enhancedInputSchemas.trace_feature.safeParse(input);
- return parsed.success
- ? this.executeValidated({ name, input: parsed.data }, signal)
- : invalidEnhancedInput(name, parsed.error);
- }
}
}
@@ -133,10 +132,55 @@ export class EnhancedTools {
case "analyze_function":
return this.#analyzeFunction(call.input, signal);
case "trace_feature":
- return this.#traceFeature(call.input, signal);
+ return traceLiteralFeature(
+ (name, arguments_, operationSignal) =>
+ this.#call(name, arguments_, operationSignal),
+ call.input,
+ "feature",
+ signal,
+ );
+ case "find_code_for_string":
+ return traceLiteralFeature(
+ (name, arguments_, operationSignal) =>
+ this.#call(name, arguments_, operationSignal),
+ call.input,
+ "string",
+ signal,
+ );
+ case "trace_call_path":
+ return traceCallPath(
+ (name, arguments_, operationSignal) =>
+ this.#call(name, arguments_, operationSignal),
+ call.input,
+ signal,
+ );
}
}
+ #executeTracing(
+ name: "trace_feature" | "find_code_for_string" | "trace_call_path",
+ input: unknown,
+ signal?: AbortSignal,
+ ): EnhancedResult {
+ const parsed = enhancedInputSchemas[name].safeParse(input);
+ if (!parsed.success) return invalidEnhancedInput(name, parsed.error);
+ if (name === "trace_call_path")
+ return this.executeValidated(
+ {
+ name,
+ input: enhancedInputSchemas.trace_call_path.parse(parsed.data),
+ },
+ signal,
+ );
+ return this.executeValidated(
+ {
+ name,
+ input: enhancedInputSchemas[name].parse(parsed.data),
+ },
+ signal,
+ );
+ }
+
async #analyzeFunction(
input: Readonly<Record<string, JsonValue>>,
signal?: AbortSignal,
@@ -346,161 +390,6 @@ export class EnhancedTools {
});
}
- async #traceFeature(
- input: {
- readonly query: string;
- readonly case_sensitive: boolean;
- readonly limit: number;
- readonly max_operations: number;
- },
- signal?: AbortSignal,
- ): EnhancedResult {
- const searched = await this.#literalMatches(input, signal);
- if (!searched.ok) return searched;
- const residual = new Set<string>();
- const traced = await this.#traceReferences(
- searched.value.matches,
- input.limit,
- input.max_operations - searched.value.operations,
- signal,
- );
- if (!traced.ok) return traced;
- for (const reason of traced.value.residual) residual.add(reason);
- const operations = searched.value.operations + traced.value.operations;
- if (operations >= input.max_operations)
- residual.add("Investigation reached the operation budget.");
- if (searched.value.matches.length >= input.limit)
- residual.add("Literal matches reached the configured limit.");
- return ok({
- query: input.query,
- search_mode: "literal",
- operations_used: operations,
- operation_budget: input.max_operations,
- matches: searched.value.matches,
- references: traced.value.references,
- truncated: residual.size > 0,
- residual_unknowns: [...residual],
- });
- }
-
- async #literalMatches(
- input: {
- readonly query: string;
- readonly case_sensitive: boolean;
- readonly limit: number;
- readonly max_operations: number;
- },
- signal?: AbortSignal,
- ): Promise<
- Result<{ matches: TraceMatch[]; operations: number }, AnalysisError>
- > {
- let operations = 0;
- const matches: TraceMatch[] = [];
- const needle = input.case_sensitive
- ? input.query
- : input.query.toLowerCase();
- for (const [tool, type] of [
- ["list_strings", "string"],
- ["list_procedures", "procedure"],
- ] as const) {
- let offset = 0;
- while (
- operations < input.max_operations &&
- matches.length < input.limit
- ) {
- operations += 1;
- const result = await this.#call(tool, { offset, limit: 500 }, signal);
- if (!result.ok) return result;
- const page = parseAddressedPage(result.value);
- if (!page.ok) return page;
- for (const item of page.value.items) {
- const haystack = input.case_sensitive
- ? item.name
- : item.name.toLowerCase();
- if (haystack.includes(needle))
- matches.push({ type, address: item.address, value: item.name });
- if (matches.length >= input.limit) break;
- }
- if (!page.value.hasMore || page.value.nextOffset === null) break;
- offset = page.value.nextOffset;
- }
- }
- return ok({ matches, operations });
- }
-
- async #traceReferences(
- matches: readonly TraceMatch[],
- limit: number,
- operationBudget: number,
- signal?: AbortSignal,
- ): Promise<
- Result<
- { references: TraceReference[]; operations: number; residual: string[] },
- AnalysisError
- >
- > {
- let operations = 0;
- const references: TraceReference[] = [];
- const residual = new Set<string>();
- for (const match of matches) {
- if (operations >= operationBudget) {
- residual.add("Reference traversal stopped at the operation budget.");
- break;
- }
- operations += 1;
- const xrefs = await this.#call(
- "xrefs",
- { address: match.address },
- signal,
- );
- if (!xrefs.ok) return xrefs;
- if (!Array.isArray(xrefs.value))
- return err(
- new AnalysisOutputError(
- "xrefs",
- "provider returned a non-array result",
- ),
- );
- for (const source of xrefs.value) {
- if (typeof source !== "string")
- return err(
- new AnalysisOutputError(
- "xrefs",
- "provider returned a non-address value",
- ),
- );
- if (operations >= operationBudget) {
- residual.add(
- "Containing-procedure resolution stopped at the operation budget.",
- );
- break;
- }
- operations += 1;
- const resolved = await this.#call(
- "resolve_containing_procedure",
- { address: source },
- signal,
- );
- if (!resolved.ok) return resolved;
- references.push({
- target_address: match.address,
- source_address: source,
- containing_procedure: resolved.value,
- });
- if (references.length >= limit) {
- residual.add("Reference results reached the configured limit.");
- break;
- }
- }
- if (references.length >= limit) break;
- }
- return ok({
- references,
- operations,
- residual: [...residual],
- });
- }
-
async #allAddressed(
tool: "list_names" | "list_procedures",
signal?: AbortSignal,
diff --git a/src/contracts/analysisSearchContract.ts b/src/contracts/analysisSearchContract.ts
new file mode 100644
index 000000000..0d8d6b8a1
--- /dev/null
+++ b/src/contracts/analysisSearchContract.ts
@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+/** Shared bounded provider search input fields. */
+export const analysisSearchInput = {
+ pattern: z
+ .string()
+ .min(1)
+ .max(256)
+ .describe("The literal text or bounded regex pattern to search for"),
+ mode: z.enum(["literal", "regex"]).default("literal"),
+ case_sensitive: z.boolean().default(false).describe("Whether to match case"),
+ offset: z.number().int().min(0).default(0),
+ limit: z.number().int().min(1).max(100).default(100),
+ document: z.string().optional().describe("The document name"),
+};
diff --git a/src/contracts/enhancedInputs.ts b/src/contracts/enhancedInputs.ts
index 689f1be3c..3841b02a2 100644
--- a/src/contracts/enhancedInputs.ts
+++ b/src/contracts/enhancedInputs.ts
@@ -1,5 +1,16 @@
import { z } from "zod";
+const traceLiteralInputSchema = z.object({
+ query: z.string().min(1),
+ case_sensitive: z.boolean().default(false),
+ limit: z.number().int().min(1).max(100).default(20),
+ max_operations: z.number().int().min(1).max(100).default(20),
+ unknown_registry_approved: z
+ .literal(true)
+ .optional()
+ .describe("Explicit approval to record bounded residuals durably"),
+});
+
/** Input schemas shared by MCP registration and enhanced application dispatch. */
export const enhancedInputSchemas = {
swift_classes: z.object({ pattern: z.string().default("") }),
@@ -52,11 +63,18 @@ export const enhancedInputSchemas = {
basic_blocks: 0,
}),
}),
- trace_feature: z.object({
- query: z.string().min(1),
- case_sensitive: z.boolean().default(false),
- limit: z.number().int().min(1).max(100).default(20),
- max_operations: z.number().int().min(1).max(100).default(20),
+ trace_feature: traceLiteralInputSchema,
+ find_code_for_string: traceLiteralInputSchema,
+ trace_call_path: z.object({
+ start: z.string().describe("A provider-normalized procedure address"),
+ goal: z
+ .string()
+ .describe("An optional provider-normalized destination address")
+ .optional(),
+ direction: z.enum(["forward", "backward"]).default("forward"),
+ max_depth: z.number().int().min(1).max(10).default(5),
+ max_nodes: z.number().int().min(1).max(500).default(100),
+ max_operations: z.number().int().min(1).max(500).default(100),
unknown_registry_approved: z
.literal(true)
.optional()
@@ -66,7 +84,7 @@ export const enhancedInputSchemas = {
export type EnhancedToolName = keyof typeof enhancedInputSchemas;
-/** Runtime parser for dispatching only the eight closed enhanced names. */
+/** Runtime parser for dispatching only the closed enhanced names. */
export const enhancedToolNameSchema = z.enum([
"swift_classes",
"get_objc_classes",
@@ -78,4 +96,6 @@ export const enhancedToolNameSchema = z.enum([
"binary_overview",
"analyze_function",
"trace_feature",
+ "find_code_for_string",
+ "trace_call_path",
]);
diff --git a/src/contracts/hopperMemoryContracts.ts b/src/contracts/hopperMemoryContracts.ts
new file mode 100644
index 000000000..0488ea5ac
--- /dev/null
+++ b/src/contracts/hopperMemoryContracts.ts
@@ -0,0 +1,28 @@
+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",
+ );
+
+/** Bounded Hopper memory and file-mapping contracts. */
+export const HOPPER_MEMORY_TOOL_DEFINITIONS = [
+ {
+ name: "read_bytes",
+ description:
+ "Read at most 4,096 analyzed bytes from one provider-normalized virtual address. The hexadecimal payload reports the exact returned length; incomplete reads remain explicit and unsupported provider APIs return typed capability unavailability.",
+ inputSchema: z.object({
+ address,
+ length: z.number().int().min(1).max(4_096).default(256),
+ document,
+ }),
+ },
+ {
+ 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.",
+ inputSchema: z.object({ address, document }),
+ },
+] as const;
diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.ts
index 699ab8415..6d2d0f2b7 100644
--- a/src/hopper/HopperClient.ts
+++ b/src/hopper/HopperClient.ts
@@ -5,11 +5,13 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import {
+ AnalysisCapabilityUnavailableError,
HopperCancelledError,
type AnalysisError,
type HopperError,
HopperProcessError,
HopperProtocolError,
+ HopperRemoteError,
HopperStartError,
hopperStartupFailure,
HopperTimeoutError,
@@ -279,10 +281,21 @@ export class HopperClient {
readonly timeoutMs?: number;
readonly progress?: ProgressReporter;
} = {},
- ): Promise<Result<JsonValue, HopperError>> {
+ ): Promise<Result<JsonValue, AnalysisError>> {
const started = await this.start(options.signal);
if (!started.ok) return started;
- return this.#request(name, arguments_, options);
+ const result = await this.#request(name, arguments_, options);
+ return !result.ok &&
+ result.error instanceof HopperRemoteError &&
+ result.error.diagnosticType === "capability_unavailable"
+ ? err(
+ new AnalysisCapabilityUnavailableError(
+ "hopper",
+ name,
+ result.error.safeMessage,
+ ),
+ )
+ : result;
}
/** Stop the bridge, settle outstanding requests, and remove session artifacts. */
diff --git a/src/hopper/HopperProvider.ts b/src/hopper/HopperProvider.ts
index fabbaa7f5..a7f641cae 100644
--- a/src/hopper/HopperProvider.ts
+++ b/src/hopper/HopperProvider.ts
@@ -75,7 +75,7 @@ const CAPABILITIES: readonly CapabilityDescriptor[] = Object.freeze(
}),
limits: Object.freeze({
maxResults: null,
- maxPayloadBytes: null,
+ maxPayloadBytes: contract.name === "read_bytes" ? 4_096 : null,
timeoutMs: null,
}),
limitations: Object.freeze([
diff --git a/src/hopper/protocol.ts b/src/hopper/protocol.ts
index 92571a42e..370b775ff 100644
--- a/src/hopper/protocol.ts
+++ b/src/hopper/protocol.ts
@@ -19,6 +19,7 @@ const responseSchema = z.union([
"remote",
"authorization",
"invalid_request",
+ "capability_unavailable",
"bridge_exception",
])
.default("remote"),
diff --git a/src/server/registerEnhancedTools.ts b/src/server/registerEnhancedTools.ts
index 7f51ef21d..fbf19b2bc 100644
--- a/src/server/registerEnhancedTools.ts
+++ b/src/server/registerEnhancedTools.ts
@@ -229,6 +229,18 @@ const ENHANCED_INPUT_PARSERS: {
input,
"trace_feature",
),
+ find_code_for_string: (input) =>
+ safeParseToolInput(
+ enhancedInputSchemas.find_code_for_string,
+ input,
+ "find_code_for_string",
+ ),
+ trace_call_path: (input) =>
+ safeParseToolInput(
+ enhancedInputSchemas.trace_call_path,
+ input,
+ "trace_call_path",
+ ),
};
const parseEnhancedCall = (
@@ -286,6 +298,16 @@ const parseEnhancedCall = (
ENHANCED_INPUT_PARSERS.trace_feature(input),
(value) => ({ name, input: value }),
);
+ case "find_code_for_string":
+ return mapEnhancedCall(
+ ENHANCED_INPUT_PARSERS.find_code_for_string(input),
+ (value) => ({ name, input: value }),
+ );
+ case "trace_call_path":
+ return mapEnhancedCall(
+ ENHANCED_INPUT_PARSERS.trace_call_path(input),
+ (value) => ({ name, input: value }),
+ );
}
};
@@ -313,7 +335,9 @@ const recordWorkflowUnknowns = ({
| ReturnType<BinarySessionPort["recordUnknown"]>
| { readonly ok: true; readonly value: null } => {
if (
- name !== "trace_feature" ||
+ !["trace_feature", "find_code_for_string", "trace_call_path"].includes(
+ name,
+ ) ||
input.unknown_registry_approved !== true ||
recordUnknown === undefined ||
typeof result !== "object" ||
@@ -336,7 +360,7 @@ const recordWorkflowUnknowns = ({
required_environment: null,
recommended_probes: [
{
- operation: "trace_feature",
+ operation: name,
rationale: "Continue with a larger bounded budget.",
},
],
diff --git a/tests/enhancedTools.test.ts b/tests/enhancedTools.test.ts
index a36346775..65552d7d0 100644
--- a/tests/enhancedTools.test.ts
+++ b/tests/enhancedTools.test.ts
@@ -213,7 +213,7 @@ describe("enhanced MCP tools", () => {
).toEqual(ENHANCED_TOOL_CONTRACTS.map(({ name }) => name).sort());
});
- it("executes all ten tools through production registration", async () => {
+ it("executes all twelve tools through production registration", async () => {
const client = await connect();
const calls = [
["swift_classes", { pattern: "Fixture" }],
@@ -226,6 +226,8 @@ describe("enhanced MCP tools", () => {
["binary_overview", {}],
["analyze_function", { procedure: "0x1" }],
["trace_feature", { query: "hello", max_operations: 10 }],
+ ["find_code_for_string", { query: "hello", max_operations: 10 }],
+ ["trace_call_path", { start: "0x1", goal: "0x2", max_operations: 10 }],
] as const;
const results = await Promise.all(
calls.map(async ([name, arguments_]) =>
@@ -277,6 +279,53 @@ describe("enhanced MCP tools", () => {
{ target_address: "0x30", source_address: "0x21" },
],
});
+ expect(results[10]).toMatchObject({
+ query: "hello",
+ matches: [{ type: "string", address: "0x30", value: "hello" }],
+ truncated: false,
+ });
+ expect(results[11]).toMatchObject({
+ start: "0x1",
+ goal: "0x2",
+ direction: "forward",
+ goal_status: "reached",
+ traversal_path: ["0x1", "0x2"],
+ nodes: [
+ { address: "0x1", depth: 0 },
+ { address: "0x2", depth: 1 },
+ ],
+ truncated: false,
+ });
+ });
+
+ it("returns Evidence IDs and explicit call-path frontiers at limits", async () => {
+ const client = await connect();
+ const result = await client.callTool({
+ name: "trace_call_path",
+ arguments: {
+ start: "0x1",
+ goal: "0x3",
+ max_nodes: 1,
+ max_operations: 10,
+ },
+ });
+
+ expect(result.isError).not.toBe(true);
+ expect(result.structuredContent).toMatchObject({
+ evidence_id: expect.stringMatching(/^ev_[a-f0-9]{64}$/u),
+ result: {
+ goal_status: "not_reached",
+ nodes: [{ address: "0x1", depth: 0 }],
+ frontier: ["0x2"],
+ truncated: true,
+ residual_unknowns: [expect.stringContaining("reached the node limit")],
+ limits: {
+ max_nodes: 1,
+ nodes_visited: 1,
+ operations_used: 1,
+ },
+ },
+ });
});
it("bounds batch concurrency at the parsed maximum of 20", async () => {
diff --git a/tests/fixtures/bridgeRegexProbe.py b/tests/fixtures/bridgeRegexProbe.py
index d4655670b..b566e7f56 100644
--- a/tests/fixtures/bridgeRegexProbe.py
+++ b/tests/fixtures/bridgeRegexProbe.py
@@ -7,11 +7,8 @@ import sys
def _load_bridge(path):
source = Path(path).read_text(encoding="utf-8")
- prefix, marker, suffix = source.rpartition("\n_run()")
- if not marker or suffix.strip():
- raise RuntimeError("bridge entrypoint shape changed")
- namespace = {"__file__": path}
- exec(compile(prefix, path, "exec"), namespace)
+ namespace = {"__file__": path, "__name__": "rea_hopper_bridge"}
+ exec(compile(source, path, "exec"), namespace)
return namespace
diff --git a/tests/fixtures/fakeHopper.mjs b/tests/fixtures/fakeHopper.mjs
index bf091a59c..7259fc822 100644
--- a/tests/fixtures/fakeHopper.mjs
+++ b/tests/fixtures/fakeHopper.mjs
@@ -8,6 +8,14 @@ const shutdownResult = () => ({
document_closed: shutdownMode !== "unconfirmed",
...(shutdownMode === "cleanup-required" ? { cleanup_required: true } : {}),
});
+const capabilityUnavailableResult = (id) => ({
+ id,
+ error: {
+ code: -32000,
+ message: "fixture API is unavailable",
+ type: "capability_unavailable",
+ },
+});
const enhancedFixtureResult = (method) => {
switch (method) {
case "list_segments":
@@ -153,6 +161,8 @@ const server = createServer((socket) => {
type: "bridge_exception",
},
});
+ } else if (request.method === "capability_unavailable") {
+ send(capabilityUnavailableResult(request.id));
} else if (request.method === "current_document") {
send({ id: request.id, result: "fixture" });
} else if (enhancedFixtureResult(request.method) !== undefined) {
diff --git a/tests/fixtures/hopperBridgeFacadeProbe.py b/tests/fixtures/hopperBridgeFacadeProbe.py
new file mode 100644
index 000000000..aefad41ec
--- /dev/null
+++ b/tests/fixtures/hopperBridgeFacadeProbe.py
@@ -0,0 +1,92 @@
+"""Exercise the Hopper bridge facade without importing Hopper globals."""
+
+import json
+from pathlib import Path
+import sys
+
+
+class FakeDocument:
+ def __init__(self):
+ self.analysis_active = True
+
+ def getDocumentName(self):
+ return "fixture"
+
+ def getExecutableFilePath(self):
+ return "/tmp/rea-hopper-facade-fixture"
+
+ def getDatabaseFilePath(self):
+ return None
+
+ def backgroundProcessActive(self):
+ return self.analysis_active
+
+ def getCurrentAddress(self):
+ return 0x401000
+
+
+class FakeDocumentProvider:
+ document = FakeDocument()
+
+ @classmethod
+ def getAllDocuments(cls):
+ return [cls.document]
+
+ @classmethod
+ def getCurrentDocument(cls):
+ return cls.document
+
+
+def load_bridge(path):
+ namespace = {
+ "__file__": path,
+ "__name__": "rea_hopper_bridge",
+ }
+ source = Path(path).read_text(encoding="utf-8")
+ exec(compile(source, path, "exec"), namespace)
+ return namespace
+
+
+def main():
+ bridge = load_bridge(sys.argv[1])
+ unavailable = None
+ try:
+ bridge["_api"]()
+ except Exception as error:
+ unavailable = {
+ "type": type(error).__name__,
+ "diagnostic_type": bridge["_diagnostic_type"](error),
+ }
+
+ bridge["REA_TARGET_PATH"] = "/tmp/rea-hopper-facade-fixture"
+ bridge["_configure_hopper_api"](FakeDocumentProvider)
+ current = bridge["_dispatch"]("current_document", {})
+ current_address = bridge["_dispatch"]("current_address", {})
+ selected = bridge["_session_document"]().getDocumentName()
+
+ analysis_guard = None
+ try:
+ bridge["_dispatch"]("list_procedures", {"offset": 0, "limit": 1})
+ except Exception as error:
+ analysis_guard = {
+ "type": type(error).__name__,
+ "diagnostic_type": bridge["_diagnostic_type"](error),
+ "message": str(error),
+ }
+
+ print(
+ json.dumps(
+ {
+ "imported_without_hopper": unavailable,
+ "current_document": current,
+ "current_address": current_address,
+ "session_document": selected,
+ "analysis_guard": analysis_guard,
+ },
+ sort_keys=True,
+ )
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/hopperBridgeFacade.test.ts b/tests/hopperBridgeFacade.test.ts
new file mode 100644
index 000000000..a7b53bbfb
--- /dev/null
+++ b/tests/hopperBridgeFacade.test.ts
@@ -0,0 +1,45 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+const execute = promisify(execFile);
+const bridgePath = new URL("../bridge/hopper_bridge.py", import.meta.url);
+const probePath = new URL(
+ "./fixtures/hopperBridgeFacadeProbe.py",
+ import.meta.url,
+);
+
+const probeResultSchema = z.strictObject({
+ imported_without_hopper: z.strictObject({
+ type: z.literal("CapabilityUnavailableError"),
+ diagnostic_type: z.literal("capability_unavailable"),
+ }),
+ current_document: z.literal("fixture"),
+ current_address: z.literal("0x401000"),
+ session_document: z.literal("fixture"),
+ analysis_guard: z.strictObject({
+ type: z.literal("CapabilityUnavailableError"),
+ diagnostic_type: z.literal("capability_unavailable"),
+ message: z.string(),
+ }),
+});
+
+describe("Hopper API facade", () => {
+ it("imports without Hopper globals and gates exhaustive work during analysis", async () => {
+ const { stdout } = await execute(
+ "python3",
+ [probePath.pathname, bridgePath.pathname],
+ {
+ encoding: "utf8",
+ timeout: 3_000,
+ maxBuffer: 1_024 * 1_024,
+ },
+ );
+ const result = probeResultSchema.parse(JSON.parse(stdout));
+ expect(result.analysis_guard.message).toContain(
+ "requires completed Hopper background analysis",
+ );
+ });
+});
diff --git a/tests/hopperClient.test.ts b/tests/hopperClient.test.ts
index c7af32efa..2fd88ac47 100644
--- a/tests/hopperClient.test.ts
+++ b/tests/hopperClient.test.ts
@@ -278,7 +278,7 @@ describe("HopperClient", () => {
const results = await Promise.all(
OFFICIAL_TOOL_CONTRACTS.map(({ name }) => client.callTool(name, {})),
);
- expect(results).toHaveLength(34);
+ expect(results).toHaveLength(36);
expect(results.every((result) => result.ok)).toBe(true);
});
@@ -317,6 +317,19 @@ describe("HopperClient", () => {
});
});
+ it("projects a missing bridge API as typed capability unavailability", async () => {
+ const client = await startClient();
+ const result = await client.callTool("capability_unavailable");
+ expect(result.ok).toBe(false);
+ if (!result.ok)
+ expect(result.error).toMatchObject({
+ _tag: "AnalysisCapabilityUnavailableError",
+ providerId: "hopper",
+ operation: "capability_unavailable",
+ reason: "fixture API is unavailable",
+ });
+ });
+
it("cancels and ignores late responses without corrupting the session", async () => {
const client = await startClient();
const controller = new AbortController();
diff --git a/tests/hopperProviderSelection.test.ts b/tests/hopperProviderSelection.test.ts
index e4edabbe5..62cc52aca 100644
--- a/tests/hopperProviderSelection.test.ts
+++ b/tests/hopperProviderSelection.test.ts
@@ -50,6 +50,26 @@ describe("Hopper provider discovery", () => {
code: "architecture_unsupported",
});
});
+
+ it("advertises the exact bounded byte-read limit", () => {
+ const capabilities = provider(process.execPath).capabilities();
+ expect(
+ capabilities.find(({ operation }) => operation === "read_bytes"),
+ ).toMatchObject({
+ available: true,
+ pagination: "none",
+ limits: {
+ maxResults: null,
+ maxPayloadBytes: 4_096,
+ timeoutMs: null,
+ },
+ });
+ expect(
+ capabilities.find(
+ ({ operation }) => operation === "address_to_file_offset",
+ ),
+ ).toMatchObject({ available: true, pagination: "none" });
+ });
});
const provider = (launcherPath: string): HopperProvider => {
diff --git a/tests/officialTools.test.ts b/tests/officialTools.test.ts
index f6bc450df..991ac8e14 100644
--- a/tests/officialTools.test.ts
+++ b/tests/officialTools.test.ts
@@ -33,6 +33,8 @@ const VALID_INPUTS: Readonly<
procedure_callers: { procedure: "main" },
procedure_info: { procedure: "main" },
read_function_instructions: { procedure: "main" },
+ read_bytes: { address: "0x1000", length: 4 },
+ address_to_file_offset: { address: "0x1000" },
procedure_references: { procedure: "main" },
procedure_pseudo_code: { procedure: "main" },
resolve_containing_procedure: { address: "0x1000" },
@@ -130,6 +132,16 @@ const outputFor = (name: string): JsonValue => {
instruction_scan_truncated: false,
limitations: ["Provider-specific instruction text."],
};
+ if (name === "read_bytes")
+ return {
+ address: "0x1000",
+ requested_bytes: 4,
+ returned_bytes: 4,
+ bytes_hex: "c3c3c3c3",
+ complete: true,
+ };
+ if (name === "address_to_file_offset")
+ return { address: "0x1000", file_offset: 0 };
if (name === "procedure_references")
return {
procedure: { address: "0x1000", name: "main" },
diff --git a/tests/providerArchitecture.test.ts b/tests/providerArchitecture.test.ts
index be1cbe89a..c18abad65 100644
--- a/tests/providerArchitecture.test.ts
+++ b/tests/providerArchitecture.test.ts
@@ -78,7 +78,7 @@ describe("provider-neutral architecture", () => {
if (!config.ok) return;
const provider = new HopperProvider(config.value, silentLogger);
const capabilities = provider.capabilities();
- expect(capabilities).toHaveLength(35);
+ expect(capabilities).toHaveLength(37);
expect(new Set(capabilities.map(({ operation }) => operation)).size).toBe(
capabilities.length,
);