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>, + signal?: AbortSignal, +) => Promise>; + +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; + }>; + readonly frontier: Set; + readonly residual: Set; + 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 => { + 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>, + signal?: AbortSignal, +) => Promise>; + +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(); + 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(); + 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>, 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(); - 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(); - 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> { + ): Promise> { 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 | { 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, );