handcode 0.3.0rc1__py3-none-any.whl

agentctl/control/replay/server.py

@@ -0,0 +1,109 @@
+r"""A local OpenAI-compatible endpoint that answers from a cassette.
+
+Point `--base-url` at it and the agent runs normally: same SDK, same tools,
+same gate, same ledger — but every completion comes from disk. No API key, no
+network, no tokens, no sampling.
+
+Stdlib only, deliberately. `docs/0021` §7 is what a casual dependency costs on
+this project, and a test fixture is the last place to spend that.
+
+**On a miss the server returns 502, and that is correct.** A miss means the
+agent asked something the recording never contains, which is a real
+divergence. Answering it with a plausible-looking completion would produce a
+run that looks like a replay and is not one -- the same shape as the failures
+in `docs/0024` and `docs/0028`, where a component returned something usable
+instead of admitting it could not answer.
+"""
+from __future__ import annotations
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from .cassette import Cassette
+
+
+class ReplayServer:
+    """Serves one cassette on localhost for the life of a `with` block."""
+
+    def __init__(self, cassette: Cassette, port: int = 0,
+                 on_miss: Any = None):
+        self.cassette = cassette
+        self.on_miss = on_miss
+        self._srv = ThreadingHTTPServer(("127.0.0.1", port),
+                                        _handler_for(self))
+        self._thread: threading.Thread | None = None
+
+    @property
+    def port(self) -> int:
+        return self._srv.server_address[1]
+
+    @property
+    def base_url(self) -> str:
+        """What to pass as `--base-url`. The SDK appends `/chat/completions`."""
+        return f"http://127.0.0.1:{self.port}/v1"
+
+    def start(self) -> "ReplayServer":
+        self._thread = threading.Thread(target=self._srv.serve_forever,
+                                        daemon=True)
+        self._thread.start()
+        return self
+
+    def stop(self) -> None:
+        self._srv.shutdown()
+        self._srv.server_close()
+        if self._thread:
+            self._thread.join(timeout=5)
+
+    def __enter__(self) -> "ReplayServer":
+        return self.start()
+
+    def __exit__(self, *exc) -> None:
+        self.stop()
+
+
+def _handler_for(server: ReplayServer):
+    class Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def do_POST(self):                              # noqa: N802
+            length = int(self.headers.get("Content-Length") or 0)
+            try:
+                request = json.loads(self.rfile.read(length) or b"{}")
+            except json.JSONDecodeError:
+                return self._send(400, {"error": {"message": "bad json"}})
+
+            turn = server.cassette.match(request)
+            if turn is None:
+                miss = server.cassette.misses[-1]
+                if server.on_miss:
+                    server.on_miss(miss)
+                # 502, not a fabricated completion: see the module docstring.
+                return self._send(502, {"error": {
+                    "type": "agentctl_replay_miss",
+                    "message": f"cassette miss -- {miss.describe()}",
+                }})
+            return self._send(200, turn.response)
+
+        def do_GET(self):                               # noqa: N802
+            """`/v1/models` and health checks, so clients that probe are happy."""
+            if self.path.rstrip("/").endswith("/models"):
+                models = sorted({t.model for t in server.cassette if t.model})
+                return self._send(200, {"object": "list", "data": [
+                    {"id": m, "object": "model"} for m in models]})
+            return self._send(200, {"status": "ok",
+                                    "turns": len(server.cassette)})
+
+        def _send(self, code: int, body: dict) -> None:
+            payload = json.dumps(body).encode("utf-8")
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+            self.end_headers()
+            self.wfile.write(payload)
+
+        def log_message(self, *_args) -> None:
+            """Silence. The cassette records what happened, not stderr."""
+
+    return Handler

agentctl/demo/__init__.py

@@ -0,0 +1,214 @@
+"""`agentctl demo`: the one thing this project exists for, in a minute, for $0.
+
+`docs/0043` Phase 5. An agent runs `git commit`; its process is killed after
+the commit has landed but before the result was recorded; the run is resumed.
+Plain OpenHands re-drives the pending action and commits AGAIN (`docs/0014`
+reproduced it). With agentctl the git probe sees the commit already landed and
+hands the agent its result instead.
+
+Both arms run for real: real git, real process death (`kill`, not a polite
+shutdown), the real OpenHands SDK. Only the MODEL is scripted -- a local mock
+that asks for the commit once and then stops -- which is what makes it free,
+offline, deterministic, and the same on every OS. A recorded cassette was the
+alternative and could not be: the SDK writes the shell name into the system
+prompt, so a cassette replays only on the platform it was recorded on
+(`docs/0029` §6), and git hashes and timings in tool output would break an
+exact replay anyway (`docs/0050`).
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+MARKER = "commit_landed.marker"
+SLEEP_S = 8.0               # the crash window: committed, result not recorded
+TIMEOUT_S = 150.0
+
+
+def _git(repo: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", *args], cwd=str(repo), capture_output=True,
+                          text=True)
+
+
+def _commits(repo: Path) -> int:
+    r = _git(repo, "rev-list", "--count", "HEAD")
+    return int(r.stdout.strip()) if r.returncode == 0 and r.stdout.strip() else 0
+
+
+def _seed(ws: Path) -> Path:
+    repo = ws / "repo"
+    repo.mkdir(parents=True)
+    _git(repo, "init", "-q")
+    # Local identity: the demo must not depend on, or touch, the user's own.
+    _git(repo, "config", "user.name", "agentctl demo")
+    _git(repo, "config", "user.email", "demo@agentctl.invalid")
+    (repo / "README.md").write_text("demo\n", encoding="utf-8")
+    _git(repo, "add", "-A")
+    _git(repo, "commit", "-qm", "seed")
+    return repo
+
+
+def _child(arm: str, mode: str, ws: Path, base_url: str) -> subprocess.Popen:
+    env = {**os.environ, "OPENHANDS_SUPPRESS_BANNER": "1",
+           "PYTHONIOENCODING": "utf-8",
+           # A private run index: the demo's runs are not the user's.
+           "AGENTCTL_HOME": str(ws / "home")}
+    out = open(ws / f"{arm}_{mode}.log", "w", encoding="utf-8", errors="replace")
+    p = subprocess.Popen(
+        [sys.executable, "-m", "agentctl.demo.child", "--arm", arm, "--mode", mode,
+         "--ws", str(ws), "--base-url", base_url],
+        stdout=out, stderr=subprocess.STDOUT, env=env, stdin=subprocess.DEVNULL)
+    p._log = out                                        # type: ignore[attr-defined]
+    return p
+
+
+def _wait_marker(ws: Path, p: subprocess.Popen) -> bool:
+    t0 = time.time()
+    while time.time() - t0 < TIMEOUT_S:
+        if (ws / MARKER).exists():
+            return True
+        if p.poll() is not None:
+            return False
+        time.sleep(0.05)
+    return False
+
+
+def _tail(path: Path, n: int = 12) -> str:
+    try:
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return ""
+    return "\n".join("      " + l for l in lines[-n:])
+
+
+def _arm(arm: str, root: Path, base_url: str, say) -> dict:
+    """Commit, kill inside the window, resume. Count commits at each step."""
+    ws = root / arm
+    ws.mkdir()
+    repo = _seed(ws)
+    before = _commits(repo)
+
+    p = _child(arm, "fresh", ws, base_url)
+    if not _wait_marker(ws, p):
+        p.kill(); p.wait(); p._log.close()
+        return {"error": "the commit never ran", "log": _tail(ws / f"{arm}_fresh.log")}
+    time.sleep(0.5)
+    p.kill()                    # not a shutdown: no finally, no flush, no atexit
+    p.wait(); p._log.close()
+    after_crash = _commits(repo) - before
+    say(f"     the agent committed, then its process was killed ... "
+        f"{after_crash} new commit")
+
+    (ws / MARKER).unlink(missing_ok=True)
+    p = _child(arm, "resume", ws, base_url)
+    try:
+        p.wait(timeout=TIMEOUT_S)
+    except subprocess.TimeoutExpired:
+        p.kill(); p.wait()
+    p._log.close()
+    after_resume = _commits(repo) - before
+    return {"after_crash": after_crash, "after_resume": after_resume,
+            "ws": ws, "log": _tail(ws / f"{arm}_resume.log")}
+
+
+def _rmtree(path: Path) -> None:
+    def onerror(func, p, _exc):                         # git marks objects read-only
+        os.chmod(p, stat.S_IWRITE)
+        func(p)
+    shutil.rmtree(path, onerror=onerror)
+
+
+def run_demo(keep: bool = False) -> int:
+    from agentctl.demo.mock import MockModel
+
+    def say(msg=""):
+        print(msg, flush=True)
+
+    if shutil.which("git") is None:
+        say("  the demo needs git on PATH.")
+        return 2
+
+    say("agentctl demo   (no API key, no network, $0)")
+    say("")
+    say("  An agent runs `git commit`. Its process is killed AFTER the commit")
+    say("  lands but BEFORE the result is recorded. Then the run is resumed.")
+    say("  Real git, real OpenHands, real process death; only the model is")
+    say("  scripted, so this costs nothing and runs the same everywhere.")
+    say("")
+
+    root = Path(tempfile.mkdtemp(prefix="agentctl-demo-"))
+    results: dict = {}
+    try:
+        with MockModel() as model:
+            say("  1. Plain OpenHands, no agentctl")
+            results["bare"] = r = _arm("bare", root, model.base_url, say)
+            if "error" not in r:
+                say(f"     resumed ............................................ "
+                    f"{r['after_resume']} new commits"
+                    + ("   <- the same commit, twice" if r["after_resume"] > 1 else ""))
+            say("")
+            say("  2. With agentctl")
+            results["guarded"] = g = _arm("guarded", root, model.base_url, say)
+            if "error" not in g:
+                say(f"     resumed ............................................ "
+                    f"{g['after_resume']} new commit"
+                    + ("    <- once" if g["after_resume"] == 1 else ""))
+                ledger = _ledger_summary(g["ws"])
+                if ledger:
+                    say(f"     {ledger}")
+        say("")
+        return _verdict(results, say, root)
+    finally:
+        if keep:
+            say(f"  kept: {root}")
+        else:
+            try:
+                _rmtree(root)
+            except OSError:
+                pass
+
+
+def _ledger_summary(ws: Path) -> str:
+    try:
+        from agentctl.kernel.ledger.store import LedgerStore
+        with LedgerStore(ws / "ledger.db", holder="demo") as s:
+            rows = s._db.execute("SELECT state, probe_verdict FROM effect_record"
+                                 ).fetchall()
+            blocked = len(s.blocked())
+        parts = [f"{r['state']}" + (f" (git probe: {r['probe_verdict']})"
+                                    if r["probe_verdict"] else "") for r in rows]
+        return ("the ledger: the commit is " + ", ".join(parts)
+                + f" · {blocked} waiting on you")
+    except Exception:                                   # noqa: BLE001
+        return ""
+
+
+def _verdict(results: dict, say, root: Path) -> int:
+    bare, guarded = results.get("bare", {}), results.get("guarded", {})
+    for name, r in (("plain OpenHands", bare), ("agentctl", guarded)):
+        if "error" in r:
+            say(f"  the demo could not run the {name} arm: {r['error']}.")
+            say(r.get("log", ""))
+            say("  This is a broken demo, not a result. `agentctl doctor` checks "
+                "the install.")
+            return 2
+    if guarded["after_resume"] == 1 and bare["after_resume"] >= 2:
+        say("  Without agentctl the crash cost a duplicate commit. With it, the")
+        say("  agent got the commit's result back and carried on, and nothing")
+        say("  needed a human.")
+        say("")
+        say("  On a real task:   agentctl init")
+        say('                    agentctl run "<task>" --accept "<your tests>"')
+        return 0
+    # Never claim what was not shown.
+    say(f"  The demo did NOT show what it claims: plain OpenHands made "
+        f"{bare['after_resume']} commit(s), agentctl {guarded['after_resume']}.")
+    say(guarded.get("log", ""))
+    say(f"  Please report this with the logs in {root} (re-run with --keep).")
+    return 1

agentctl/demo/child.py

@@ -0,0 +1,84 @@
+"""One run of the demo, in its own process, so it can be killed for real.
+
+    python -m agentctl.demo.child --arm bare|guarded --mode fresh|resume \\
+        --ws DIR --base-url URL
+
+`bare` is plain OpenHands. `guarded` adds agentctl through `protect()`, the
+same public embed API the README documents -- not a demo-only path.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import uuid
+from pathlib import Path
+
+from agentctl.demo import MARKER, SLEEP_S
+
+#: The demo tool is a commit: not safe to repeat, and git can be asked whether
+#: it landed.
+MATRIX = {"version": 1, "defaults": {"unknown_tool": "EXTERNAL"},
+          "tools": {"commit": {"class": "NON_IDEMPOTENT_WRITE", "probe": "git"}}}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--arm", choices=("bare", "guarded"), required=True)
+    ap.add_argument("--mode", choices=("fresh", "resume"), required=True)
+    ap.add_argument("--ws", type=Path, required=True)
+    ap.add_argument("--base-url", required=True)
+    a = ap.parse_args()
+
+    from agentctl.demo import tool
+    from agentctl.runtime.runner import _build_agent
+    from openhands.sdk import LLM, Conversation
+
+    ws, repo = a.ws, a.ws / "repo"
+    os.environ[tool.REPO_ENV] = str(repo)
+    os.environ[tool.MARKER_ENV] = str(ws / MARKER)
+    os.environ[tool.SLEEP_ENV] = str(SLEEP_S)
+
+    cid_file = ws / "conversation_id.txt"
+    if a.mode == "fresh":
+        cid = uuid.uuid4()
+        cid_file.write_text(str(cid), encoding="utf-8")
+    else:
+        cid = uuid.UUID(cid_file.read_text(encoding="utf-8").strip())
+
+    callbacks, guard = [], None
+    if a.arm == "guarded":
+        from agentctl.adapters.openhands import protect
+        from agentctl.runtime.lease import claim
+
+        ledger = ws / "ledger.db"
+        # The crashed holder is dead, so the resume may take its lease without
+        # being told to (`docs/0046`).
+        steal = claim(ledger, str(cid)).takeover if a.mode == "resume" else False
+        guard = protect(ledger=ledger, conversation_id=str(cid),
+                        tools={tool.NAME: tool.CommitTool}, matrix=MATRIX,
+                        repo_root=repo, takeover=steal)
+        callbacks = [guard.seam_b]
+    else:
+        tool.register()
+
+    llm = LLM(model="openai/demo-model", api_key="not-needed", base_url=a.base_url,
+              service_id="agentctl-demo", temperature=0.0, num_retries=1)
+    # Through the one place allowed to build an Agent, which pins
+    # tool_concurrency_limit to 1 (`docs/0038` §4.3) -- the demo too.
+    agent = _build_agent(llm, [tool.NAME])
+    conv = Conversation(agent=agent, workspace=str(repo),
+                        persistence_dir=str(ws / "state"), conversation_id=cid,
+                        delete_on_close=False, stuck_detection=False,
+                        visualizer=None, callbacks=callbacks)
+    if guard is not None:
+        guard.attach(conv)
+    if a.mode == "fresh":
+        conv.send_message("Commit the fix with the message 'fix the typo'.")
+    conv.run()
+    if guard is not None:
+        guard.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentctl/demo/mock.py

@@ -0,0 +1,79 @@
+"""The demo's scripted model: an OpenAI-compatible server on 127.0.0.1.
+
+It does one thing: asks for the `commit` tool once, then says it is done. The
+tool call id is FIXED, so a resumed run re-drives the very same action -- which
+is the case under test. Adapted from `experiments/0000-falsification`'s mock,
+reduced to what the demo needs.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+import uuid
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+CALL_ID = "call_demo_commit_0001"
+
+
+def _completion(model: str, message: dict, finish: str) -> dict:
+    return {"id": f"chatcmpl-{uuid.uuid4().hex[:12]}", "object": "chat.completion",
+            "created": int(time.time()), "model": model,
+            "choices": [{"index": 0, "finish_reason": finish, "message": message}],
+            "usage": {"prompt_tokens": 100, "completion_tokens": 10,
+                      "total_tokens": 110}}
+
+
+class _Handler(BaseHTTPRequestHandler):
+    def log_message(self, *_):
+        pass
+
+    def _send(self, body: dict) -> None:
+        raw = json.dumps(body).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def do_GET(self):                                   # noqa: N802
+        self._send({"object": "list", "data": [{"id": "demo-model",
+                                                 "object": "model"}]})
+
+    def do_POST(self):                                  # noqa: N802
+        n = int(self.headers.get("Content-Length") or 0)
+        try:
+            body = json.loads(self.rfile.read(n) if n else b"{}")
+        except json.JSONDecodeError:
+            body = {}
+        model = body.get("model") or "demo-model"
+        done = any(m.get("role") == "tool" for m in body.get("messages") or [])
+        name = next(((t.get("function") or {}).get("name")
+                     for t in body.get("tools") or [] if t.get("function")), "commit")
+        if done:
+            msg = {"role": "assistant", "content": "Committed. Done."}
+            self._send(_completion(model, msg, "stop"))
+        else:
+            msg = {"role": "assistant", "content": None, "tool_calls": [{
+                "id": CALL_ID, "type": "function",
+                "function": {"name": name,
+                             "arguments": json.dumps({"message": "fix the typo"})}}]}
+            self._send(_completion(model, msg, "tool_calls"))
+
+
+class MockModel:
+    def __init__(self):
+        self._srv = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
+        self._thread = threading.Thread(target=self._srv.serve_forever, daemon=True)
+
+    @property
+    def base_url(self) -> str:
+        return f"http://127.0.0.1:{self._srv.server_address[1]}/v1"
+
+    def __enter__(self) -> "MockModel":
+        self._thread.start()
+        return self
+
+    def __exit__(self, *_) -> None:
+        self._srv.shutdown()
+        self._srv.server_close()

agentctl/demo/tool.py

@@ -0,0 +1,62 @@
+"""The demo's side-effecting tool: a real `git commit`, with a crash window.
+
+Module level on purpose: on resume the SDK resolves these classes to
+deserialize the persisted ActionEvent, and a class defined inside a function
+is not importable -- the resume then silently does nothing (`docs/0017`).
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Sequence
+
+from pydantic import Field
+
+from openhands.sdk.tool import (Action, Observation, ToolDefinition, ToolExecutor,
+                                register_tool)
+
+NAME = "commit"
+REPO_ENV, MARKER_ENV, SLEEP_ENV = ("AGENTCTL_DEMO_REPO", "AGENTCTL_DEMO_MARKER",
+                                   "AGENTCTL_DEMO_SLEEP")
+
+
+class CommitAction(Action):
+    # Only the message is the model's. WHERE a commit lands never is
+    # (`docs/0023` §3: a real model filled a `cwd` field with ".").
+    message: str = Field(default="agent work", description="Commit message.")
+
+
+class CommitObservation(Observation):
+    status: str = Field(default="ok")
+
+    @property
+    def agent_observation(self):
+        from openhands.sdk.llm import TextContent
+        return [TextContent(text=f"commit {self.status}")]
+
+
+class CommitExecutor(ToolExecutor):
+    def __call__(self, action, conversation=None):
+        repo = Path(os.environ[REPO_ENV])
+        subprocess.run(["git", "commit", "--allow-empty", "-q", "-m", action.message],
+                       cwd=str(repo), capture_output=True, text=True)
+        # Signal only AFTER the commit landed, so the kill falls in the window
+        # where the effect happened and the record of it did not.
+        if (marker := os.environ.get(MARKER_ENV)):
+            Path(marker).write_text(str(time.time()), encoding="utf-8")
+        time.sleep(float(os.environ.get(SLEEP_ENV, "8")))
+        return CommitObservation(status="ok")
+
+
+class CommitTool(ToolDefinition[CommitAction, CommitObservation]):
+    @classmethod
+    def create(cls, conv_state=None, **params) -> Sequence["CommitTool"]:
+        return [cls(name=NAME, description="Make a git commit in the repo.",
+                    action_type=CommitAction, observation_type=CommitObservation,
+                    executor=CommitExecutor())]
+
+
+def register() -> None:
+    register_tool(NAME, CommitTool)