jdbg: Instructions file for Codex

AGENTS.md — java-agent-debugger (jdbg)

Coding charter for AI agents working in this repo. Rules and constraints only. For architecture, module layout, command/tool surface, output schema, dependencies, and status, read DESIGN.md (the factual design-and-implementation reference). This file does NOT duplicate it.

What this project is (one paragraph)

jdbg is a cross-platform Rust CLI (binary jdbg, crate java-agent-debugger, edition 2024) that lets an AI agent debug Java interactively through the JDK's jdb compatibility backend plus an optional Java JDI sidecar backend — prompt-aware (never sleep-based), stateful (a background daemon keeps sessions alive across calls), Windows-first. It is consumed two ways: the CLI and an MCP server (jdbg __mcp, native tool calls for Claude Code, Codex, and OpenCode). Full detail in DESIGN.md.

Binding constraints (do not violate without asking)

These are settled decisions. Changing them needs explicit user sign-off.

• Keep blocking boundaries where they are settled. The existing jdb engine, daemon registry, daemon IPC, and per-session command locking remain std::thread + channels + blocking IO unless explicitly redesigned. tokio is allowed for rmcp MCP serving and the JDI sidecar transport/lifecycle subsystem.
• No temp files, no shell, no sleeps. Commands are written straight to jdb's stdin. Readiness is detected by reading until the prompt, never by sleeping. There is no shell involved anywhere (no injection surface).
• Minimal dependencies. Do not add a crate when std suffices. rmcp is allowed only for MCP protocol/tool serving, not daemon IPC or debugger backend RPC. Deliberately excluded: once_cell, nix, daemonize, portable-pty/conpty, any broad TCP/RPC framework, any windows/winapi crate (use std raw FFI for the few Win32 calls). Use std::sync::LazyLock for one-time regex compilation and std::os::* for platform bits.
• Keep Java sidecar dependencies isolated. Java-only expression/evaluation dependencies belong in sidecar/jdi and are packaged into the Gradle fat jar jdbg-jdi-sidecar.jar. Do not add a Rust RPC framework or Rust JDWP stack for sidecar work unless the user explicitly approves that redesign.
• One daemon per user; one in-flight command per session. The per-session command Mutex is held across write+wait — jdb is line-oriented and cannot interleave commands. Different sessions run in parallel.
• The daemon is the single writer of the on-disk registry (atomic temp-in-same-dir + rename). The CLI only reads it (offline fallback). The in-memory session map is the source of truth while the daemon is alive.
• Keep modules small and single-purpose. If a file grows large it is doing too much — split it.
• Use English for code comments and commit messages. Source/test comments, Rustdoc, git commit messages, and PR/review comments written for the project history should be in English.