server-re/AGENTS.md

# AGENTS.md

## Project overview

Reverse-engineering project for the Rusty Hearts game server/client binaries
(Windows PE32+ x86-64). Analysis is performed with **Ghidra** (headless or GUI)
driven through **REA** (`reverse-engineer-anything` skill + `rea-agents` MCP
server). There is no application source code here — the binaries are the
primary evidence.

The server binaries are **C++** (MSVC 2010, x64). See
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the evidence and what is known
about their structure.
All servers share one in-house framework (`Magi*`): server-kind enum,
startup modes, XML option files and DB access via DBC servers. See
[`docs/SHARED_FRAMEWORK.md`](docs/SHARED_FRAMEWORK.md) and check each new
binary against it instead of re-deriving it.
Config file definitions: [`docs/CONFIG.md`](docs/CONFIG.md). Database access
path, RMI→stored-procedure map and schema: [`docs/DATABASE.md`](docs/DATABASE.md)
(catalog dump in `decomp/schema/`, regenerate with `decomp/scripts/dump_schema.sh`).

## Target runtime environment

The analyzed binaries are expected to run in the following environment. Use
this when interpreting imports, API usage, and database access in decompiled
code.

- **OS**: Windows Server — exact version unknown; assume **2008 or 2012**.
- **Runtime dependencies** (winetricks-style identifiers):
  - `dotnet7` — .NET 7 runtime
  - `dotnetdesktop7` — .NET 7 Desktop runtime
  - `vcrun2010` — Visual C++ 2010 redistributable
  - `d3dx9` — DirectX 9 D3DX libraries
  - `d3dx10` — DirectX 10 D3DX libraries
- **Database**: Microsoft SQL Server, supported up to **SQL Server 2019**.
  Schema files for the backing databases are in `schema/`. Note: the shipped
  `.mdf` files are in SQL Server 2022 format (db version 957) and only attach
  to 2022+.

## Directory layout

| Path | Contents | Mutability |
|------|----------|------------|
| `binaries/` | Original shipped binaries: server EXEs (`GameServer_Release_USA_x64.exe`, `DungeonServer_...`, etc.), DLLs, and game data (maps, Lua scripts, tables, item/character assets) | **Read-only.** Never modify, move, or delete. Gitignored. |
| `schema/` | SQL Server database schema/log files (`.mdf` / `.ldf`) for `RustyHearts`, `RustyHearts_Account`, `RustyHearts_Auth`, `RustyHearts_Log`, `GMRustyHearts` | **Read-only.** Never modify. Gitignored. |
| `decomp/` | Raw decompilation objects exported from Ghidra/REA (pseudocode, listings, function metadata) | Derived output. Regenerable; created on demand. |
| `.agents/skills/` | Installed agent skills, notably `reverse-engineer-anything` (REA) | Agent configuration. |
| `src/` | Linux C++ reconstructions of analysed binaries (Meson; one sub-folder per binary, e.g. `agent_release/`). Build: `cd src && meson setup build && ninja -C build` | Hand-written; cite decomp addresses; `src/build/` is gitignored. |
| `docs/` | Project documentation, e.g. `ARCHITECTURE.md` (language/toolchain, libraries, code conventions) | Hand-maintained; update as findings are confirmed. |
| `third-party/` | Upstream sources/headers matched to the shipped support DLLs (OpenSSL 1.0.0d, curl 7.21.4, BugTrap ~1.3, mingw-w64 `dbghelp.h`, TinyXML 2.5.x) | Reference only, not build inputs. Do not edit upstream files; record provenance changes in the doc below. |

**Third-party libraries:** see [`third-party/README.md`](third-party/README.md)
for each support DLL's observed version, matched source and checksums, match
quality (exact vs. closest), libraries with no public source, and acquisition
routes. Consult it before decompiling any support DLL, and use the matched
headers for symbol/struct recovery instead of re-deriving known APIs.
The servers also statically link **ProudNet** (Nettention, proprietary). Its
headers live only in gitignored `third-party/_local/`; never commit them or any
other licence-restricted vendor files.

## Tooling

- **Ghidra**: installed at `/opt/ghidra`; headless entrypoint
  `/opt/ghidra/support/analyzeHeadless`. `GHIDRA_INSTALL_DIR=/opt/ghidra`.
- **REA MCP**: registered in `opencode.json` via `npx -y rea-agents@6.5.0 mcp`
  with `GHIDRA_INSTALL_DIR` and `JAVA_HOME` set in its environment.
- **Runtime versions**: managed by `mise.toml` — Java 21, Node 26.
- **REA skill**: `.agents/skills/reverse-engineer-anything/SKILL.md`. Read the
  relevant reference under `.agents/skills/reverse-engineer-anything/references/`
  before non-trivial workflows (native binaries → `native-and-artifacts.md`).

## Analysis workflow

The full reproducible procedure, with commands, is in
[`docs/WORKFLOW.md`](docs/WORKFLOW.md). Follow it for every binary. In summary:

1. Route the target first: native executables/libraries go through REA
   `open_binary` (never pass a Ghidra project file as the target — pass the
   original binary path under `binaries/`).
2. Work summary-first: `binary_overview` / summary detail before drilling into
   `analyze_function` or pseudocode. Reuse retained Evidence IDs instead of
   re-running identical analysis.
3. **Third-party libraries: every time one is discovered** (an imported DLL, a
   version string, RTTI class prefix, library error strings, or a PDB path),
   do the following before continuing analysis:
   - pin its version;
   - **search online for its source or headers** (official releases, git tags,
     vendor repos, clean-room equivalents);
   - download it into `third-party/`, or into the gitignored
     `third-party/_local/` if its licence forbids redistribution;
   - record it in `third-party/README.md`.

   If no source exists, record that and the acquisition routes. See
   `docs/WORKFLOW.md` §3.
4. Export raw decompilation artifacts (pseudocode, listings) into `decomp/`
   using per-binary subdirectories, e.g. `decomp/GameServer_Release_USA_x64/`.
   Keep filenames stable and function-address-based so results are reproducible.
   For full coverage, use the headless scripts in `decomp/scripts/`.
5. Track targets, artifact SHA-256 identities, and per-binary status in
   `decomp/INVENTORY.md`; keep a per-binary finding ledger in
   `decomp/<name>/evidence.md`.
6. Close the REA session (`close_binary`) when the investigation is complete.

## Evidence and claims

- Every conclusion must distinguish **observation** (from evidence),
  **inference**, and **unknown**. Cite Evidence IDs or `file:line`-style
  references to decomp output.
- Static analysis never establishes runtime behavior — say so explicitly.
- Do not infer behavior from filenames, strings, or binary layout alone;
  corroborate with decompilation or data from `schema/`.
- Keep a finding ledger for multi-step investigations (conclusion → evidence →
  remaining gaps).

## Ground rules

- Treat `binaries/` and `schema/` as immutable inputs; all outputs go to
  `decomp/` or a new file, never beside the originals.
- Do not install Ghidra, Java, Node, or REA prerequisites ad hoc — they are
  provisioned via `mise.toml` and `/opt/ghidra`; repair configuration instead.
- Version-pin REA at `rea-agents@6.5.0` as declared in `opencode.json`.
- Do not add npm `devEngines`/`packageManager` constraints to `package.json` —
  they make `npx` exit `EBADDEVENGINES` in this directory and break the REA MCP
  launch (this happened once; `devEngines` was removed).
- Keep the REA registration **project-local**: `opencode.json` in this repo is
  the source of truth. Do not write global client config
  (`~/.config/opencode/…`) or run `rea setup` against global paths —
  `rea doctor` may report global registration drift; that is accepted here.
- When tooling is missing or an MCP call is blocked, diagnose the specific
  blocker (registration vs. restart vs. provider) rather than re-running setup
  wholesale — see the REA skill's connection-and-recovery reference.