feat: add relocation/rebasing tools for runtime-vs-static address mapping

[12UE]

Summary

Implements #449 ? adds relocation/rebasing tools for runtime-vs-static address mapping, enabling hybrid dynamic+static analysis with debuggers (x64dbg, x32dbg, WinDbg).

New Tools

Tool	Description
calculate_relocation_delta	Compute the signed delta between IDA's imagebase and a runtime base (read-only)
convert_ida_to_runtime	Convert an IDA static address to its runtime equivalent (supports symbol names)
convert_runtime_to_ida	Convert a runtime address back to an IDA static address (includes context)
set_relocation_base	Permanently rebase the IDB to match a runtime base (destructive, @idasync)

Design Decisions

• Tools 1-3 are NOT @idasync ? they don't modify IDA state and can run without the main thread lock
• set_relocation_base IS @idasync ? it mutates the entire IDB via idaapi.rebase_program()
• Error handling follows existing patterns ? returns structured TypedDict dicts instead of raising exceptions
• Address resolution is flexible ? convert_ida_to_runtime accepts both hex addresses and symbol names via parse_address()
• Context enrichment is best-effort ? the references field in conversion results is populated when possible but never blocks on failure

Integration

One import added to __init__.py:

`python
from . import api_relocation
``n
Zero changes to existing APIs. Fully backward compatible.

Checklist

• Works in both GUI and headless (idalib-mcp) modes
• No new dependencies
• Matches existing code style (TypedDict results, @tool + @idasync decorators, Annotated parameters)
• Backward compatible

Closes #449

[12UE]

Relationship with existing get_runtime_address_info

For clarity, here's how the new tools relate to the existing get_runtime_address_info:

	get_runtime_address_info	New tools
Direction	Runtime to IDA only	Both directions (IDA to Runtime and back)
Granularity	High-level, returns rich context (function name, xrefs, etc.)	Atomic / single-purpose operations
Use case	"Tell me everything about this runtime address"	Lightweight address arithmetic, batch conversions, rebasing
Mutates IDB	No	Only set_relocation_base does

In short, get_runtime_address_info is a convenience tool for exploration, while the new tools provide the building blocks for programmatic workflows (e.g., scripting breakpoint lists, bulk address translation, or permanently syncing the IDB with a debugger session).

They complement rather than replace each other.

[12UE]

Self-review: Known Limitations

After reviewing my own code, here are a few minor points I'd like to flag for transparency:

1. Error reporting in result dicts

When address parsing fails (e.g. invalid hex input), the tools return a zeroed result (output_address: "0x0") without an explicit error field. This means callers must infer failure from the zero address rather than a clear error indicator.

Potential improvement:

class AddressConversionResult(TypedDict):
    ...
    error: NotRequired[str]  # populated only on failure

2. Silent fallback in calculate_relocation_delta

The except ValueError branch returns a structurally valid but semantically empty result. The comment says "error case handled by MCP framework", but no error signal is actually propagated.

3. Broad exception handling

convert_ida_to_runtime uses except Exception to catch parse_address failures before falling back to get_name_ea. This is intentionally broad to handle the various ways IDA's API can fail, but worth noting.

---

None of these affect correctness in normal usage — they only matter for edge cases with malformed input. Happy to address any of these if you'd prefer explicit error fields.