handcode 0.3.0rc1__py3-none-any.whl

agentctl/kernel/reconcile/filesystem.py

@@ -0,0 +1,162 @@
+"""Filesystem reconciliation probe.
+
+Covers the second common non-idempotent effect: appending to a file.
+
+Method:
+
+    capture()   the file's size and content hash, plus the bytes to be appended
+    probe()     unchanged                    -> DID_NOT_LAND
+                prefix intact + our bytes    -> LANDED  (proof, not inference)
+                anything else                -> INCONCLUSIVE
+
+The middle case is the good one. Because the tool's arguments carry the content
+being appended, we can verify *our* bytes are present rather than merely
+noticing the file changed. That is stronger than the git probe, which can only
+infer from "HEAD moved".
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from .base import DID_NOT_LAND, INCONCLUSIVE, LANDED
+
+_PATH_KEYS = ("path", "file_path", "filename", "file", "target")
+_CONTENT_KEYS = ("content", "text", "data", "payload", "new_str", "append")
+_MAX_BYTES = 32 * 1024 * 1024        # do not hash a huge file on the hot path
+
+
+class FileAppendProbe:
+    name = "filesystem"
+
+    def __init__(self, max_bytes: int = _MAX_BYTES):
+        self.max_bytes = max_bytes
+
+    # ── selection ──────────────────────────────────────────────────────
+    def handles(self, call) -> bool:
+        return self._path(call) is not None
+
+    # ── before ─────────────────────────────────────────────────────────
+    def capture(self, call) -> dict | None:
+        try:
+            path = self._path(call)
+            if path is None:
+                return None
+            pre = self._fingerprint(path)
+            if pre is None:
+                return None
+
+            out = {"probe": self.name, "path": str(path), **pre}
+
+            # If we can see what will be appended, record it so the probe can
+            # verify prefix + suffix rather than guessing.
+            content = self._content(call)
+            if content is not None:
+                out["appended"] = content.decode("utf-8", "replace")
+            return out
+        except Exception:                               # noqa: BLE001
+            return None
+
+    # ── after a crash ──────────────────────────────────────────────────
+    def probe(self, call, record) -> str:
+        try:
+            pre = _pre(record)
+            if not pre or pre.get("probe") != self.name:
+                return INCONCLUSIVE
+
+            path = Path(pre["path"])
+            now = self._fingerprint(path)
+            if now is None:
+                return INCONCLUSIVE
+
+            if now["sha256"] == pre.get("sha256") and now["size"] == pre.get("size"):
+                return DID_NOT_LAND
+
+            appended = pre.get("appended")
+            if appended is not None:
+                return self._verify_append(path, pre, appended)
+
+            # Changed, and we could not predict the post-state. Under the
+            # single-writer assumption this was our effect, but it is inference.
+            return LANDED
+        except Exception:                               # noqa: BLE001
+            return INCONCLUSIVE
+
+    # ── internals ──────────────────────────────────────────────────────
+    @staticmethod
+    def _path(call) -> Path | None:
+        for k in _PATH_KEYS:
+            if (v := call.args.get(k)):
+                try:
+                    p = Path(str(v))
+                except Exception:                       # noqa: BLE001
+                    continue
+                if p.parent.exists():
+                    return p
+        return None
+
+    @staticmethod
+    def _content(call) -> bytes | None:
+        for k in _CONTENT_KEYS:
+            v = call.args.get(k)
+            if isinstance(v, (str, bytes)):
+                return v.encode() if isinstance(v, str) else v
+        return None
+
+    def _verify_append(self, path: Path, pre: dict, appended: str) -> str:
+        """Prefix intact + our content at the tail means it landed.
+
+        Deliberately not a whole-file hash. Text-mode writers translate LF to
+        CRLF on Windows, so a predicted hash of the exact bytes almost never
+        matches and every append would fail closed. Comparing the unchanged
+        prefix against a newline-normalised tail is both more robust and a
+        stronger claim: it verifies *our* bytes are there, not merely that the
+        file changed.
+        """
+        pre_size = int(pre.get("size") or 0)
+        try:
+            data = path.read_bytes()
+        except OSError:
+            return INCONCLUSIVE
+
+        if len(data) < pre_size:
+            return INCONCLUSIVE                     # truncated: not our doing
+        if _sha(data[:pre_size]) != pre.get("sha256"):
+            return INCONCLUSIVE                     # prefix rewritten
+
+        tail = _norm(data[pre_size:])
+        ours = _norm(appended.encode())
+        if tail == ours or ours in tail:
+            return LANDED
+        return INCONCLUSIVE                         # someone else wrote
+
+    def _fingerprint(self, path: Path) -> dict | None:
+        try:
+            if not path.exists():
+                return {"exists": False, "size": 0, "sha256": _sha(b"")}
+            size = path.stat().st_size
+            if size > self.max_bytes:
+                return {"exists": True, "size": size, "sha256": None}
+            return {"exists": True, "size": size, "sha256": _sha(path.read_bytes())}
+        except OSError:
+            return None
+
+
+def _sha(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+def _norm(b: bytes) -> bytes:
+    """Normalise line endings so CRLF and LF compare equal."""
+    return b.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+
+
+def _pre(record) -> dict | None:
+    raw = getattr(record, "pre_state", None)
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except Exception:                                   # noqa: BLE001
+        return None

agentctl/kernel/reconcile/git.py

@@ -0,0 +1,162 @@
+"""Git reconciliation probe.
+
+The headline case: an agent runs `git commit`, the process dies before the
+observation is recorded, and on resume we must decide whether to run it again.
+
+Method — fingerprint, not marker:
+
+    capture()   HEAD sha + a hash of `git status --porcelain`
+    probe()     HEAD moved?            -> LANDED
+                HEAD same, tree same?  -> DID_NOT_LAND
+                anything else          -> INCONCLUSIVE
+
+No command mutation, so this works at Seam B (`docs/0016` §4).
+"""
+from __future__ import annotations
+
+import hashlib
+import shutil
+import subprocess
+from pathlib import Path
+
+from .base import DID_NOT_LAND, INCONCLUSIVE, LANDED
+
+#: Commands that move HEAD. `git push` is deliberately absent — it is EXTERNAL,
+#: and a local probe cannot see whether the remote accepted it.
+_MOVES_HEAD = ("commit", "merge", "cherry-pick", "revert", "am", "rebase")
+
+NO_COMMITS = "__NO_COMMITS__"
+
+
+class GitProbe:
+    name = "git"
+
+    def __init__(self, repo_root: str | Path | None = None, timeout_s: float = 10.0):
+        self.repo_root = Path(repo_root) if repo_root else None
+        self.timeout_s = timeout_s
+
+    # ── selection ──────────────────────────────────────────────────────
+    def handles(self, call) -> bool:
+        if shutil.which("git") is None:
+            return False
+        # A dedicated tool ("commit", "git_commit") carries no command string
+        # to sniff, so match on the tool name too.
+        name = (call.tool_name or "").lower()
+        if any(verb in name for verb in _MOVES_HEAD):
+            return True
+        text = self._command_text(call)
+        if "git " not in text:
+            return False
+        return any(f"git {verb}" in text for verb in _MOVES_HEAD)
+
+    # ── before ─────────────────────────────────────────────────────────
+    def capture(self, call) -> dict | None:
+        try:
+            root = self._root(call)
+            if root is None:
+                return None
+            head = self._head(root)
+            if head is None:
+                return None                     # not a git repo
+            return {
+                "probe": self.name,
+                "root": str(root),
+                # The repo we actually attached to. A workspace nested inside a
+                # larger repo silently resolves to the ANCESTOR, whose HEAD
+                # moves for reasons that have nothing to do with this agent.
+                "toplevel": self._git(root, "rev-parse", "--show-toplevel"),
+                "head": head,
+                "tree": self._tree_hash(root),
+            }
+        except Exception:                               # noqa: BLE001
+            return None
+
+    # ── after a crash ──────────────────────────────────────────────────
+    def probe(self, call, record) -> str:
+        try:
+            pre = _pre(record)
+            if not pre or pre.get("probe") != self.name:
+                return INCONCLUSIVE
+
+            root = Path(pre["root"])
+            head_now = self._head(root)
+            if head_now is None:
+                return INCONCLUSIVE
+
+            # A different repo than the one we fingerprinted: say nothing.
+            if self._git(root, "rev-parse", "--show-toplevel") != pre.get("toplevel"):
+                return INCONCLUSIVE
+
+            if head_now != pre.get("head"):
+                # HEAD moved during the crash window. With a single writer in
+                # the workspace, that was our commit.
+                return LANDED
+
+            tree_now = self._tree_hash(root)
+            if tree_now is not None and tree_now == pre.get("tree"):
+                # HEAD unchanged AND the working tree is exactly as we left it:
+                # nothing was committed and nothing else happened either.
+                return DID_NOT_LAND
+
+            # HEAD unchanged but the tree moved. Something happened that was
+            # not a commit; we cannot attribute it. Do not guess.
+            return INCONCLUSIVE
+        except Exception:                               # noqa: BLE001
+            return INCONCLUSIVE
+
+    # ── internals ──────────────────────────────────────────────────────
+    def _root(self, call) -> Path | None:
+        """Configured root wins over anything the model supplied.
+
+        A model that can choose the path can choose the blast radius, and the
+        probe would then faithfully fingerprint the wrong world. Argument keys
+        are a fallback for tools that genuinely take a path, never an override.
+        """
+        if self.repo_root is not None:
+            return self.repo_root
+        for key in ("cwd", "working_dir", "path", "repo"):
+            if (v := call.args.get(key)):
+                p = Path(str(v))
+                if p.is_dir():
+                    return p
+        return None
+
+    def _git(self, root: Path, *args: str) -> str | None:
+        try:
+            r = subprocess.run(
+                ["git", *args], cwd=str(root), capture_output=True,
+                text=True, timeout=self.timeout_s,
+            )
+        except Exception:                               # noqa: BLE001
+            return None
+        return r.stdout.strip() if r.returncode == 0 else None
+
+    def _head(self, root: Path) -> str | None:
+        if self._git(root, "rev-parse", "--is-inside-work-tree") != "true":
+            return None
+        head = self._git(root, "rev-parse", "HEAD")
+        # A repo with no commits yet has no HEAD; that is a valid state.
+        return head if head else NO_COMMITS
+
+    def _tree_hash(self, root: Path) -> str | None:
+        status = self._git(root, "status", "--porcelain=v1", "--untracked-files=all")
+        if status is None:
+            return None
+        return hashlib.sha256(status.encode()).hexdigest()
+
+    @staticmethod
+    def _command_text(call) -> str:
+        if "command" in call.args:
+            return str(call.args["command"])
+        return " ".join(str(v) for v in call.args.values())
+
+
+def _pre(record) -> dict | None:
+    import json
+    raw = getattr(record, "pre_state", None)
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except Exception:                                   # noqa: BLE001
+        return None

agentctl/runtime/__init__.py

@@ -0,0 +1,20 @@
+"""Runtime: real tools and a runner, for doing actual work.
+
+`experiments/` proves the system; this uses it.
+
+The names below load on first use. Importing them eagerly meant that any
+`agentctl.runtime.*` import -- `lease`, `config`, `init` -- pulled in the tools
+and with them pydantic and the OpenHands SDK. So the control plane's `proxy
+down` could not even check a pid without the agent framework (`docs/0047`).
+"""
+__all__ = ["run", "TOOLS", "register_all"]
+
+
+def __getattr__(name: str):
+    if name == "run":
+        from .runner import run
+        return run
+    if name in ("TOOLS", "register_all"):
+        from . import tools
+        return getattr(tools, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

agentctl/runtime/citations.py

@@ -0,0 +1,179 @@
+r"""Check a scout's citation before believing it.
+
+`docs/0039` §7, fifteenth entry. The first live fan-out returned:
+
+    "The lease TTL is enforced in hook.py ... 900.0 seconds ...
+     cited at hook.py:13"
+
+The lease TTL is `store.py:63`, 60.0 seconds. `hook.py`'s 900.0 is the
+turn-affinity pin, a different timer — and `hook.py:13` is prose in a
+docstring about `tool_call_id`. Nothing malfunctioned: the scout read eight
+files, found *a* `ttl_s`, and reported it as *the* one, with a citation, in
+the format its prompt demanded.
+
+**Citation discipline did not help, because a citation is only as good as the
+check nobody performed.** This is that check.
+
+## What can and cannot be verified here
+
+Mechanically certain:
+
+* the file exists in the workspace,
+* the line number is within it,
+* what that line actually says.
+
+Mechanically useful, and what caught the live failure: **does the value the
+claim asserts appear where the claim says it does?** `900.0` is 81 lines from
+`hook.py:13`, and saying so is enough to stop a reader believing it.
+
+Not verifiable here, and not attempted: whether the claim is *true*. A line
+can exist, contain the token, and still not support the sentence wrapped
+around it. This narrows what must be read by hand; it does not replace
+reading.
+
+**A citation that fails these checks is not a false claim, and a citation
+that passes is not a true one.** The output says which check ran.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+#: `store.py:63`, `agentctl/kernel/hook.py:94`, with optional backticks.
+_CITE = re.compile(r"`?([\w./\\-]+\.[A-Za-z]\w*):(\d+)`?")
+
+#: Tokens worth looking for at the cited line: decimals, backticked spans,
+#: and identifiers distinctive enough that finding one means something.
+#: Bare short words are deliberately excluded — "the" appearing near a line
+#: would corroborate nothing.
+_NUMBER = re.compile(r"\b\d+\.\d+\b|\b\d{2,}\b")
+_BACKTICK = re.compile(r"`([^`\n]{2,40})`")
+_IDENT = re.compile(r"\b([A-Za-z_][A-Za-z0-9_]{4,})\b")
+
+#: How far from the cited line a token still counts as "there". Small on
+#: purpose: a citation that is 80 lines out is the failure being caught.
+WINDOW = 3
+
+
+@dataclass
+class Citation:
+    path: str
+    line: int
+    resolved: Path | None = None
+    text: str | None = None
+    problem: str | None = None
+    #: (token, line where it actually is, or None if nowhere in the file)
+    misplaced: list[tuple[str, int | None]] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return self.problem is None and not self.misplaced
+
+
+def _tokens(context: str) -> list[str]:
+    """Distinctive things the claim asserts, worth finding at the line."""
+    out: list[str] = []
+    for m in _BACKTICK.findall(context):
+        m = m.strip()
+        # A backticked path:line is the citation itself, not a claim about it.
+        if not _CITE.fullmatch(m) and len(m) >= 2:
+            out.append(m)
+    out += _NUMBER.findall(context)
+    out += [t for t in _IDENT.findall(context)
+            if "_" in t or not t.islower()]
+    # Stable order, no duplicates, and nothing that is just the filename.
+    seen, keep = set(), []
+    for t in out:
+        low = t.lower()
+        if low in seen or low.endswith((".py", ".md", ".yaml")):
+            continue
+        seen.add(low)
+        keep.append(t)
+    return keep[:6]
+
+
+def find(report: str) -> list[tuple[str, int, str]]:
+    """Every `path:line` in the report, with the sentence around it."""
+    out = []
+    for m in _CITE.finditer(report):
+        start = max(0, m.start() - 220)
+        end = min(len(report), m.end() + 80)
+        out.append((m.group(1), int(m.group(2)), report[start:end]))
+    return out
+
+
+def check(path: str, line: int, context: str, workspace: str | Path,
+          window: int = WINDOW) -> Citation:
+    """Resolve one citation and test the claim's tokens against it."""
+    c = Citation(path=path, line=line)
+    ws = Path(workspace).resolve()
+
+    candidate = (ws / path).resolve()
+    if not str(candidate).startswith(str(ws)):
+        c.problem = "cites a path outside the workspace"
+        return c
+    if not candidate.is_file():
+        hits = list(ws.rglob(Path(path).name))
+        c.problem = ("no such file in the workspace"
+                     + (f"; closest match {hits[0].relative_to(ws)}"
+                        if len(hits) == 1 else ""))
+        return c
+    c.resolved = candidate
+
+    try:
+        lines = candidate.read_text(encoding="utf-8",
+                                    errors="replace").splitlines()
+    except Exception as e:                              # noqa: BLE001
+        c.problem = f"unreadable: {type(e).__name__}"
+        return c
+
+    if not 1 <= line <= len(lines):
+        c.problem = f"line {line} is past the end of the file ({len(lines)})"
+        return c
+    c.text = lines[line - 1].strip()
+
+    lo, hi = max(0, line - 1 - window), min(len(lines), line + window)
+    near = "\n".join(lines[lo:hi]).lower()
+    # Strip the citations themselves first. `store.py:63` otherwise yields the
+    # token `63`, and "63 is not at line 63" flags a correct report -- a
+    # verifier that cries wolf on good citations trains you to ignore it,
+    # which is worse than not checking at all.
+    for tok in _tokens(_CITE.sub(" ", context)):
+        if tok.lower() in near:
+            continue
+        where = next((i + 1 for i, l in enumerate(lines)
+                      if tok.lower() in l.lower()), None)
+        c.misplaced.append((tok, where))
+    return c
+
+
+def verify(report: str, workspace: str | Path,
+           window: int = WINDOW) -> list[Citation]:
+    """Every citation in a scout's report, checked."""
+    return [check(p, n, ctx, workspace, window) for p, n, ctx in find(report)]
+
+
+def describe(cites: list[Citation]) -> str:
+    """What a reader needs to decide whether to believe the report."""
+    if not cites:
+        return ("  no citation to check -- this report asserts things it does "
+                "not point at, so none of it has been verified.")
+    out = []
+    for c in cites:
+        if c.problem:
+            out.append(f"  !!  {c.path}:{c.line}  {c.problem}")
+            continue
+        if c.misplaced:
+            out.append(f"  !!  {c.path}:{c.line}  says: {(c.text or '')[:56]}")
+            for tok, where in c.misplaced:
+                loc = f"line {where}" if where else "nowhere in this file"
+                out.append(f"        {tok!r} is not there -- it is at {loc}")
+            continue
+        out.append(f"  ok  {c.path}:{c.line}  {(c.text or '')[:60]}")
+    bad = sum(1 for c in cites if not c.ok)
+    if bad:
+        out.append(f"      {bad} of {len(cites)} citation(s) did not check "
+                   f"out. A citation that fails is not a false claim -- it is "
+                   f"one nobody can take on trust.")
+    return "\n".join(out)

agentctl/runtime/config.py

@@ -0,0 +1,97 @@
+"""Where `agentctl run` gets its defaults. `docs/0043` Phase 2.
+
+Phase 0 (`docs/0044`) needed `--workspace`, `--model`, `--base-url` and
+`--ledger` on almost every command, and the built-in model was one OpenRouter
+id: a user holding only a Gemini or Anthropic key was handed a default that
+could not work.
+
+Precedence, highest first:
+
+    a flag on the command line
+    an environment variable     AGENTCTL_MODEL, AGENTCTL_BASE_URL
+    ~/.agentctl/config.toml     written by `agentctl init`, editable
+    derived                     the default model of the first provider you
+                                hold a key for, free tiers first
+
+`resolve()` reports which of these each value came from, because a default
+nobody can trace is the confidently-wrong shape `docs/0039` is about.
+"""
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+#: Keys this file owns. Anything else in config.toml is kept but not read.
+KEYS = ("model", "base_url")
+ENV = {"model": "AGENTCTL_MODEL", "base_url": "AGENTCTL_BASE_URL"}
+
+
+def path() -> Path:
+    """`~/.agentctl/config.toml`, or `AGENTCTL_CONFIG` when set."""
+    if (p := os.environ.get("AGENTCTL_CONFIG")):
+        return Path(p)
+    return Path.home() / ".agentctl" / "config.toml"
+
+
+def load(p: Path | None = None) -> dict:
+    p = p or path()
+    if not p.exists():
+        return {}
+    try:
+        return tomllib.loads(p.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as e:
+        # A broken config must not silently fall back to a different model.
+        raise SystemExit(f"{p} is not valid TOML: {e}\n"
+                         f"  fix it, or delete it and run `agentctl init`")
+
+
+def write(values: dict, p: Path | None = None, note: str = "") -> Path:
+    """Write the keys this module owns. Values are plain strings."""
+    p = p or path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    lines = ["# Written by `agentctl init`. Edit freely; a flag or an",
+             "# AGENTCTL_* environment variable still wins over anything here."]
+    if note:
+        lines += [f"# {line}" for line in note.splitlines()]
+    lines.append("")
+    for k in KEYS:
+        if values.get(k):
+            v = str(values[k]).replace("\\", "\\\\").replace('"', '\\"')
+            lines.append(f'{k} = "{v}"')
+    p.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return p
+
+
+def derived_model() -> str | None:
+    """The default model of the first provider holding a key, free first.
+
+    The registry's first model per provider is the one `init` would try
+    first. Without `init` it is unverified -- `resolve` says so.
+    """
+    from agentctl.control.providers import configured
+
+    for p in configured():
+        if p.default_model:
+            return p.default_model
+    return None
+
+
+@dataclass(frozen=True)
+class Setting:
+    value: str | None
+    source: str                 # "flag" | "env AGENTCTL_MODEL" | "config" | ...
+
+
+def resolve(name: str, flag: str | None, cfg: dict | None = None) -> Setting:
+    if flag:
+        return Setting(flag, "flag")
+    if (v := os.environ.get(ENV[name])):
+        return Setting(v, f"env {ENV[name]}")
+    cfg = load() if cfg is None else cfg
+    if cfg.get(name):
+        return Setting(str(cfg[name]), f"config {path()}")
+    if name == "model" and (m := derived_model()):
+        return Setting(m, "derived from your keys (unverified: `agentctl init` checks it)")
+    return Setting(None, "unset")