apdb 0.1.0__tar.gz

apdb-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, apdb contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

apdb-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: apdb
+Version: 0.1.0
+Summary: Agent-friendly remote Python debugger over a zero-dependency TCP API
+Author: apdb contributors
+License-Expression: BSD-2-Clause
+Keywords: debugger,pdb,agent,tcp,remote-debugger
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# apdb
+
+`apdb` is an agent-friendly Python debugger inspired by `remote-pdb`.
+It keeps the Python call site close to `pdb`, but exposes debugger control over
+a newline-delimited JSON TCP API instead of a human interactive shell.
+
+The runtime and CLI use only the Python standard library.
+
+## Python API
+
+```python
+import apdb
+
+answer = 41
+apdb.set_trace(port=4444)
+print(answer + 1)
+```
+
+`set_trace()` blocks the target process whether or not a client is connected.
+The process resumes only after the TCP API receives a release command such as
+`continue`, `next`, `step`, or `quit`.
+
+By default, `apdb` binds to `127.0.0.1` and uses no authentication:
+
+```python
+apdb.set_trace(port=4444, host="127.0.0.1")
+```
+
+## CLI
+
+The package installs `apdb_cli`:
+
+```bash
+apdb_cli ping --port 4444
+apdb_cli state --port 4444
+apdb_cli where --port 4444
+apdb_cli locals --port 4444
+apdb_cli eval 'answer + 1' --port 4444
+apdb_cli next --port 4444
+apdb_cli step --port 4444
+apdb_cli continue --port 4444
+```
+
+The CLI prints one JSON response to stdout and exits nonzero for connection
+failures or API errors.
+
+## TCP API
+
+The TCP API speaks newline-delimited JSON. Each request and response is one JSON
+object followed by `\n`.
+
+Request:
+
+```json
+{"id": 1, "cmd": "state"}
+```
+
+Response:
+
+```json
+{"id": 1, "ok": true, "result": {"status": "paused"}}
+```
+
+Supported v0 commands:
+
+- `ping`
+- `state`
+- `where`
+- `locals`
+- `eval`
+- `next`
+- `step`
+- `continue`
+- `quit`
+
+## Security
+
+`apdb` has no authentication in v0. Debugger access can inspect and evaluate
+code inside the target process. Bind to `127.0.0.1` unless you explicitly want
+to expose that control surface.

apdb-0.1.0/README.md

@@ -0,0 +1,80 @@
+# apdb
+
+`apdb` is an agent-friendly Python debugger inspired by `remote-pdb`.
+It keeps the Python call site close to `pdb`, but exposes debugger control over
+a newline-delimited JSON TCP API instead of a human interactive shell.
+
+The runtime and CLI use only the Python standard library.
+
+## Python API
+
+```python
+import apdb
+
+answer = 41
+apdb.set_trace(port=4444)
+print(answer + 1)
+```
+
+`set_trace()` blocks the target process whether or not a client is connected.
+The process resumes only after the TCP API receives a release command such as
+`continue`, `next`, `step`, or `quit`.
+
+By default, `apdb` binds to `127.0.0.1` and uses no authentication:
+
+```python
+apdb.set_trace(port=4444, host="127.0.0.1")
+```
+
+## CLI
+
+The package installs `apdb_cli`:
+
+```bash
+apdb_cli ping --port 4444
+apdb_cli state --port 4444
+apdb_cli where --port 4444
+apdb_cli locals --port 4444
+apdb_cli eval 'answer + 1' --port 4444
+apdb_cli next --port 4444
+apdb_cli step --port 4444
+apdb_cli continue --port 4444
+```
+
+The CLI prints one JSON response to stdout and exits nonzero for connection
+failures or API errors.
+
+## TCP API
+
+The TCP API speaks newline-delimited JSON. Each request and response is one JSON
+object followed by `\n`.
+
+Request:
+
+```json
+{"id": 1, "cmd": "state"}
+```
+
+Response:
+
+```json
+{"id": 1, "ok": true, "result": {"status": "paused"}}
+```
+
+Supported v0 commands:
+
+- `ping`
+- `state`
+- `where`
+- `locals`
+- `eval`
+- `next`
+- `step`
+- `continue`
+- `quit`
+
+## Security
+
+`apdb` has no authentication in v0. Debugger access can inspect and evaluate
+code inside the target process. Bind to `127.0.0.1` unless you explicitly want
+to expose that control surface.

apdb-0.1.0/apdb/__init__.py

@@ -0,0 +1,5 @@
+from .debugger import APDBError, AgentPdbSession, set_trace
+
+__version__ = "0.1.0"
+
+__all__ = ["APDBError", "AgentPdbSession", "__version__", "set_trace"]

apdb-0.1.0/apdb/cli.py

@@ -0,0 +1,57 @@
+import argparse
+import json
+import socket
+import sys
+
+from .protocol import dumps_response, loads_json_line
+
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_TIMEOUT = 2.0
+
+
+def build_parser():
+    shared = argparse.ArgumentParser(add_help=False)
+    shared.add_argument("--host", default=DEFAULT_HOST)
+    shared.add_argument("--port", type=int, required=True)
+    shared.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT)
+
+    parser = argparse.ArgumentParser(prog="apdb_cli")
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+    for name in ("ping", "state", "where", "locals", "next", "step", "continue", "quit"):
+        subparsers.add_parser(name, parents=[shared])
+
+    eval_parser = subparsers.add_parser("eval", parents=[shared])
+    eval_parser.add_argument("expr")
+    return parser
+
+
+def make_request(args):
+    request = {"id": 1, "cmd": args.cmd}
+    if args.cmd == "eval":
+        request["expr"] = args.expr
+    return request
+
+
+def send_command(host, port, request, timeout=DEFAULT_TIMEOUT):
+    with socket.create_connection((host, port), timeout=timeout) as sock:
+        sock.sendall(dumps_response(request))
+        with sock.makefile("rb") as reader:
+            return loads_json_line(reader.readline())
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        response = send_command(args.host, args.port, make_request(args), args.timeout)
+    except OSError as exc:
+        print(f"connection failed: {exc}", file=sys.stderr)
+        return 2
+
+    print(json.dumps(response, sort_keys=True))
+    return 0 if response.get("ok") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

apdb-0.1.0/apdb/debugger.py

@@ -0,0 +1,194 @@
+import bdb
+import linecache
+import sys
+import threading
+
+from .protocol import error_response, ok_response
+from .server import APDBTCPServer
+
+
+RELEASE_COMMANDS = {"continue", "next", "step", "quit"}
+
+
+class APDBError(RuntimeError):
+    pass
+
+
+class AgentPdbSession:
+    def __init__(self, host, port, header=None):
+        self.host = host
+        self.port = port
+        self.header = header
+        self._condition = threading.Condition()
+        self._release_event = threading.Event()
+        self._server = None
+        self._server_thread = None
+        self._current_frame = None
+        self._current_action = None
+        self._done = False
+        self._paused = False
+        self._trace_mode = None
+        self._next_frame = None
+
+    def start(self):
+        try:
+            self._server = APDBTCPServer((self.host, self.port), self)
+        except OSError as exc:
+            raise APDBError(f"could not start apdb server on {self.host}:{self.port}: {exc}") from exc
+
+        self._server_thread = threading.Thread(
+            target=self._server.serve_forever,
+            name=f"apdb:{self.host}:{self.port}",
+            daemon=True,
+        )
+        self._server_thread.start()
+
+    def close(self):
+        self._done = True
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            self._server = None
+
+    def pause(self, frame):
+        with self._condition:
+            self._current_frame = frame
+            self._current_action = None
+            self._paused = True
+            self._release_event.clear()
+            self._condition.notify_all()
+
+        self._release_event.wait()
+
+        with self._condition:
+            self._paused = False
+            return self._current_action
+
+    def handle_request(self, request):
+        cmd = request["cmd"]
+        try:
+            if cmd == "ping":
+                return ok_response(request, {"status": "online"})
+            if cmd == "state":
+                return ok_response(request, self._state())
+            if cmd == "where":
+                return ok_response(request, {"frames": self._stack()})
+            if cmd == "locals":
+                return ok_response(request, self._locals())
+            if cmd == "eval":
+                return ok_response(request, self._eval(request.get("expr", "")))
+            if cmd in RELEASE_COMMANDS:
+                return self._release(request, cmd)
+            return error_response(request, "unknown_command", f"unknown command: {cmd}")
+        except Exception as exc:
+            return error_response(request, "command_error", f"{type(exc).__name__}: {exc}")
+
+    def trace_dispatch(self, frame, event, arg):
+        if self._done:
+            return None
+        if self._should_pause_for_trace(frame, event):
+            action = self.pause(frame)
+            return self._after_action(action, frame)
+        return self.trace_dispatch
+
+    def _release(self, request, action):
+        with self._condition:
+            self._current_action = action
+            self._release_event.set()
+        status = {
+            "continue": "continuing",
+            "next": "next",
+            "step": "step",
+            "quit": "quitting",
+        }[action]
+        return ok_response(request, {"status": status})
+
+    def _state(self):
+        frame = self._current_frame
+        result = {"status": "paused" if self._paused else "running"}
+        if frame is not None:
+            result.update(self._frame_info(frame, index=0))
+        return result
+
+    def _stack(self):
+        frames = []
+        frame = self._current_frame
+        index = 0
+        while frame is not None:
+            frames.append(self._frame_info(frame, index=index))
+            frame = frame.f_back
+            index += 1
+        return frames
+
+    def _locals(self):
+        frame = self._require_frame()
+        return {name: safe_repr(value) for name, value in sorted(frame.f_locals.items())}
+
+    def _eval(self, expr):
+        if not expr:
+            raise ValueError("eval command requires expr")
+        frame = self._require_frame()
+        value = eval(expr, frame.f_globals, frame.f_locals)
+        return {"repr": safe_repr(value), "type": type(value).__name__}
+
+    def _require_frame(self):
+        if self._current_frame is None:
+            raise RuntimeError("debugger is not paused at a frame")
+        return self._current_frame
+
+    def _frame_info(self, frame, index):
+        filename = frame.f_code.co_filename
+        line = linecache.getline(filename, frame.f_lineno).strip()
+        return {
+            "index": index,
+            "file": filename,
+            "line": frame.f_lineno,
+            "function": frame.f_code.co_name,
+            "code": line,
+        }
+
+    def _should_pause_for_trace(self, frame, event):
+        if event != "line":
+            return False
+        if self._trace_mode == "step":
+            return True
+        if self._trace_mode == "next":
+            return frame is self._next_frame
+        return False
+
+    def _after_action(self, action, frame):
+        if action == "continue":
+            self.close()
+            sys.settrace(None)
+            return None
+        if action == "quit":
+            self.close()
+            sys.settrace(None)
+            raise bdb.BdbQuit()
+        if action in {"next", "step"}:
+            self._trace_mode = action
+            self._next_frame = frame
+            frame.f_trace = self.trace_dispatch
+            sys.settrace(self.trace_dispatch)
+            return self.trace_dispatch
+        self.close()
+        sys.settrace(None)
+        return None
+
+
+def safe_repr(value):
+    try:
+        return repr(value)
+    except Exception:
+        return f"<unrepresentable {type(value).__name__}>"
+
+
+def set_trace(host="127.0.0.1", port=None, header=None):
+    if port is None:
+        raise TypeError("apdb.set_trace() missing required keyword argument: 'port'")
+
+    frame = sys._getframe().f_back
+    session = AgentPdbSession(host=host, port=port, header=header)
+    session.start()
+    action = session.pause(frame)
+    return session._after_action(action, frame)

apdb-0.1.0/apdb/protocol.py

@@ -0,0 +1,45 @@
+import json
+
+
+class ProtocolError(ValueError):
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def loads_request(line):
+    request = loads_json_line(line)
+    if not isinstance(request, dict):
+        raise ProtocolError("invalid_request", "request must be a JSON object")
+    if not request.get("cmd"):
+        raise ProtocolError("missing_command", "request must include cmd")
+    if not isinstance(request["cmd"], str):
+        raise ProtocolError("invalid_command", "cmd must be a string")
+    return request
+
+
+def loads_json_line(line):
+    try:
+        payload = json.loads(line.decode("utf-8"))
+    except UnicodeDecodeError as exc:
+        raise ProtocolError("invalid_encoding", str(exc)) from exc
+    except json.JSONDecodeError as exc:
+        raise ProtocolError("invalid_json", str(exc)) from exc
+    return payload
+
+
+def dumps_response(response):
+    return (json.dumps(response, sort_keys=True) + "\n").encode("utf-8")
+
+
+def ok_response(request, result):
+    return {"id": request.get("id"), "ok": True, "result": result}
+
+
+def error_response(request, code, message):
+    return {
+        "id": request.get("id"),
+        "ok": False,
+        "error": {"code": code, "message": message},
+    }

apdb-0.1.0/apdb/server.py

@@ -0,0 +1,24 @@
+import socketserver
+
+from .protocol import ProtocolError, dumps_response, error_response, loads_request
+
+
+class APDBRequestHandler(socketserver.StreamRequestHandler):
+    def handle(self):
+        line = self.rfile.readline()
+        try:
+            request = loads_request(line)
+        except ProtocolError as exc:
+            response = error_response({"id": None}, exc.code, exc.message)
+        else:
+            response = self.server.session.handle_request(request)
+        self.wfile.write(dumps_response(response))
+
+
+class APDBTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
+    allow_reuse_address = True
+    daemon_threads = True
+
+    def __init__(self, server_address, session):
+        self.session = session
+        super().__init__(server_address, APDBRequestHandler)

apdb-0.1.0/apdb.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: apdb
+Version: 0.1.0
+Summary: Agent-friendly remote Python debugger over a zero-dependency TCP API
+Author: apdb contributors
+License-Expression: BSD-2-Clause
+Keywords: debugger,pdb,agent,tcp,remote-debugger
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# apdb
+
+`apdb` is an agent-friendly Python debugger inspired by `remote-pdb`.
+It keeps the Python call site close to `pdb`, but exposes debugger control over
+a newline-delimited JSON TCP API instead of a human interactive shell.
+
+The runtime and CLI use only the Python standard library.
+
+## Python API
+
+```python
+import apdb
+
+answer = 41
+apdb.set_trace(port=4444)
+print(answer + 1)
+```
+
+`set_trace()` blocks the target process whether or not a client is connected.
+The process resumes only after the TCP API receives a release command such as
+`continue`, `next`, `step`, or `quit`.
+
+By default, `apdb` binds to `127.0.0.1` and uses no authentication:
+
+```python
+apdb.set_trace(port=4444, host="127.0.0.1")
+```
+
+## CLI
+
+The package installs `apdb_cli`:
+
+```bash
+apdb_cli ping --port 4444
+apdb_cli state --port 4444
+apdb_cli where --port 4444
+apdb_cli locals --port 4444
+apdb_cli eval 'answer + 1' --port 4444
+apdb_cli next --port 4444
+apdb_cli step --port 4444
+apdb_cli continue --port 4444
+```
+
+The CLI prints one JSON response to stdout and exits nonzero for connection
+failures or API errors.
+
+## TCP API
+
+The TCP API speaks newline-delimited JSON. Each request and response is one JSON
+object followed by `\n`.
+
+Request:
+
+```json
+{"id": 1, "cmd": "state"}
+```
+
+Response:
+
+```json
+{"id": 1, "ok": true, "result": {"status": "paused"}}
+```
+
+Supported v0 commands:
+
+- `ping`
+- `state`
+- `where`
+- `locals`
+- `eval`
+- `next`
+- `step`
+- `continue`
+- `quit`
+
+## Security
+
+`apdb` has no authentication in v0. Debugger access can inspect and evaluate
+code inside the target process. Bind to `127.0.0.1` unless you explicitly want
+to expose that control surface.

apdb-0.1.0/apdb.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+apdb/__init__.py
+apdb/cli.py
+apdb/debugger.py
+apdb/protocol.py
+apdb/server.py
+apdb.egg-info/PKG-INFO
+apdb.egg-info/SOURCES.txt
+apdb.egg-info/dependency_links.txt
+apdb.egg-info/entry_points.txt
+apdb.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_integration.py
+tests/test_protocol.py

apdb-0.1.0/apdb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

apdb-0.1.0/apdb.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+apdb_cli = apdb.cli:main

apdb-0.1.0/apdb.egg-info/top_level.txt

@@ -0,0 +1 @@
+apdb

apdb-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apdb"
+version = "0.1.0"
+description = "Agent-friendly remote Python debugger over a zero-dependency TCP API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "BSD-2-Clause"
+authors = [
+  {name = "apdb contributors"}
+]
+keywords = ["debugger", "pdb", "agent", "tcp", "remote-debugger"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Debuggers",
+]
+dependencies = []
+license-files = ["LICENSE"]
+
+[project.scripts]
+apdb_cli = "apdb.cli:main"
+
+[tool.setuptools]
+packages = ["apdb"]

apdb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

apdb-0.1.0/tests/test_cli.py

@@ -0,0 +1,81 @@
+import contextlib
+import io
+import json
+import socket
+import socketserver
+import threading
+import unittest
+
+from apdb import cli
+
+
+class OneShotHandler(socketserver.StreamRequestHandler):
+    response = {"id": 1, "ok": True, "result": {"status": "online"}}
+    seen_request = None
+
+    def handle(self):
+        line = self.rfile.readline()
+        type(self).seen_request = json.loads(line.decode("utf-8"))
+        self.wfile.write((json.dumps(type(self).response) + "\n").encode("utf-8"))
+
+
+class CLITests(unittest.TestCase):
+    def run_server(self):
+        server = socketserver.TCPServer(("127.0.0.1", 0), OneShotHandler)
+        thread = threading.Thread(target=server.handle_request, daemon=True)
+        thread.start()
+        self.addCleanup(server.server_close)
+        return server, thread
+
+    def test_send_command_exchanges_one_ndjson_request(self):
+        server, thread = self.run_server()
+        host, port = server.server_address
+
+        response = cli.send_command(host, port, {"id": 1, "cmd": "ping"}, timeout=1.0)
+        thread.join(timeout=1.0)
+
+        self.assertEqual(response, OneShotHandler.response)
+        self.assertEqual(OneShotHandler.seen_request, {"id": 1, "cmd": "ping"})
+
+    def test_main_prints_json_response(self):
+        server, thread = self.run_server()
+        host, port = server.server_address
+        stdout = io.StringIO()
+
+        with contextlib.redirect_stdout(stdout):
+            exit_code = cli.main(["ping", "--host", host, "--port", str(port)])
+        thread.join(timeout=1.0)
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(json.loads(stdout.getvalue()), OneShotHandler.response)
+
+    def test_main_returns_nonzero_when_connection_fails(self):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.bind(("127.0.0.1", 0))
+            host, port = sock.getsockname()
+        stderr = io.StringIO()
+
+        with contextlib.redirect_stderr(stderr):
+            exit_code = cli.main(["ping", "--host", host, "--port", str(port)])
+
+        self.assertEqual(exit_code, 2)
+        self.assertIn("connection failed", stderr.getvalue())
+
+    def test_eval_command_sends_expression(self):
+        server, thread = self.run_server()
+        host, port = server.server_address
+        stdout = io.StringIO()
+
+        with contextlib.redirect_stdout(stdout):
+            exit_code = cli.main(["eval", "x + 1", "--host", host, "--port", str(port)])
+        thread.join(timeout=1.0)
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(
+            OneShotHandler.seen_request,
+            {"id": 1, "cmd": "eval", "expr": "x + 1"},
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

apdb-0.1.0/tests/test_integration.py

@@ -0,0 +1,212 @@
+import os
+import socket
+import subprocess
+import sys
+import tempfile
+import textwrap
+import time
+import unittest
+
+from apdb.cli import send_command
+
+
+def unused_port():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+def wait_for_ping(port, timeout=5.0):
+    deadline = time.monotonic() + timeout
+    last_error = None
+    while time.monotonic() < deadline:
+        try:
+            return send_command("127.0.0.1", port, {"id": 1, "cmd": "ping"}, timeout=0.2)
+        except OSError as exc:
+            last_error = exc
+            time.sleep(0.05)
+    raise AssertionError(f"apdb service did not become ready: {last_error}")
+
+
+class IntegrationTests(unittest.TestCase):
+    def start_debuggee(self, source):
+        tempdir = tempfile.TemporaryDirectory()
+        self.addCleanup(tempdir.cleanup)
+        script = os.path.join(tempdir.name, "debuggee.py")
+        with open(script, "w", encoding="utf-8") as handle:
+            handle.write(source)
+
+        env = os.environ.copy()
+        repo_root = os.path.dirname(os.path.dirname(__file__))
+        env["PYTHONPATH"] = repo_root + os.pathsep + env.get("PYTHONPATH", "")
+        process = subprocess.Popen(
+            [sys.executable, script],
+            cwd=tempdir.name,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        self.addCleanup(self.cleanup_process, process)
+        return process
+
+    def cleanup_process(self, process):
+        if process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=2)
+        if process.stdout is not None:
+            process.stdout.close()
+        if process.stderr is not None:
+            process.stderr.close()
+
+    def test_set_trace_serves_state_locals_eval_and_continue(self):
+        port = unused_port()
+        source = textwrap.dedent(
+            f"""
+            import apdb
+
+            def main():
+                answer = 41
+                print("before", flush=True)
+                apdb.set_trace(port={port})
+                print("after", answer + 1, flush=True)
+
+            main()
+            """
+        )
+        process = self.start_debuggee(source)
+
+        self.assertEqual(process.stdout.readline().strip(), "before")
+        self.assertEqual(wait_for_ping(port)["result"], {"status": "online"})
+
+        state = send_command("127.0.0.1", port, {"id": 2, "cmd": "state"}, timeout=1.0)
+        self.assertTrue(state["ok"])
+        self.assertEqual(state["result"]["status"], "paused")
+        self.assertEqual(state["result"]["function"], "main")
+        self.assertEqual(os.path.basename(state["result"]["file"]), "debuggee.py")
+
+        locals_response = send_command(
+            "127.0.0.1", port, {"id": 3, "cmd": "locals"}, timeout=1.0
+        )
+        self.assertEqual(locals_response["result"]["answer"], "41")
+
+        eval_response = send_command(
+            "127.0.0.1", port, {"id": 4, "cmd": "eval", "expr": "answer + 1"}, timeout=1.0
+        )
+        self.assertEqual(eval_response["result"]["repr"], "42")
+
+        continue_response = send_command(
+            "127.0.0.1", port, {"id": 5, "cmd": "continue"}, timeout=1.0
+        )
+        self.assertTrue(continue_response["ok"])
+        self.assertEqual(continue_response["result"]["status"], "continuing")
+
+        self.assertEqual(process.stdout.readline().strip(), "after 42")
+        self.assertEqual(process.wait(timeout=2), 0)
+
+    def test_unknown_command_returns_structured_error(self):
+        port = unused_port()
+        source = textwrap.dedent(
+            f"""
+            import apdb
+            print("before", flush=True)
+            apdb.set_trace(port={port})
+            print("after", flush=True)
+            """
+        )
+        process = self.start_debuggee(source)
+
+        self.assertEqual(process.stdout.readline().strip(), "before")
+        wait_for_ping(port)
+        response = send_command("127.0.0.1", port, {"id": 9, "cmd": "bad"}, timeout=1.0)
+
+        self.assertFalse(response["ok"])
+        self.assertEqual(response["error"]["code"], "unknown_command")
+        send_command("127.0.0.1", port, {"id": 10, "cmd": "continue"}, timeout=1.0)
+        self.assertEqual(process.wait(timeout=2), 0)
+
+    def test_next_releases_to_next_line_and_pauses_again(self):
+        port = unused_port()
+        source = textwrap.dedent(
+            f"""
+            import apdb
+
+            def main():
+                value = 1
+                print("before", flush=True)
+                apdb.set_trace(port={port})
+                value = value + 1
+                print("middle", value, flush=True)
+                print("after", flush=True)
+
+            main()
+            """
+        )
+        process = self.start_debuggee(source)
+
+        self.assertEqual(process.stdout.readline().strip(), "before")
+        wait_for_ping(port)
+        next_response = send_command(
+            "127.0.0.1", port, {"id": 11, "cmd": "next"}, timeout=1.0
+        )
+        self.assertTrue(next_response["ok"])
+
+        state = send_command("127.0.0.1", port, {"id": 12, "cmd": "state"}, timeout=2.0)
+        self.assertEqual(state["result"]["status"], "paused")
+        self.assertIn("value = value + 1", state["result"]["code"])
+
+        send_command("127.0.0.1", port, {"id": 13, "cmd": "continue"}, timeout=1.0)
+        self.assertEqual(process.stdout.readline().strip(), "middle 2")
+        self.assertEqual(process.stdout.readline().strip(), "after")
+        self.assertEqual(process.wait(timeout=2), 0)
+
+    def test_step_enters_called_function_and_pauses_again(self):
+        port = unused_port()
+        source = textwrap.dedent(
+            f"""
+            import apdb
+
+            def helper():
+                marker = "inside"
+                return marker
+
+            def main():
+                print("before", flush=True)
+                apdb.set_trace(port={port})
+                result = helper()
+                print("after", result, flush=True)
+
+            main()
+            """
+        )
+        process = self.start_debuggee(source)
+
+        self.assertEqual(process.stdout.readline().strip(), "before")
+        wait_for_ping(port)
+        step_response = send_command(
+            "127.0.0.1", port, {"id": 14, "cmd": "step"}, timeout=1.0
+        )
+        self.assertTrue(step_response["ok"])
+
+        state = send_command("127.0.0.1", port, {"id": 15, "cmd": "state"}, timeout=2.0)
+        self.assertEqual(state["result"]["status"], "paused")
+        self.assertIn("result = helper()", state["result"]["code"])
+
+        step_into_response = send_command(
+            "127.0.0.1", port, {"id": 16, "cmd": "step"}, timeout=1.0
+        )
+        self.assertTrue(step_into_response["ok"])
+        state = send_command("127.0.0.1", port, {"id": 17, "cmd": "state"}, timeout=2.0)
+        self.assertEqual(state["result"]["function"], "helper")
+
+        send_command("127.0.0.1", port, {"id": 18, "cmd": "continue"}, timeout=1.0)
+        self.assertEqual(process.stdout.readline().strip(), "after inside")
+        self.assertEqual(process.wait(timeout=2), 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

apdb-0.1.0/tests/test_protocol.py

@@ -0,0 +1,62 @@
+import json
+import unittest
+
+from apdb.protocol import (
+    ProtocolError,
+    dumps_response,
+    error_response,
+    loads_request,
+    ok_response,
+)
+
+
+class ProtocolTests(unittest.TestCase):
+    def test_loads_request_accepts_json_object_with_command(self):
+        request = loads_request(b'{"id": 7, "cmd": "ping"}\n')
+
+        self.assertEqual(request, {"id": 7, "cmd": "ping"})
+
+    def test_loads_request_rejects_invalid_json(self):
+        with self.assertRaises(ProtocolError) as context:
+            loads_request(b"{not-json}\n")
+
+        self.assertEqual(context.exception.code, "invalid_json")
+
+    def test_loads_request_rejects_missing_command(self):
+        with self.assertRaises(ProtocolError) as context:
+            loads_request(b'{"id": 1}\n')
+
+        self.assertEqual(context.exception.code, "missing_command")
+
+    def test_dumps_response_writes_newline_delimited_json(self):
+        payload = dumps_response({"id": 1, "ok": True, "result": {"status": "online"}})
+
+        self.assertTrue(payload.endswith(b"\n"))
+        self.assertEqual(
+            json.loads(payload.decode("utf-8")),
+            {"id": 1, "ok": True, "result": {"status": "online"}},
+        )
+
+    def test_ok_response_preserves_request_id(self):
+        response = ok_response({"id": "abc", "cmd": "ping"}, {"status": "online"})
+
+        self.assertEqual(
+            response,
+            {"id": "abc", "ok": True, "result": {"status": "online"}},
+        )
+
+    def test_error_response_preserves_request_id(self):
+        response = error_response({"id": 3}, "unknown_command", "unknown command: nope")
+
+        self.assertEqual(
+            response,
+            {
+                "id": 3,
+                "ok": False,
+                "error": {"code": "unknown_command", "message": "unknown command: nope"},
+            },
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()