rea-agents 2.4.0 → 3.0.0

package/bridge/hopper_bridge.py

@@ -11,19 +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:
@@ -36,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
 
@@ -54,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:
@@ -64,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
@@ -225,12 +318,35 @@ def _invalidate_search_inventory(document):
             del _search_inventory_cache[key]
 
 
+def _invalidate_pseudocode(document):
+    """Discard cached decompilation after an analysis annotation changes."""
+    document_id = id(document)
+    for key in list(_pseudocode_cache):
+        if key[0] == document_id:
+            del _pseudocode_cache[key]
+
+
+def _pseudocode(document, procedure):
+    """Reuse one provider decompilation for repeated bounded projections."""
+    key = (id(document), procedure.getEntryPoint())
+    if key not in _pseudocode_cache:
+        _pseudocode_cache[key] = procedure.decompile()
+    return _pseudocode_cache[key]
+
+
 def _search_inventory(document, kind):
     """Cache an immutable, address-sorted inventory for an unchanged document."""
     key = (id(document), kind)
     inventory = _search_inventory_cache.get(key)
     if inventory is None:
-        values = _procedure_map(document) if kind == "procedure" else _strings(document)
+        if kind == "procedure":
+            values = _procedure_map(document)
+        elif kind == "string":
+            values = _strings(document)
+        elif kind == "name":
+            values = {_hex(address): value for address, value in _name_map(document).items()}
+        else:
+            raise ValueError("Unknown inventory kind")
         inventory = tuple(sorted(values.items(), key=lambda item: int(item[0], 16)))
         _search_inventory_cache[key] = inventory
     return inventory
@@ -507,6 +623,22 @@ def _name_map(document):
     return result
 
 
+def _render_instruction(segment, address):
+    instruction = segment.getInstructionAtAddress(address)
+    if instruction is None:
+        return None
+    arguments = [
+        instruction.getFormattedArgument(index)
+        for index in range(instruction.getArgumentCount())
+    ]
+    suffix = ", ".join(value for value in arguments if value is not None)
+    return "%s: %s%s" % (
+        _hex(address),
+        instruction.getInstructionString(),
+        (" " + suffix) if suffix else "",
+    )
+
+
 def _assembly(procedure, limit=None):
     """Render bounded assembly while guarding against malformed instruction cycles."""
     lines = []
@@ -520,9 +652,9 @@ def _assembly(procedure, limit=None):
             instruction = segment.getInstructionAtAddress(address)
             if instruction is None:
                 break
-            arguments = [instruction.getFormattedArgument(index) for index in range(instruction.getArgumentCount())]
-            suffix = ", ".join(value for value in arguments if value is not None)
-            lines.append("%s: %s%s" % (_hex(address), instruction.getInstructionString(), (" " + suffix) if suffix else ""))
+            line = _render_instruction(segment, address)
+            if line is not None:
+                lines.append(line)
             if limit is not None and len(lines) >= limit:
                 return "\n".join(lines)
             length = instruction.getInstructionLength()
@@ -532,6 +664,45 @@ def _assembly(procedure, limit=None):
     return "\n".join(lines)
 
 
+def _read_function_instructions(document, params):
+    """Read one bounded raw-instruction window without invoking decompilation."""
+    procedure = _procedure(document, params.get("procedure"))
+    offset = _offset(params, "offset")
+    limit = params.get("limit", 64)
+    if offset > 100000:
+        raise ValueError("offset must not exceed 100000")
+    if not isinstance(limit, int) or isinstance(limit, bool) or limit < 1 or limit > 500:
+        raise ValueError("limit must be an integer between 1 and 500")
+    addresses, scan_truncated = _instruction_addresses(
+        procedure, offset + limit + 1
+    )
+    start = min(offset, len(addresses))
+    end = min(len(addresses), start + limit)
+    segment = procedure.getSegment()
+    items = []
+    for address in addresses[start:end]:
+        line = _render_instruction(segment, address)
+        if line is not None:
+            items.append(line)
+    has_more = scan_truncated or end < len(addresses)
+    return {
+        "procedure": _procedure_identity(procedure),
+        "instructions": {
+            "items": items,
+            "total": None if scan_truncated else len(addresses),
+            "returned": len(items),
+            "truncated": has_more,
+            "next_offset": end if has_more else None,
+        },
+        "instructions_scanned": len(addresses),
+        "instruction_scan_truncated": scan_truncated,
+        "limitations": [
+            "Instruction text and ordering are Hopper-specific representations.",
+            "The fast path does not decompile the procedure or scan whole-program names and strings.",
+        ],
+    }
+
+
 def _analyze_function(document, params):
     """Collect a bounded, single-pass function dossier for agent callers."""
     procedure = _procedure(document, params.get("procedure"))
@@ -560,8 +731,8 @@ def _analyze_function(document, params):
             "end": _hex(block.getEndingAddress()),
             "successors": sorted(set(successors), key=lambda value: int(value, 16)),
         })
-    pseudo = procedure.decompile() or ""
-    assembly_lines = _assembly(procedure).splitlines() if params.get("include_assembly", False) else []
+    pseudo = _pseudocode(document, procedure) or ""
+    assembly_lines = _assembly(procedure, max_instructions).splitlines() if params.get("include_assembly", False) else []
     callers = sorted((_procedure_identity(item) for item in procedure.getAllCallerProcedures()), key=lambda item: int(item["address"], 16))
     callees = sorted((_procedure_identity(item) for item in procedure.getAllCalleeProcedures()), key=lambda item: int(item["address"], 16))
     comments = []
@@ -595,8 +766,14 @@ def _analyze_function(document, params):
             incoming.append(item)
         if source in procedure_addresses:
             outgoing.append(item)
-    string_map = {int(address, 16): value for address, value in _strings(document).items()}
-    name_map = _name_map(document)
+    string_map = {
+        int(address, 16): value
+        for address, value in _search_inventory(document, "string")
+    }
+    name_map = {
+        int(address, 16): value
+        for address, value in _search_inventory(document, "name")
+    }
     referenced_strings = []
     referenced_names = []
     for edge in outgoing:
@@ -615,7 +792,13 @@ def _analyze_function(document, params):
     return {
         "procedure": {"address": _hex(procedure.getEntryPoint()), "name": _procedure_name(procedure), "classification": None, "signature": procedure.signatureString(), "locals": _procedure_locals(procedure)},
         "pseudocode": {"text": pseudo_text, "total_chars": len(pseudo), "returned_chars": len(pseudo_text), "truncated": pseudo_next < len(pseudo), "next_offset": pseudo_next if pseudo_next < len(pseudo) else None},
-        "assembly": _bounded(assembly_lines, assembly_offset, max_instructions),
+        "assembly": _bounded(
+            assembly_lines,
+            assembly_offset,
+            max_instructions,
+            None,
+            instruction_scan_truncated if params.get("include_assembly", False) else False,
+        ),
         "comments": collection("comments", comments, instruction_scan_truncated),
         "callers": collection("callers", callers), "callees": collection("callees", callees),
         "incoming_references": collection("incoming_references", incoming, instruction_scan_truncated),
@@ -671,9 +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)
@@ -740,19 +968,16 @@ def _dispatch(method, params):
             })
         return result
     if method == "list_procedures":
-        return _page(_procedure_map(document), params.get("offset", 0), params.get("limit", 100))
+        return _page(dict(_search_inventory(document, "procedure")), params.get("offset", 0), params.get("limit", 100))
     if method == "list_strings":
-        values = _strings(document)
+        values = dict(_search_inventory(document, "string"))
         requested = params.get("address")
         if requested is not None:
             key = _hex(_address(document, requested))
             values = {key: values[key]} if key in values else {}
         return _page(values, params.get("offset", 0), params.get("limit", 100))
     if method == "list_names":
-        result = {}
-        for segment in document.getSegmentsList():
-            for item in segment.getNamedAddresses():
-                result[_hex(item)] = segment.getNameAtAddress(item)
+        result = dict(_search_inventory(document, "name"))
         requested = params.get("address")
         if requested is not None:
             key = _hex(_address(document, requested))
@@ -768,7 +993,7 @@ def _dispatch(method, params):
         if method == "procedure_assembly":
             return _assembly(procedure)
         if method == "procedure_pseudo_code":
-            return procedure.decompile()
+            return _pseudocode(document, procedure)
         if method == "procedure_callers":
             return sorted((_hex(item.getEntryPoint()) for item in procedure.getAllCallerProcedures()), key=lambda value: int(value, 16))
         if method == "procedure_callees":
@@ -779,12 +1004,18 @@ def _dispatch(method, params):
             return {"name": _procedure_name(procedure), "entrypoint": _hex(procedure.getEntryPoint()), "basicblock_count": procedure.getBasicBlockCount(), "length": length, "signature": procedure.signatureString(), "locals": _procedure_locals(procedure), "classification": None}
     if method == "set_address_name":
         address = _address(document, params.get("address"))
-        result = document.setNameAtAddress(address, params["name"])
-        _invalidate_search_inventory(document)
+        try:
+            result = document.setNameAtAddress(address, params["name"])
+        finally:
+            _invalidate_search_inventory(document)
+            _invalidate_pseudocode(document)
         return result
     if method == "set_addresses_names":
-        result = {key: document.setNameAtAddress(_address(document, key), value) for key, value in params["names"].items()}
-        _invalidate_search_inventory(document)
+        try:
+            result = {key: document.setNameAtAddress(_address(document, key), value) for key, value in params["names"].items()}
+        finally:
+            _invalidate_search_inventory(document)
+            _invalidate_pseudocode(document)
         return result
     if method in ("set_comment", "set_inline_comment"):
         address = _address(document, params.get("address"))
@@ -792,6 +1023,7 @@ def _dispatch(method, params):
         setter = segment.setCommentAtAddress if method == "set_comment" else segment.setInlineCommentAtAddress
         getter = segment.getCommentAtAddress if method == "set_comment" else segment.getInlineCommentAtAddress
         setter(address, params["comment"])
+        _invalidate_pseudocode(document)
         return getter(address) == params["comment"]
     if method == "list_bookmarks":
         return [{"address": _hex(item), "name": document.getBookmarkName(item)} for item in document.getBookmarks()]
@@ -814,30 +1046,68 @@ def _serve_connection(connection):
         if not line or len(line) > MAX_LINE_BYTES:
             break
         request_id = None
+        authenticated = False
         should_stop = False
         try:
             request = json.loads(line.decode("utf-8"))
             if set(request) != {"id", "token", "method", "params"}:
                 raise ValueError("Invalid bridge request shape")
             request_id = request["id"]
+            if isinstance(request_id, bool) or not isinstance(request_id, int) or request_id < 0:
+                raise ValueError("Invalid bridge request id")
             if not isinstance(request["token"], str) or not hmac.compare_digest(request["token"], REA_TOKEN):
                 raise PermissionError("Invalid bridge capability")
+            authenticated = True
+            _write_message(file, {"id": request_id, "event": {
+                "type": "progress",
+                "phase": "hopper_bridge",
+                "completed": 0,
+                "total": 1,
+                "message": "Hopper bridge started request",
+            }})
             result = _dispatch(request["method"], request["params"])
             should_stop = request["method"] == "shutdown_document" or (
                 request["method"] == "shutdown" and not result.get("cleanup_required", False)
             )
-            response = {"id": request_id, "result": _json_safe(result)}
+            safe_result = _json_safe(result)
+            _write_message(file, {"id": request_id, "event": {
+                "type": "progress",
+                "phase": "hopper_bridge",
+                "completed": 1,
+                "total": 1,
+                "message": "Hopper bridge completed request",
+                "terminal": True,
+            }})
+            response = {"id": request_id, "result": safe_result}
         except Exception as error:
-            response = {"id": request_id if isinstance(request_id, int) else 0, "error": {"code": -32000, "message": str(error)[:512], "type": _diagnostic_type(error)}}
-        file.write((json.dumps(response, separators=(",", ":")) + "\n").encode("utf-8"))
-        file.flush()
+            diagnostic = _safe_diagnostic(error)
+            if authenticated:
+                _write_message(file, {"id": request_id, "event": {
+                    "type": "diagnostic",
+                    "error": diagnostic,
+                }})
+            response_id = request_id if (
+                isinstance(request_id, int)
+                and not isinstance(request_id, bool)
+                and request_id >= 0
+            ) else 0
+            response = {"id": response_id, "error": diagnostic}
+        _write_message(file, response)
         if should_stop:
             break
     file.close()
     connection.close()
 
 
+def _write_message(file, message):
+    """Write and flush one compact bridge message."""
+    file.write((json.dumps(message, separators=(",", ":")) + "\n").encode("utf-8"))
+    file.flush()
+
+
 def _diagnostic_type(error):
+    if isinstance(error, CapabilityUnavailableError):
+        return "capability_unavailable"
     if isinstance(error, PermissionError):
         return "authorization"
     if isinstance(error, (ValueError, TypeError, KeyError)):
@@ -845,6 +1115,20 @@ def _diagnostic_type(error):
     return "bridge_exception"
 
 
+def _safe_diagnostic(error):
+    """Project one exception without retaining provider or credential text."""
+    diagnostic_type = _diagnostic_type(error)
+    if diagnostic_type == "capability_unavailable":
+        message = str(error)[:512]
+    elif diagnostic_type == "authorization":
+        message = "Invalid bridge capability"
+    elif diagnostic_type == "invalid_request":
+        message = "Invalid Hopper bridge request"
+    else:
+        message = "%s: Hopper bridge operation failed" % type(error).__name__[:128]
+    return {"code": -32000, "message": message, "type": diagnostic_type}
+
+
 def _run():
     """Own a permission-restricted, single-client Unix socket for this bridge."""
     if os.path.exists(REA_SOCKET):
@@ -864,4 +1148,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()

package/dist/application/AnalysisClientCleanup.js

@@ -0,0 +1,14 @@
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+/** Close one provider client and normalize unexpected adapter rejection. */
+export const closeAnalysisClient = async (client, providerId, options = {}) => {
+    try {
+        if (client.closeWithOutcome !== undefined)
+            return await client.closeWithOutcome(options);
+        await client.close();
+        return ok(null);
+    }
+    catch (cause) {
+        return err(new ProviderCleanupError(providerId, ["provider-client"], { reason: "provider client close rejected unexpectedly" }, { cause }));
+    }
+};

package/dist/application/AnalysisContextQueries.js

@@ -0,0 +1,130 @@
+import { AnalysisOutputError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+const parameters = (document, address) => ({
+    ...(document === undefined ? {} : { document }),
+    ...(address === undefined ? {} : { address }),
+});
+const executionOptions = (signal) => signal === undefined ? {} : { signal };
+/** Compose the provider's volatile selection state into one coherent query. */
+export const getNavigationContext = async (analysis, input, signal) => {
+    const document = input.document ??
+        (await analysis.execute("current_document", {}, executionOptions(signal)));
+    if (typeof document !== "string" && !document.ok)
+        return document;
+    const documentName = typeof document === "string" ? document : document.value.result;
+    const documentArgs = typeof documentName === "string" ? parameters(documentName) : {};
+    const address = await analysis.execute("current_address", documentArgs, executionOptions(signal));
+    if (!address.ok)
+        return address;
+    if (typeof address.value.result !== "string")
+        return ok({
+            document: documentName,
+            address: address.value.result,
+            procedure: null,
+        });
+    const procedure = await analysis.execute("resolve_containing_procedure", parameters(typeof documentName === "string" ? documentName : undefined, address.value.result), executionOptions(signal));
+    if (!procedure.ok) {
+        if (!isMissingCurrentProcedure(procedure.error))
+            return procedure;
+        return ok({
+            document: documentName,
+            address: address.value.result,
+            procedure: null,
+        });
+    }
+    return ok({
+        document: documentName,
+        address: address.value.result,
+        procedure: containingProcedureName(procedure.value.result),
+    });
+};
+/** Inspect bounded provider-neutral facets at one explicit reproducible address. */
+export const inspectAddressContext = async (analysis, input, signal) => {
+    const document = await resolveDocument(analysis, input.document, signal);
+    if (!document.ok)
+        return document;
+    const args = parameters(document.value, input.address);
+    const operations = [
+        "address_name",
+        "resolve_containing_procedure",
+        "comment",
+        "inline_comment",
+        "list_bookmarks",
+    ];
+    const results = await Promise.all(operations.map((operation) => analysis.execute(operation, operation === "list_bookmarks" ? parameters(document.value) : args, executionOptions(signal))));
+    for (const result of results) {
+        if (!result.ok && isRequestLevelFailure(result.error))
+            return result;
+    }
+    const name = facet(results[0], operations[0]);
+    const procedure = facet(results[1], operations[1]);
+    const comment = facet(results[2], operations[2]);
+    const inlineComment = facet(results[3], operations[3]);
+    const bookmarks = facet(results[4], operations[4]);
+    return ok({
+        address: input.address,
+        document: document.value,
+        name,
+        procedure,
+        comment,
+        inline_comment: inlineComment,
+        bookmarks: bookmarks.state === "available"
+            ? {
+                state: "available",
+                value: matchingBookmarks(bookmarks.value, resolvedAddress(results[1], input.address)),
+            }
+            : bookmarks,
+    });
+};
+const resolveDocument = async (analysis, document, signal) => {
+    if (document !== undefined)
+        return ok(document);
+    const current = await analysis.execute("current_document", {}, executionOptions(signal));
+    if (!current.ok)
+        return current;
+    return typeof current.value.result === "string"
+        ? ok(current.value.result)
+        : err(new AnalysisOutputError("current_document", "expected a document identity string"));
+};
+const facet = (result, operation) => result?.ok === true
+    ? { state: "available", value: result.value.result }
+    : {
+        state: "unavailable",
+        reason: result?.error.message ?? `${operation} returned no result`,
+        remediation: `Call ${operation} directly to inspect provider availability and diagnostics.`,
+    };
+const isMissingCurrentProcedure = (error) => /(?:no procedure exists|not in a procedure)/iu.test(error.message);
+const isRequestLevelFailure = (error) => error._tag === "AnalysisCancelledError" ||
+    error._tag === "AnalysisTimeoutError" ||
+    error._tag === "NoBinaryOpenError" ||
+    error._tag === "PermissionRequiredError";
+const containingProcedureName = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    if (value.found !== true)
+        return null;
+    const procedure = value.procedure;
+    if (typeof procedure !== "object" ||
+        procedure === null ||
+        Array.isArray(procedure))
+        return null;
+    return typeof procedure.name === "string" ? procedure.name : null;
+};
+const resolvedAddress = (result, fallback) => {
+    if (result?.ok !== true)
+        return fallback;
+    const value = result.value.result;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return fallback;
+    return typeof value.query_address === "string"
+        ? value.query_address
+        : fallback;
+};
+const matchingBookmarks = (value, address) => {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((bookmark) => typeof bookmark === "object" &&
+        bookmark !== null &&
+        !Array.isArray(bookmark) &&
+        bookmark.address === address);
+};

package/dist/application/AnalysisSnapshotCache.js

@@ -1,7 +1,7 @@
 import { EvidenceIntegrityError, NoBinaryOpenError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { analysisQueryId, createAnalysisSnapshotEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
-import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 const STATEFUL_OPERATIONS = new Set([
     "health",
     "current_address",
@@ -19,7 +19,9 @@ const CURSOR_DEFAULT_OPERATIONS = new Set([
     "prev_address",
     "xrefs",
 ]);
-const DOCUMENT_SCOPED_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name).filter((name) => name !== "current_document" &&
+const DOCUMENT_SCOPED_OPERATIONS = new Set(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy")
+    .map(({ name }) => name)
+    .filter((name) => name !== "current_document" &&
     name !== "list_documents" &&
     name !== "set_current_document"));
 /** Whether an operation is immutable and independent of provider UI state. */