feat(analysis): add bounded memory and call tracing

This commit is contained in:
morluto
2026-07-24 13:14:01 +00:00
parent 205bf1529b
commit 8e7709d35a
21 changed files with 1025 additions and 188 deletions
+142 -4
View File
@@ -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()
+42
View File
@@ -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,
};
};
+244
View File
@@ -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);
+185
View File
@@ -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],
});
};
+54 -165
View File
@@ -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,
+15
View File
@@ -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"),
};
+26 -6
View File
@@ -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",
]);
+28
View File
@@ -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;
+15 -2
View File
@@ -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. */
+1 -1
View File
@@ -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([
+1
View File
@@ -19,6 +19,7 @@ const responseSchema = z.union([
"remote",
"authorization",
"invalid_request",
"capability_unavailable",
"bridge_exception",
])
.default("remote"),
+26 -2
View File
@@ -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.",
},
],
+50 -1
View File
@@ -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 () => {
+2 -5
View File
@@ -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
+10
View File
@@ -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) {
+92
View File
@@ -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()
+45
View File
@@ -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",
);
});
});
+14 -1
View File
@@ -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();
+20
View File
@@ -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 => {
+12
View File
@@ -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" },
+1 -1
View File
@@ -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,
);