subtask-mcp 0.2.3__py3-none-any.whl

subtask/ledger.py

@@ -0,0 +1,268 @@
+"""Spend ledger: reservations against a monthly cap, closed exactly once.
+
+Files: <HOME>/ledger/YYYY-MM.jsonl, one JSON row per operation, under one lock
+(<HOME>/ledger/.lock) so check-then-reserve is atomic across processes.
+
+Row v2: {"v":2,"ts":..,"op":"reserve"|"settle"|"release","rid":..,"job":..,"usd":..,"month":"YYYY-MM"}
+- reserve: books `usd` against the cap of `month` (the month it was made in);
+- settle: closes the reservation with the cost actually charged;
+- release: closes it at zero (nothing could have been spent).
+A closing row goes to the file of its reservation's month, so a job that
+crosses midnight at month end is charged once, to the month it was admitted in.
+A second close of the same rid is a no-op (idempotent settlement).
+
+The v0 single file ledger.jsonl is migrated once; the original is kept as
+ledger.jsonl.v0.bak (rollback: move it back and delete the ledger folder).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import math
+import os
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from . import config
+
+VERSION = 2
+
+
+def _dir() -> Path:
+    return config.HOME / "ledger"
+
+
+def month_of(ts: str | None = None) -> str:
+    return (ts or now())[:7]
+
+
+def now() -> str:
+    t = time.time()
+    return time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(t)) + f".{int(t % 1 * 1e6):06d}+00:00"
+
+
+@contextmanager
+def locked() -> Iterator[None]:
+    folder = _dir()
+    folder.mkdir(parents=True, exist_ok=True)
+    with (folder / ".lock").open("a") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        _migrate_v0()
+        yield
+
+
+def _rows(month: str) -> list[dict]:
+    path = _dir() / f"{month}.jsonl"
+    try:
+        lines = path.read_text().splitlines()
+    except FileNotFoundError:
+        return []
+    out = []
+    for line in lines:
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            continue  # a torn last line after a crash: ignored, never fatal
+        if isinstance(row, dict):
+            out.append(row)
+    return out
+
+
+def _append(month: str, row: dict) -> None:
+    path = _dir() / f"{month}.jsonl"
+    with path.open("ab+") as fh:
+        fh.seek(0, 2)
+        if fh.tell():
+            fh.seek(-1, 2)
+            if fh.read(1) != b"\n":
+                fh.write(b"\n")  # a torn last line must not swallow this row
+        fh.write((json.dumps(row) + "\n").encode())
+        fh.flush()
+        os.fsync(fh.fileno())
+
+
+def _months() -> list[str]:
+    if not _dir().is_dir():
+        return []
+    return sorted((p.stem for p in _dir().glob("????-??.jsonl")), reverse=True)
+
+
+def _usd(value: object) -> float | None:
+    """A finite, non-negative amount, or None."""
+    try:
+        amount = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+    return amount if math.isfinite(amount) and amount >= 0 else None
+
+
+def _summary(month: str) -> tuple[float, dict[str, dict], set[str]]:
+    """(settled usd, open reservations by rid, closed rids) for one month."""
+    settled, open_, closed = 0.0, {}, set()
+    for row in _rows(month):
+        op, rid = row.get("op"), row.get("rid")
+        if op == "reserve" and rid not in closed:
+            open_[rid] = row
+        elif op in ("settle", "release") and rid not in closed:
+            closed.add(rid)
+            open_.pop(rid, None)
+            settled += _usd(row.get("usd")) or 0.0
+    return settled, open_, closed
+
+
+def _committed(month: str) -> float:
+    settled, open_, _ = _summary(month)
+    return settled + sum(_usd(r.get("usd")) or 0.0 for r in open_.values())
+
+
+def committed(month: str | None = None) -> float:
+    """Spent plus still reserved this month (what counts against the cap)."""
+    with locked():
+        return _committed(month or month_of())
+
+
+def reserve(rid: str, job: str, usd: float, cap: float | None = None) -> float | None:
+    """Book `usd`; None when it would overshoot the cap or is not a sane amount.
+
+    Idempotent per rid: reserving an rid that already exists returns None.
+    """
+    if not isinstance(usd, (int, float)) or not math.isfinite(usd) or usd <= 0:
+        return None
+    cap = config.MONTHLY_CAP_USD if cap is None else cap
+    with locked():
+        month = month_of()
+        if _find(rid) is not None:
+            return None
+        total = _committed(month)
+        if total + usd > cap:
+            return None
+        _append(
+            month,
+            {
+                "v": VERSION,
+                "ts": now(),
+                "op": "reserve",
+                "rid": rid,
+                "job": job,
+                "usd": float(usd),
+                "month": month,
+            },
+        )
+        return total + usd
+
+
+def _find(rid: str) -> tuple[str, dict | None] | None:
+    """(month, open reserve row or None if closed) for an rid, newest month first."""
+    for month in _months():
+        _, open_, closed = _summary(month)
+        if rid in open_:
+            return month, open_[rid]
+        if rid in closed:
+            return month, None
+    return None
+
+
+def close(rid: str, usd: float, op: str = "settle") -> float | None:
+    """Close an open reservation once. Returns what was booked, None when nothing was open.
+
+    A settle is capped at the reservation (the cap must hold); an unknown cost
+    (NaN, inf, negative, not a number) is charged the whole reservation. Both
+    cases are noted on the row.
+    """
+    if op not in ("settle", "release"):
+        raise ValueError(op)
+    reported = _usd(usd)
+    with locked():
+        found = _find(rid)
+        if not found or found[1] is None:
+            return None
+        month, row = found[0], found[1] or {}
+        reserved = _usd(row.get("usd")) or 0.0
+        booked = 0.0 if op == "release" else reserved if reported is None else min(reported, reserved)
+        closing = {"v": VERSION, "ts": now(), "op": op, "rid": rid, "job": row.get("job"),
+                   "usd": round(booked, 6), "month": month}  # fmt: skip
+        if op == "settle" and reported is None:
+            closing["note"] = "unknown cost: charged the reservation"
+        elif op == "settle" and reported > reserved:
+            closing["note"] = f"reported {reported:.4f} above the reservation: capped"
+        _append(month, closing)
+        return booked
+
+
+def is_open(rid: str) -> bool:
+    with locked():
+        found = _find(rid)
+        return bool(found and found[1] is not None)
+
+
+def open_for(job: str) -> list[dict]:
+    with locked():
+        out = []
+        for month in _months()[:3]:
+            _, open_, _ = _summary(month)
+            out += [r for r in open_.values() if r.get("job") == job]
+        return out
+
+
+def spend_rows(month: str | None = None) -> list[dict]:
+    with locked():
+        return _rows(month or month_of())
+
+
+def _migrate_v0() -> None:
+    """Split the v0 single-file ledger into monthly v2 files, once (lock held).
+
+    Rows that cannot be read are skipped and listed in ledger-migration.log; an
+    unreadable cost closes its reservation at the reserved amount (prudential).
+    """
+    old = config.HOME / "ledger.jsonl"
+    if not old.is_file():
+        return
+    counters: dict[str, int] = {}
+    open_rid: dict[str, tuple[str, float]] = {}
+    skipped: list[str] = []
+
+    def row_for(op: str, rid: str, job: str, usd: float, ts: str, month: str) -> dict:
+        return {"v": VERSION, "ts": ts, "op": op, "rid": rid, "job": job, "usd": usd, "month": month}
+
+    for line in old.read_text(errors="replace").splitlines():
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            if line.strip():
+                skipped.append(line[:200])
+            continue
+        if not isinstance(row, dict):
+            skipped.append(line[:200])
+            continue
+        job, ts = str(row.get("job", "?")), str(row.get("ts") or now())
+        month = month_of(ts) if len(ts) >= 7 and ts[4] == "-" else month_of()
+        if "reserve_usd" in row:
+            usd = _usd(row["reserve_usd"])
+            if usd is None:
+                skipped.append(line[:200])
+                continue
+            counters[job] = counters.get(job, 0) + 1
+            rid = f"{job}#v0-{counters[job]}"
+            open_rid[job] = (rid, usd)
+            _append(month, row_for("reserve", rid, job, usd, ts, month))
+            continue
+        cost = _usd(row.get("cost_usd") or 0)
+        pending = open_rid.pop(job, None)
+        if pending is None:
+            if cost is None:
+                skipped.append(line[:200])
+                continue
+            counters[job] = counters.get(job, 0) + 1
+            rid = f"{job}#v0-{counters[job]}"
+            _append(month, row_for("reserve", rid, job, cost, ts, month))
+            _append(month, row_for("settle", rid, job, cost, ts, month))
+            continue
+        rid, reserved = pending
+        _append(month, row_for("settle", rid, job, reserved if cost is None else cost, ts, month))
+    if skipped:
+        (config.HOME / "ledger-migration.log").write_text("skipped v0 rows:\n" + "\n".join(skipped) + "\n")
+    old.rename(old.with_name("ledger.jsonl.v0.bak"))

subtask/narrate.py

@@ -0,0 +1,134 @@
+"""Independent narrator for significant steps.
+
+A separate model (not the agent doing the work) reads the step the agent
+declared plus the repository's real state, and explains it to the user in
+plain words, pointing out anything that does not add up. One direct Messages
+API call: fast and cheap, no agent loop, no tools.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+import urllib.request
+
+from . import config, ledger
+
+# (model, USD per million input tokens, USD per million output tokens).
+# Override when prices change.
+EXPLAINER = (
+    os.environ.get("SUBTASK_STEP_MODEL", "claude-haiku-5-5"),
+    config._money("SUBTASK_STEP_PRICE_IN", "1"),
+    config._money("SUBTASK_STEP_PRICE_OUT", "5"),
+)
+RESERVE_USD = 0.05
+MAX_CONTEXT = 6000
+
+EXPLAIN = (
+    "You are an independent observer. A coding agent is about to take a step. "
+    "You did not plan it. Explain it to the operator, who is smart but not technical: "
+    "what the agent is about to do, which road it takes, how, and the decisions it made "
+    "and why. Short sentences, plain words, no em dashes, bullets, at most 6 lines. "
+    "Keep two things apart: what the agent DECLARES it will do (an intention) and what "
+    "the repository state and the observed job activity SHOW (facts). If they disagree, say so. "
+    "Never invent facts. Write in this language: {lang}."
+)
+
+
+def _git(repo: str, *args: str) -> str:
+    try:
+        done = subprocess.run(
+            ["git", "-C", repo, *args], capture_output=True, text=True, timeout=10, check=False
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    return done.stdout.strip() if done.returncode == 0 else ""
+
+
+def repo_context(repo: str) -> str:
+    parts = [
+        ("branch", _git(repo, "branch", "--show-current")),
+        ("last commits", _git(repo, "log", "--oneline", "-5")),
+        ("changed files", "\n".join(_git(repo, "status", "--short").splitlines()[:30])),
+        (
+            "diff size",
+            _git(repo, "diff", "--stat", "HEAD").splitlines()[-1:]
+            and _git(repo, "diff", "--stat", "HEAD").splitlines()[-1],
+        ),
+    ]
+    parts.append(("observed sub-task activity", observed_activity(repo)))
+    text = "\n\n".join(f"{k}:\n{v}" for k, v in parts if v)
+    return text[:MAX_CONTEXT] or "(not a git repository)"
+
+
+def observed_activity(repo: str, limit: int = 5) -> str:
+    """Last real event of the active sub-tasks working on this repository (no model involved)."""
+    from . import admission, events, jobs
+
+    lines = []
+    try:
+        active = admission.active()
+    except OSError:
+        return ""
+    for job_id in active[:limit]:
+        spec = jobs.spec(job_id)
+        if spec.get("repo") != repo and spec.get("cwd") != repo:
+            continue
+        last = events.last(job_id)
+        lines.append(f"{job_id} {spec.get('engine')}: {last.get('phase', '?')} {last.get('msg', '')}"[:150])
+    return "\n".join(lines)
+
+
+def _call(spec: tuple[str, float, float], system: str, user: str) -> str:
+    """One Messages API call, booked in the ledger. Raises on any failure."""
+    model, price_in, price_out = spec
+    secrets = config.load_secrets()
+    key = secrets.get("ANTHROPIC_API_KEY")
+    if not key:
+        raise RuntimeError("no API key")
+    job = f"step-{time.time_ns()}"
+    rid = f"{job}#1"
+    if ledger.reserve(rid, job, RESERVE_USD) is None:
+        raise RuntimeError("monthly cap reached")
+    cost = 0.0
+    try:
+        body = {
+            "model": model,
+            "max_tokens": 800,
+            # Sonnet 5.5 refuses "disabled"; "between_tools" means no thinking there.
+            "thinking": {"type": "between_tools" if "sonnet-5" in model else "disabled"},
+            "system": system,
+            "messages": [{"role": "user", "content": user}],
+        }
+        headers = {
+            "x-api-key": key,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        }
+        if secrets.get("ANTHROPIC_WORKSPACE_ID"):
+            headers["anthropic-workspace-id"] = secrets["ANTHROPIC_WORKSPACE_ID"]
+        req = urllib.request.Request(
+            "https://api.anthropic.com/v1/messages", data=json.dumps(body).encode(), headers=headers
+        )
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            data = json.load(resp)
+        usage = data.get("usage", {})
+        cost = (usage.get("input_tokens", 0) * price_in + usage.get("output_tokens", 0) * price_out) / 1e6
+        return "".join(b.get("text", "") for b in data.get("content", []) if b.get("type") == "text").strip()
+    finally:
+        ledger.close(rid, cost)
+
+
+def review(step_text: str, repo: str, lang: str) -> str:
+    """Explain the step with the cheap model: the text, or '(unavailable: reason)'.
+
+    Falsification does not run here: it belongs to finished, complex work and
+    runs as a separate sub-task on Sonnet.
+    """
+    user = f"Declared step:\n{step_text}\n\nRepository state:\n{repo_context(repo)}"
+    try:
+        return _call(EXPLAINER, EXPLAIN.format(lang=lang), user)
+    except Exception as exc:  # noqa: BLE001 - the step must never block the work
+        return f"(unavailable: {type(exc).__name__}: {str(exc)[:80]})"

subtask/policy.py

@@ -0,0 +1,58 @@
+"""Security policy: what a job demands, and whether an engine can enforce it.
+
+Levels, weakest first:
+- worktree: git isolation only. The agent can still read and write the rest of
+  the host as the same user. Not a sandbox.
+- sandbox: the engine's own sandbox for shell commands (Claude Code OS sandbox,
+  Codex workspace-write). Same user: a guard rail, not a strong boundary.
+- isolated: subtask runs the engine under bubblewrap: read-only system,
+  writable worktree and git dir only, a private HOME holding only the engine's
+  own state, new pid/ipc/uts namespaces.
+
+A job states a minimum. Engines that cannot enforce it are not eligible, and
+nothing downgrades silently: start() fails instead.
+"""
+
+from __future__ import annotations
+
+from .engines.base import LEVELS, Adapter
+
+DEFAULT_LEVEL = "worktree"
+
+
+def demand(readonly: bool = False, level: str | None = None, untrusted: bool = False) -> dict:
+    if level == "untrusted":  # shorthand: sandbox at least, network off for commands
+        level, untrusted = "sandbox", True
+    level = level or ("sandbox" if untrusted else DEFAULT_LEVEL)
+    if level not in LEVELS:
+        raise ValueError(f"policy must be one of {', '.join(LEVELS)}, untrusted")
+    if untrusted and LEVELS.index(level) < LEVELS.index("sandbox"):
+        raise ValueError("untrusted needs policy sandbox or isolated")
+    return {"level": level, "readonly": bool(readonly), "untrusted": bool(untrusted)}
+
+
+def effective(adapter: Adapter, wanted: dict) -> tuple[str | None, str]:
+    """(level the run will really have, reason). None = cannot satisfy."""
+    caps = adapter.capabilities
+    if wanted["readonly"]:
+        if not caps.readonly:
+            return None, f"{adapter.name} cannot run read-only"
+        return "readonly", "engine-enforced read-only"
+    if wanted["untrusted"] and not caps.command_network_off:
+        return None, f"{adapter.name} cannot deny network to commands (untrusted)"
+    floor = LEVELS.index(wanted["level"])
+    if wanted["level"] == "isolated":
+        if "isolated" in caps.levels:
+            return "isolated", "bubblewrap runner"
+        return None, f"{adapter.name} cannot run isolated"
+    # Strongest native level at or above the demand; isolation only when asked or needed.
+    native = [lvl for lvl in caps.levels if lvl != "isolated" and LEVELS.index(lvl) >= floor]
+    if native:
+        level = max(native, key=LEVELS.index)
+        return (
+            level,
+            "engine sandbox, same user" if level == "sandbox" else "git worktree only, not a host sandbox",
+        )
+    if "isolated" in caps.levels:
+        return "isolated", "bubblewrap runner (engine has no native sandbox)"
+    return None, f"{adapter.name} cannot enforce {wanted['level']}"

subtask/procid.py

@@ -0,0 +1,97 @@
+"""Process identity that survives PID reuse: pid + start time + boot id.
+
+`alive()` answers "alive", "dead" or "unknown". Only "dead" is proof: callers
+must not settle money or free a slot on "unknown".
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ALIVE, DEAD, UNKNOWN = "alive", "dead", "unknown"
+
+
+def boot_id() -> str:
+    try:
+        return Path("/proc/sys/kernel/random/boot_id").read_text().strip()
+    except OSError:
+        return ""
+
+
+def start_ticks(pid: int) -> str | None:
+    """Kernel start time of `pid` (clock ticks since boot on Linux, lstart elsewhere)."""
+    if Path("/proc/self/stat").exists():  # Linux: /proc is authoritative
+        try:
+            stat = Path(f"/proc/{pid}/stat").read_text()
+            return stat.rsplit(")", 1)[1].split()[19]  # field 22: starttime
+        except FileNotFoundError:
+            return None
+        except (OSError, IndexError):
+            pass
+    if sys.platform == "win32":
+        return None
+    try:
+        done = subprocess.run(
+            ["ps", "-o", "lstart=", "-p", str(pid)], capture_output=True, text=True, timeout=5, check=False
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return done.stdout.strip() or None
+
+
+def identity(pid: int | None = None) -> dict:
+    pid = os.getpid() if pid is None else pid
+    return {"pid": pid, "start": start_ticks(pid), "boot": boot_id()}
+
+
+def _exists(pid: int) -> bool | None:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return None
+    return True
+
+
+def alive(ident: dict | None) -> str:
+    if not isinstance(ident, dict) or not ident.get("pid"):
+        return UNKNOWN
+    try:
+        pid = int(ident["pid"])
+    except (TypeError, ValueError):
+        return UNKNOWN  # a corrupt identity proves nothing
+    if pid <= 0:
+        return UNKNOWN
+    try:
+        if os.waitpid(pid, os.WNOHANG)[0] == pid:
+            return DEAD  # our own child that exited: reaped now
+    except ChildProcessError:
+        pass
+    except OSError:
+        pass
+    if ident.get("boot") and boot_id() and ident["boot"] != boot_id():
+        return DEAD  # the machine rebooted since
+    exists = _exists(pid)
+    if exists is False:
+        return DEAD
+    if exists is None:
+        return UNKNOWN
+    if _zombie(pid):
+        return DEAD
+    recorded, now = ident.get("start"), start_ticks(pid)
+    if recorded and now:
+        return ALIVE if recorded == now else DEAD  # different start time: pid reused
+    return UNKNOWN  # exists, but its start time cannot be compared
+
+
+def _zombie(pid: int) -> bool:
+    try:
+        return Path(f"/proc/{pid}/stat").read_text().rsplit(")", 1)[1].split()[0] == "Z"
+    except (OSError, IndexError):
+        return False