subtask-mcp 0.2.3__py3-none-any.whl

subtask/events.py

@@ -0,0 +1,105 @@
+"""Per-job event log: what really happened, in order. Feeds progress and the narrator.
+
+One JSON line per event in jobs/<id>/progress.jsonl:
+{"v":1,"job":..,"attempt":..,"seq":..,"ts":..,"phase":..,"state":..,"msg":..,"source":..}
+
+Writers take an flock so `seq` is strictly increasing across processes.
+Transient activity is capped per job; lifecycle and terminal events always land.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import time
+from pathlib import Path
+
+from . import config
+from .redact import redact
+
+VERSION = 1
+NAME = "progress.jsonl"
+MAX_TRANSIENT = 2000  # activity lines per job; terminal and lifecycle events are never dropped
+TERMINAL = {"done", "failed", "stopped"}
+
+
+def _path(job_id: str) -> Path:
+    return config.JOBS / job_id / NAME
+
+
+def emit(
+    job_id: str,
+    phase: str,
+    msg: str = "",
+    state: str | None = None,
+    source: str = "lifecycle",
+    attempt: int | None = None,
+) -> dict | None:
+    path = _path(job_id)
+    if not path.parent.is_dir():
+        return None
+    with path.open("a+", encoding="utf-8") as fh:
+        fcntl.flock(fh, fcntl.LOCK_EX)
+        last = _last(fh)
+        seq = int(last.get("seq", 0)) + 1
+        if source != "lifecycle" and state not in TERMINAL and seq > MAX_TRANSIENT:
+            return None
+        event = {
+            "v": VERSION,
+            "job": job_id,
+            "attempt": attempt,
+            "seq": seq,
+            "ts": round(time.time(), 3),
+            "phase": phase,
+            "state": state,
+            "msg": redact(msg)[:200],
+            "source": source,
+        }
+        fh.seek(0, os.SEEK_END)
+        fh.write(json.dumps(event, ensure_ascii=False) + "\n")
+        fh.flush()
+    return event
+
+
+def _last(fh) -> dict:
+    fh.seek(0, os.SEEK_END)
+    size = fh.tell()
+    fh.seek(max(0, size - 4096))
+    lines = fh.read().splitlines()
+    for line in reversed(lines):
+        try:
+            return json.loads(line)
+        except json.JSONDecodeError:
+            continue
+    return {}
+
+
+def read_since(job_id: str, offset: int = 0, limit: int = 500) -> tuple[list[dict], int]:
+    """Events after byte `offset`, and the new offset. Bounded: reads at most `limit` lines."""
+    path = _path(job_id)
+    try:
+        with path.open("rb") as fh:
+            fh.seek(offset)
+            out: list[dict] = []
+            while len(out) < limit:
+                line = fh.readline()
+                if not line or not line.endswith(b"\n"):
+                    break  # a half-written line is read next time
+                offset = fh.tell()
+                try:
+                    out.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+            return out, offset
+    except FileNotFoundError:
+        return [], offset
+
+
+def last(job_id: str) -> dict:
+    path = _path(job_id)
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            return _last(fh)
+    except FileNotFoundError:
+        return {}

subtask/evidence.py

@@ -0,0 +1,103 @@
+"""ResultEnvelope: what happened, with the source of every claim.
+
+Levels:
+- runner_observed: read by subtask itself (git refs, diff, commands seen in the engine's event stream);
+- worker_reported: what the worker wrote (the summary); a claim, not a check;
+- independently_verified: the parent's `verify` command, run by subtask on the recorded head.
+No tests seen is reported as no tests, never as success.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from . import jobs, telemetry
+from .engines import registry
+
+VERSION = 1
+
+
+def _git(repo: str, *args: str) -> str | None:
+    try:
+        done = subprocess.run(
+            ["git", "-C", repo, *args], capture_output=True, text=True, timeout=30, check=False
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return done.stdout.strip() if done.returncode == 0 else None
+
+
+def envelope(job_id: str) -> dict:
+    from .core import summary_of
+
+    st, sp = jobs.status(job_id), jobs.spec(job_id)
+    folder = jobs.job_dir(job_id)
+    text = (folder / "result.md").read_text() if (folder / "result.md").is_file() else ""
+    adapter = registry.get(sp.get("engine", ""))
+    attempts = st.get("attempts") or []
+    last = attempts[-1] if attempts else {}
+    git: dict = {"level": "runner_observed"}
+    if sp.get("branch") and sp.get("repo"):
+        repo, base, branch = sp["repo"], sp["base"], sp["branch"]
+        head = _git(repo, "rev-parse", branch)
+        names = _git(repo, "diff", "--name-only", f"{base}..{branch}") or ""
+        git.update(
+            base=base,
+            head=head,
+            branch=branch,
+            commits=int(_git(repo, "rev-list", "--count", f"{base}..{branch}") or 0),
+            changed_files=[n for n in names.splitlines() if n][:200],
+            uncommitted=bool(_git(sp["cwd"], "status", "--porcelain")) if sp.get("cwd") else None,
+        )
+    commands = [c for a in attempts for c in a.get("commands") or []]
+    tests = [c for c in commands if _is_test(c.get("command", ""))]
+    verification = st.get("verification")
+    cost = {
+        "unit": "USD",
+        "observed": last.get("cost_observed"),
+        "charged_total": st.get("cost_usd"),
+        "reserved": sp.get("max_usd") if adapter and adapter.capabilities.paid else None,
+        "billing": adapter.capabilities.cost if adapter else "unknown",
+        "note": "charged = observed, or the whole reservation when the real cost is unknown",
+    }
+    return {
+        "v": VERSION,
+        "id": job_id,
+        "engine": sp.get("engine"),
+        "model": sp.get("model") or (adapter.model if adapter else None),
+        "kind": sp.get("kind"),
+        "state": st.get("state"),
+        "detail": st.get("detail"),
+        "policy": sp.get("policy"),
+        "verification": verification
+        or {"level": "independently_verified", "status": "not_run", "note": "start(verify=...) to enable"},
+        "git": git,
+        "commands": {"level": "runner_observed", "seen": len(commands), "tests": tests[-20:]},
+        "tests_status": _tests_status(tests),
+        "summary": {"level": "worker_reported", "text": summary_of(text)},
+        "cost": cost,
+        "tokens": {
+            "level": "runner_observed" if last.get("tokens") else "missing",
+            **(last.get("tokens") or {}),
+        },
+        "attempts": len(attempts),
+        "round_trips": len(telemetry.calls(job_id)),
+        "error": st.get("error"),
+    }
+
+
+def _is_test(command: str) -> bool:
+    low = command.lower()
+    return any(
+        k in low
+        for k in ("pytest", "npm test", "go test", "cargo test", "unittest", "jest", "vitest", "make test")
+    )
+
+
+def _tests_status(tests: list[dict]) -> str:
+    if not tests:
+        return "none_observed"
+    codes = [t.get("exit_code") for t in tests]
+    if codes[-1] is None:
+        return "observed_exit_unknown"
+    return "last_passed" if codes[-1] == 0 else "last_failed"

subtask/fastserver.py

@@ -0,0 +1,272 @@
+"""MCP server (stdio) without the mcp library: JSON-RPC by hand, ~10x faster start.
+
+Dual-era (MCP 2026-07-28 "Versioning and Compatibility"):
+- modern requests carry `_meta["io.modelcontextprotocol/protocolVersion"]` and
+  are served statelessly, with `resultType` and `serverInfo` in every result;
+  `server/discover` answers; unknown versions get UnsupportedProtocolVersion (-32022);
+- legacy clients open with `initialize` (2025-11-25 and earlier) and keep the
+  negotiated revision for this process.
+
+Progress: a tools/call with `_meta.progressToken` gets `notifications/progress`
+while it runs (see progress.py). `notifications/cancelled` ends the call: no
+further message is sent for it, and the jobs keep running (stop() stops work).
+
+Importing the mcp package costs ~560 ms; this file answers before `core` is
+even imported. Tool names, descriptions and schemas come from tools.json,
+generated from server.py (`subtask-mcp-fastmcp --dump-tools`).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import time
+from pathlib import Path
+
+from . import __version__
+
+SPEC = json.loads((Path(__file__).with_name("tools.json")).read_text())
+MODERN = ("2026-07-28",)
+LEGACY = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+VERSIONS = MODERN + LEGACY
+SERVER_INFO = {"name": "subtask", "version": __version__}
+META = "io.modelcontextprotocol/"
+WAIT_TICK_S = 0.5
+CACHE = {"ttlMs": 3_600_000, "cacheScope": "public"}  # MUST on discover and tools/list (2026-07-28)
+
+_out = threading.Lock()
+_pending: list[threading.Thread] = []  # calls still running when the client closes stdin
+_core_lock = threading.Lock()  # quick state-changing tools run one at a time in this process
+_cancelled: dict[object, threading.Event] = {}
+_state: dict[str, str | None] = {"legacy": None}  # protocol version chosen by `initialize`
+
+
+def _send(msg: dict) -> None:
+    line = json.dumps(msg, ensure_ascii=False, separators=(",", ":")) + "\n"
+    with _out:  # one writer: lines never interleave
+        sys.stdout.write(line)
+        sys.stdout.flush()
+
+
+class Call:
+    """One in-flight tools/call: its id, progress token, cancellation and era."""
+
+    def __init__(self, msg_id: object, token: object, modern: bool) -> None:
+        self.id, self.token, self.modern = msg_id, token, modern
+        self.cancel = _cancelled.setdefault(msg_id, threading.Event())
+        self.reporter = None
+        if isinstance(token, (str, int)) and not isinstance(token, bool):
+            from .progress import Reporter
+
+            self.reporter = Reporter(self.progress)
+
+    def progress(self, value: float, message: str, total: float | None) -> None:
+        if self.cancel.is_set():
+            return  # MUST NOT send anything for a cancelled request
+        params: dict = {"progressToken": self.token, "progress": value, "message": message}
+        if total is not None:
+            params["total"] = total
+        _send({"jsonrpc": "2.0", "method": "notifications/progress", "params": params})
+
+    def sleep(self, seconds: float) -> bool:
+        """Sleep, polling progress; True when cancelled."""
+        end = time.monotonic() + seconds
+        while time.monotonic() < end:
+            if self.cancel.wait(min(WAIT_TICK_S, max(0.0, end - time.monotonic()))):
+                return True
+            if self.reporter:
+                self.reporter.poll()
+        return self.cancel.is_set()
+
+
+def _wait(
+    core, call: Call, ids: list[str], timeout: int = 300, any: bool = False, since: str | None = None
+) -> str:
+    deadline = time.monotonic() + max(1, min(int(timeout), 600))
+    if call.reporter:
+        for job_id in ids:
+            if core.known(job_id):
+                call.reporter.add(job_id)
+        call.reporter.poll()
+    while True:
+        out = core.wait(ids, 0, any, since=since)
+        if not out.startswith("still running") or time.monotonic() >= deadline:
+            if call.reporter:
+                call.reporter.poll()
+            return out
+        if call.sleep(1.0):
+            return "wait cancelled; jobs keep running"
+
+
+def _call(name: str, args: dict, call: Call) -> str:
+    from . import core
+
+    if name == "wait":
+        return _wait(core, call, **args)
+    if name == "stop":
+        if call.reporter:
+            call.reporter.add(args["id"])
+            call.reporter.phase(f"stopping {args['id']}", force=True)
+        return core.stop(args["id"])
+    if name == "step":
+        a = {"decisions": None, "repo": None, **args}
+        return core.step(a["title"], a["path"], a["how"], a["decisions"], a["repo"])
+    if name == "result":
+        return core.result(args["id"], args.get("full", False), args.get("evidence", False))
+    if name == "engines":
+        return core.engines() + "\n" + core.spend()
+    with _core_lock:
+        if name == "start":
+            return core.start(**_start_args(args), progress=call.reporter)
+        if name == "start_many":
+            return core.start_many(args["tasks"], progress=call.reporter)
+        if name == "status":
+            return core.status(args.get("id"))
+        if name == "reply":
+            return core.reply(args["id"], args["message"])
+        if name == "cleanup":
+            return core.cleanup(args["id"])
+    raise KeyError(name)
+
+
+START_ARGS = {
+    "task", "kind", "repo", "cwd", "files", "readonly", "engine", "max_usd", "effort",
+    "base", "max_turns", "policy", "verify",
+}  # fmt: skip
+
+
+def _start_args(args: dict) -> dict:
+    unknown = set(args) - START_ARGS
+    if unknown:
+        raise TypeError(f"unexpected argument(s): {', '.join(sorted(unknown))}")
+    if "task" not in args:
+        raise KeyError("task")
+    return args
+
+
+def _with_meta(modern: bool, payload: dict) -> dict:
+    if modern:
+        return {"resultType": "complete", **payload, "_meta": {META + "serverInfo": SERVER_INFO}}
+    return payload
+
+
+def _tool_call(msg_id: object, params: dict, modern: bool) -> None:
+    meta = params.get("_meta") or {}
+    call = Call(msg_id, meta.get("progressToken"), modern)
+    name, args = params.get("name", ""), params.get("arguments") or {}
+    try:
+        text, error = _call(name, args, call), False
+    except KeyError as exc:
+        text, error = f"unknown tool or missing argument: {exc}", True
+    except TypeError as exc:
+        text, error = f"bad arguments: {exc}", True
+    except Exception as exc:  # noqa: BLE001 - a tool error is a result, never a crash
+        text, error = f"{type(exc).__name__}: {exc}", True
+    finally:
+        _cancelled.pop(msg_id, None)
+    if call.cancel.is_set():
+        return  # cancelled: no response, no notification
+    from .redact import redact
+
+    payload = {"content": [{"type": "text", "text": redact(text)}], "isError": error}
+    _send({"jsonrpc": "2.0", "id": msg_id, "result": _with_meta(modern, payload)})
+
+
+def _error(msg_id: object, code: int, message: str, data: object = None) -> None:
+    err: dict = {"code": code, "message": message}
+    if data is not None:
+        err["data"] = data
+    _send({"jsonrpc": "2.0", "id": msg_id, "error": err})
+
+
+def _era(msg: dict) -> tuple[bool | None, str | None]:
+    """(modern?, problem). Modern when the request declares a version in _meta."""
+    meta = (msg.get("params") or {}).get("_meta") or {}
+    version = meta.get(META + "protocolVersion")
+    if version is None:
+        return False, None
+    if version not in VERSIONS:
+        return None, str(version)
+    if version not in MODERN:
+        return False, None  # a legacy version named per request: serve it as legacy
+    if META + "clientCapabilities" not in meta:
+        return None, "missing-capabilities"
+    return True, None
+
+
+def _handle(msg: dict) -> None:
+    method, msg_id = msg.get("method"), msg.get("id")
+    if msg_id is None:
+        if method == "notifications/cancelled":
+            event = _cancelled.get((msg.get("params") or {}).get("requestId"))
+            if event:
+                event.set()
+        return  # other notifications are never answered
+    if method == "initialize":
+        asked = (msg.get("params") or {}).get("protocolVersion")
+        chosen = asked if asked in LEGACY else LEGACY[0]
+        _state["legacy"] = chosen
+        result = {
+            "protocolVersion": chosen,
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": SERVER_INFO,
+            "instructions": SPEC["instructions"],
+        }
+        _send({"jsonrpc": "2.0", "id": msg_id, "result": result})
+        return
+    modern, problem = _era(msg)
+    if modern is None:
+        if problem == "missing-capabilities":
+            _error(msg_id, -32602, "Invalid params: missing _meta io.modelcontextprotocol/clientCapabilities")
+        else:
+            _error(
+                msg_id,
+                -32022,
+                "Unsupported protocol version",
+                {"supported": list(VERSIONS), "requested": problem},
+            )
+        return
+    if method == "server/discover":
+        result = {
+            "supportedVersions": list(VERSIONS),
+            "capabilities": {"tools": {"listChanged": False}},
+            "instructions": SPEC["instructions"],
+            **CACHE,
+        }
+        _send({"jsonrpc": "2.0", "id": msg_id, "result": _with_meta(True, result)})
+    elif method == "tools/list":
+        listing = {"tools": SPEC["tools"], **(CACHE if modern else {})}
+        _send({"jsonrpc": "2.0", "id": msg_id, "result": _with_meta(modern, listing)})
+    elif method == "tools/call":
+        _cancelled.setdefault(msg_id, threading.Event())  # a cancel may arrive before the thread runs
+        worker = threading.Thread(
+            target=_tool_call, args=(msg_id, msg.get("params") or {}, modern), daemon=True
+        )
+        worker.start()
+        _pending.append(worker)
+    elif method == "ping":
+        _send({"jsonrpc": "2.0", "id": msg_id, "result": _with_meta(modern, {})})
+    else:
+        _error(msg_id, -32601, f"no method {method}")
+
+
+def main() -> None:
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            _error(None, -32700, "parse error")
+            continue
+        if isinstance(msg, dict):
+            _handle(msg)
+        else:
+            _error(None, -32600, "invalid request")
+    for worker in _pending:
+        worker.join(timeout=30)  # stdin closed: still answer the calls already received
+
+
+if __name__ == "__main__":
+    main()

subtask/gc.py

@@ -0,0 +1,99 @@
+"""Retention and disk usage: report first, delete only with --apply, never user work.
+
+Removable: folders of finished jobs older than the retention, whose worktree is
+already gone or clean (no uncommitted and no ignored files), telemetry older
+than its retention. Never removed: active jobs, dirty worktrees, branches.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+from . import config, jobs, telemetry
+
+RETENTION_DAYS = int(os.environ.get("SUBTASK_JOB_RETENTION_DAYS", "30"))
+
+
+def _size(path: Path) -> int:
+    total = 0
+    for root, _dirs, files in os.walk(path):
+        for name in files:
+            try:
+                total += (Path(root) / name).lstat().st_size
+            except OSError:
+                continue
+    return total
+
+
+def du() -> dict:
+    parts = {
+        "jobs": config.JOBS,
+        "worktrees": config.WORKTREES,
+        "ledger": config.HOME / "ledger",
+        "telemetry": config.HOME / "telemetry",
+    }
+    return {name: _size(path) if path.exists() else 0 for name, path in parts.items()}
+
+
+def _worktree_clean(path: str) -> bool | None:
+    if not Path(path).exists():
+        return None
+    done = subprocess.run(
+        ["git", "-C", path, "status", "--porcelain", "--ignored"], capture_output=True, text=True, check=False
+    )
+    return done.returncode == 0 and not done.stdout.strip()
+
+
+def plan(days: int = RETENTION_DAYS) -> list[dict]:
+    cutoff = time.time() - days * 86400
+    out = []
+    for job_id in jobs.all_jobs():
+        folder = jobs.job_dir(job_id)
+        st, sp = jobs.status(job_id), jobs.spec(job_id)
+        if st.get("state") not in jobs.FINAL:
+            continue
+        if float(st.get("updated") or folder.stat().st_mtime) > cutoff:
+            continue
+        item = {"job": job_id, "folder": str(folder), "bytes": _size(folder), "worktree": None}
+        if sp.get("branch") and sp.get("cwd"):
+            clean = _worktree_clean(sp["cwd"])
+            if clean is False:
+                item["skip"] = "worktree has uncommitted or ignored files"
+            elif clean:
+                item["worktree"] = sp["cwd"]
+        out.append(item)
+    return out
+
+
+def run(days: int = RETENTION_DAYS, apply: bool = False) -> str:
+    items = plan(days)
+    old_telemetry = telemetry.prune(dry_run=not apply)
+    removed = kept = freed = 0
+    lines = []
+    for item in items:
+        if item.get("skip"):
+            kept += 1
+            lines.append(f"keep {item['job']}: {item['skip']}")
+            continue
+        if apply:
+            if item["worktree"]:
+                sp = jobs.spec(item["job"])
+                done = subprocess.run(["git", "-C", sp["repo"], "worktree", "remove", item["worktree"]],
+                                      capture_output=True, text=True, check=False)  # fmt: skip
+                if done.returncode != 0:
+                    kept += 1
+                    lines.append(f"keep {item['job']}: worktree not removed ({done.stderr.strip()[:80]})")
+                    continue
+            shutil.rmtree(item["folder"])
+        removed += 1
+        freed += item["bytes"]
+    verb = "removed" if apply else "would remove"
+    head = f"{verb} {removed} job folders ({freed / 1e6:.1f} MB), kept {kept}; {verb} {len(old_telemetry)} telemetry files"
+    usage = ", ".join(f"{k} {v / 1e6:.1f} MB" for k, v in du().items())
+    return "\n".join(
+        [head, f"disk: {usage}", *lines[:20]] + ([] if apply else ["(dry run: add --apply to delete)"])
+    )

subtask/install/__init__.py

@@ -0,0 +1 @@
+"""Client installers: register the subtask MCP server and skill in coding-agent apps."""