subtask-mcp 0.2.3__py3-none-any.whl

subtask/__init__.py

@@ -0,0 +1,3 @@
+"""subtask: background sub-agents for coding agents."""
+
+__version__ = "0.2.3"

subtask/admission.py

@@ -0,0 +1,254 @@
+"""Global admission: at most MAX_RUNNING active jobs across every CLI and MCP process.
+
+The active index (<HOME>/active.json) is the source of truth for slots and is
+only changed under <HOME>/admission.lock. It is rebuildable: `rebuild()` scans
+job folders when the index is missing or corrupt. Entries:
+
+  {"job": id, "phase": "admitting"|"running", "owner": identity, "worker": identity|None, "since": ts}
+
+Lock order: a job lock, then admission.lock, then the ledger lock. Nothing
+slow (git, spawn, network) runs while admission.lock is held.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from . import config, procid
+
+ADMIT_GRACE_S = 120  # an 'admitting' entry whose owner is alive but silent this long is stale
+
+
+def _index() -> Path:
+    return config.HOME / "active.json"
+
+
+def _markers() -> Path:
+    """One file per job between admission and its first status: survives a corrupt index."""
+    return config.HOME / "admitting"
+
+
+@contextmanager
+def locked() -> Iterator[None]:
+    config.HOME.mkdir(parents=True, exist_ok=True)
+    with (config.HOME / "admission.lock").open("a") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        yield
+
+
+def _valid_ident(ident: object) -> bool:
+    if not isinstance(ident, dict):
+        return False
+    try:
+        return int(ident.get("pid")) > 0  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return False
+
+
+def _valid_entry(entry: object) -> bool:
+    if not isinstance(entry, dict) or not isinstance(entry.get("job"), str):
+        return False
+    for key in ("owner", "worker"):
+        if entry.get(key) is not None and not _valid_ident(entry[key]):
+            return False
+    return True
+
+
+def _read() -> dict[str, dict] | None:
+    """The index, or None when it is missing or corrupt (callers then rebuild)."""
+    try:
+        data = json.loads(_index().read_text())
+    except (FileNotFoundError, json.JSONDecodeError, OSError, UnicodeDecodeError):
+        return None
+    if not isinstance(data, dict) or not isinstance(data.get("jobs"), dict):
+        return None
+    return {k: v for k, v in data["jobs"].items() if _valid_entry(v)}  # a bad entry is dropped, not fatal
+
+
+def _write(entries: dict[str, dict]) -> None:
+    path = _index()
+    tmp = path.with_suffix(f".{os.getpid()}.tmp")
+    tmp.write_text(json.dumps({"v": 1, "jobs": entries}, indent=1))
+    os.replace(tmp, path)
+
+
+def _mark(entry: dict) -> None:
+    _markers().mkdir(parents=True, exist_ok=True)
+    tmp = _markers() / f".{entry['job']}.{os.getpid()}.tmp"
+    tmp.write_text(json.dumps(entry))
+    os.replace(tmp, _markers() / f"{entry['job']}.json")
+
+
+def _unmark(job_id: str) -> None:
+    (_markers() / f"{job_id}.json").unlink(missing_ok=True)
+
+
+def rebuild() -> dict[str, dict]:
+    """Index from the job folders (queued/running) and the admission markers."""
+    entries: dict[str, dict] = {}
+    if _markers().is_dir():
+        for path in _markers().glob("*.json"):
+            try:
+                entry = json.loads(path.read_text())
+            except (OSError, json.JSONDecodeError):
+                continue
+            if _valid_entry(entry):
+                entries[entry["job"]] = entry
+    if config.JOBS.is_dir():
+        for folder in config.JOBS.iterdir():
+            try:
+                status = json.loads((folder / "status.json").read_text())
+            except (OSError, json.JSONDecodeError):
+                continue
+            if status.get("state") in ("queued", "running"):
+                worker = status.get("proc") or ({"pid": status["pid"]} if status.get("pid") else None)
+                entry = entries.get(folder.name) or {"job": folder.name, "owner": None}
+                entry.update(
+                    phase="running" if worker else entry.get("phase", "running"),
+                    since=status.get("updated", time.time()),
+                )
+                if _valid_ident(worker):
+                    entry["worker"] = worker
+                entries[folder.name] = entry
+    return entries
+
+
+def _live(entry: dict) -> bool:
+    """False only with proof the entry no longer holds a slot."""
+    status, attempt = _job_state(entry["job"]), _job_attempt(entry["job"])
+    newer = entry.get("phase") == "admitting" and int(entry.get("attempt") or 1) > attempt
+    if status in ("done", "failed", "stopped") and not newer:
+        return False
+    if entry.get("phase") == "running":
+        worker = entry.get("worker")
+        if worker:
+            return procid.alive(worker) != procid.DEAD
+        return status in ("queued", "running", None)
+    owner = entry.get("owner")
+    verdict = procid.alive(owner) if owner else procid.UNKNOWN
+    if verdict == procid.DEAD:
+        return False
+    return not (verdict == procid.UNKNOWN and time.time() - float(entry.get("since") or 0) > ADMIT_GRACE_S)
+
+
+def _job_state(job_id: str) -> str | None:
+    try:
+        return json.loads((config.JOBS / job_id / "status.json").read_text()).get("state")
+    except (OSError, json.JSONDecodeError, AttributeError):
+        return None
+
+
+def _job_attempt(job_id: str) -> int:
+    try:
+        return int(json.loads((config.JOBS / job_id / "status.json").read_text()).get("attempt") or 1)
+    except (OSError, json.JSONDecodeError, AttributeError, TypeError, ValueError):
+        return 0
+
+
+def _drop(entry: dict) -> None:
+    """An entry lost its slot. If its job never got a status, nothing ran: release its money."""
+    _unmark(entry["job"])
+    if entry.get("phase") == "admitting" and _job_state(entry["job"]) is None:
+        from . import ledger
+
+        for row in ledger.open_for(entry["job"]):
+            ledger.close(row["rid"], 0.0, "release")
+
+
+def _current() -> dict[str, dict]:
+    entries = _read()
+    if entries is None:
+        entries = rebuild()
+    live = {}
+    for key, entry in entries.items():
+        if _live(entry):
+            live[key] = entry
+        else:
+            _drop(entry)
+    return live
+
+
+def admit(job_id: str, limit: int | None = None, attempt: int = 1) -> str | None:
+    """Take a slot for job_id. None on success, else the refusal reason. Caller holds nothing."""
+    with locked():
+        return admit_locked(job_id, limit, attempt)
+
+
+def admit_locked(job_id: str, limit: int | None = None, attempt: int = 1) -> str | None:
+    """Same as admit() for a caller already holding admission.lock."""
+    limit = config.MAX_RUNNING if limit is None else limit
+    entries = _current()
+    if len(entries) >= limit:
+        _write(entries)
+        return f"{limit} sub-tasks already running: use wait()"
+    entry = {
+        "job": job_id,
+        "attempt": attempt,
+        "phase": "admitting",
+        "owner": procid.identity(),
+        "worker": None,
+        "since": time.time(),
+    }
+    _mark(entry)
+    entries[job_id] = entry
+    _write(entries)
+    return None
+
+
+def running(job_id: str, worker: dict) -> None:
+    with locked():
+        entries = _read()
+        if entries is None:
+            entries = rebuild()
+        entries[job_id] = {
+            **entries.get(job_id, {"job": job_id}),
+            "phase": "running",
+            "worker": worker,
+            "since": time.time(),
+        }
+        _write(entries)
+        _unmark(job_id)
+
+
+def _mine(entry: dict) -> bool:
+    """May the calling process free this entry? Its owner or worker may; anyone may once they are dead."""
+    me = procid.identity()
+    holder = entry.get("worker") if entry.get("phase") == "running" else entry.get("owner")
+    if not holder:
+        return True
+    if int(holder.get("pid", -1)) == me["pid"] and holder.get("start") in (None, me.get("start")):
+        return True
+    return procid.alive(holder) == procid.DEAD
+
+
+def release(job_id: str) -> bool:
+    """Free the job's slot, unless a newer attempt (another live process) holds it now."""
+    with locked():
+        entries = _read()
+        if entries is None:
+            entries = rebuild()
+        entry = entries.get(job_id)
+        if entry is not None and not _mine(entry):
+            return False  # a stale release (e.g. an old worker after a new reply): keep the slot
+        entries.pop(job_id, None)
+        _unmark(job_id)
+        _write(entries)
+        return True
+
+
+def active() -> list[str]:
+    """Jobs holding a slot right now. O(active), not O(history)."""
+    with locked():
+        entries = _current()
+        _write(entries)
+        return list(entries)
+
+
+def count() -> int:
+    return len(active())

subtask/capacity.py

@@ -0,0 +1,90 @@
+"""How much room each engine has: value, unit, source, freshness, confidence.
+
+Unknown stays unknown (value None). The router may use a prior for unknown
+engines, and it says so. Quota exhaustion seen in a real run (e.g. Codex
+"usage limit") is remembered until its reset time.
+"""
+
+from __future__ import annotations
+
+import time
+
+from . import config, jobs
+from .engines import registry
+
+CACHE_TTL_S = 120
+
+
+def _cache():
+    return config.HOME / "capacity.json"
+
+
+def _hints():
+    return config.HOME / "quota-hints.json"
+
+
+def note_exhausted(engine: str, until: float | None, message: str) -> None:
+    """Record that a run hit the engine's quota (from the worker)."""
+    config.HOME.mkdir(parents=True, exist_ok=True)
+    hints = jobs.read_json(_hints())
+    hints[engine] = {"seen": time.time(), "until": until, "message": message[:200]}
+    jobs.write_json(_hints(), hints)
+    _cache().unlink(missing_ok=True)
+
+
+def _hint(engine: str) -> dict | None:
+    hint = jobs.read_json(_hints()).get(engine)
+    if not hint:
+        return None
+    until = hint.get("until") or hint["seen"] + 3600  # unknown reset: assume an hour
+    return hint if until > time.time() else None
+
+
+def snapshot(refresh: bool = False) -> dict[str, dict]:
+    cache = _cache()
+    if not refresh and cache.is_file() and time.time() - cache.stat().st_mtime < CACHE_TTL_S:
+        cached = jobs.read_json(cache)
+        if cached.get("v") == 2:
+            return cached["engines"]
+    out: dict[str, dict] = {}
+    for name, adapter in registry.all_engines().items():
+        try:
+            reading = adapter.capacity().as_dict()
+        except Exception as exc:  # noqa: BLE001 - one broken source must not hide the others
+            reading = {"value": None, "unit": "pct_free", "source": "error", "ts": time.time(),
+                       "confidence": "none", "note": f"{type(exc).__name__}: {exc}"[:120]}  # fmt: skip
+        hint = _hint(name)
+        if hint:
+            reading = {**reading, "value": 0.0, "confidence": "high", "source": "last run: quota exhausted",
+                       "note": hint["message"], "ts": hint["seen"], "resets_at": hint.get("until")}  # fmt: skip
+        out[name] = reading
+    config.HOME.mkdir(parents=True, exist_ok=True)
+    jobs.write_json(cache, {"v": 2, "engines": out})  # atomic: parallel readers never see half a file
+    return out
+
+
+def report() -> str:
+    lines = []
+    for engine, info in snapshot(refresh=True).items():
+        value = "?" if info["value"] is None else f"{info['value']:.0f}%"
+        age = int(time.time() - float(info.get("ts") or time.time()))
+        lines.append(
+            f"{engine:12} free {value:>4} · conf {info['confidence']:6} · age {age}s · {info['note']}"[:150]
+        )
+    return "\n".join(lines)
+
+
+def pick(kind: str = "code", max_usd: float | None = None, readonly: bool = False) -> tuple[str, str]:
+    """v0 API, kept for callers: (engine, reason). The router does the work."""
+    from . import policy, router
+
+    engine, reason, _ = router.pick(kind, max_usd, policy.demand(readonly=readonly))
+    return engine, reason
+
+
+def __getattr__(name: str):
+    if name == "KINDS":  # v0 API: the kind table now lives in the router
+        from .router import KINDS
+
+        return KINDS
+    raise AttributeError(name)

subtask/cli.py

@@ -0,0 +1,183 @@
+"""Command line twin of the MCP tools, for agents or humans without MCP.
+
+subtask start "brief" [--engine auto] [--kind code] [--repo PATH] [--readonly] [--max-usd 2]
+subtask wait ID [ID...] [--timeout 50]
+subtask status [ID] | result ID [--full|--evidence] | reply ID "msg" | stop ID | cleanup ID | spend | engines
+subtask install|uninstall --client claude|codex|kimi|opencode|all [--yes]
+subtask doctor [--json] [--client X] | gc [--days 30] [--apply] | du | roi | routing explain|calibrate | watch ID...
+
+Differences from the MCP tools: the CLI also has --model, --no-sandbox (same as
+--policy worktree), --untrusted, spend, steps, install, doctor, gc, du, roi,
+routing and watch. MCP `engines` returns capacity plus spend in one call.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import core
+from .install import commands as install_commands
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(
+        prog="subtask", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("start")
+    s.add_argument("task", help="brief, or - to read it from stdin")
+    s.add_argument("--engine", default="auto")
+    s.add_argument("--kind", default="code", choices=["read", "code", "review", "hard"])
+    s.add_argument("--repo")
+    s.add_argument("--cwd")
+    s.add_argument("--base", default="HEAD")
+    s.add_argument("--readonly", action="store_true")
+    s.add_argument("--max-usd", type=float)
+    s.add_argument("--max-turns", type=int, default=60)
+    s.add_argument("--effort", default="medium")
+    s.add_argument("--model")
+    s.add_argument("--no-sandbox", action="store_true")
+    s.add_argument("--file", action="append", dest="files", help="path the agent reads first")
+    s.add_argument("--policy", choices=["worktree", "sandbox", "isolated", "untrusted"])
+    s.add_argument("--untrusted", action="store_true")
+    s.add_argument("--verify", help="command subtask runs itself on the result (exit 0 = verified)")
+    w = sub.add_parser("wait")
+    w.add_argument("ids", nargs="+")
+    w.add_argument("--timeout", type=int, default=300)
+    w.add_argument("--no-results", action="store_true")
+    w.add_argument("--any", action="store_true", help="return when the first job ends")
+    w.add_argument("--since", help="cursor from a previous wait ('' to start): adds what changed")
+    st = sub.add_parser("status")
+    st.add_argument("id", nargs="?")
+    r = sub.add_parser("result")
+    r.add_argument("id")
+    r.add_argument("--full", action="store_true")
+    r.add_argument("--evidence", action="store_true", help="JSON envelope with sources")
+    rp = sub.add_parser("reply")
+    rp.add_argument("id")
+    rp.add_argument("message")
+    for name in ("stop", "cleanup"):
+        sub.add_parser(name).add_argument("id")
+    sp = sub.add_parser("step")
+    sp.add_argument("title")
+    sp.add_argument("--path", required=True)
+    sp.add_argument("--how", required=True)
+    sp.add_argument("--decision", action="append", dest="decisions")
+    sub.add_parser("steps")
+    sub.add_parser("spend")
+    sub.add_parser("engines")
+    install_commands.add_parsers(sub)
+    g = sub.add_parser("gc")
+    g.add_argument("--days", type=int, default=30)
+    g.add_argument("--apply", action="store_true")
+    sub.add_parser("du")
+    sub.add_parser("roi")
+    ro = sub.add_parser("routing")
+    ro.add_argument("action", choices=["explain", "calibrate"])
+    ro.add_argument("--kind", default="code", choices=["read", "code", "review", "hard"])
+    ro.add_argument("--policy", choices=["worktree", "sandbox", "isolated", "untrusted"])
+    ro.add_argument("--readonly", action="store_true")
+    wa = sub.add_parser("watch", help="terminal view of job progress (diagnostic, not the chat)")
+    wa.add_argument("ids", nargs="+")
+    wa.add_argument("--interval", type=float, default=2.0)
+    a = p.parse_args()
+
+    if a.cmd in ("install", "uninstall") or (a.cmd == "doctor" and a.client):
+        return install_commands.run(a)
+
+    if a.cmd == "start":
+        task = sys.stdin.read() if a.task == "-" else a.task
+        out = core.start(
+            task,
+            a.engine,
+            a.repo,
+            a.cwd,
+            a.base,
+            a.readonly,
+            a.max_usd,
+            a.max_turns,
+            a.effort,
+            a.model,
+            not a.no_sandbox,
+            a.kind,
+            a.files,
+            policy=a.policy,
+            verify=a.verify,
+            untrusted=a.untrusted,
+        )
+    elif a.cmd == "wait":
+        out = core.wait(a.ids, a.timeout, a.any, not a.no_results, since=a.since)
+    elif a.cmd == "status":
+        out = core.status(a.id)
+    elif a.cmd == "result":
+        out = core.result(a.id, a.full, a.evidence)
+    elif a.cmd == "reply":
+        out = core.reply(a.id, a.message)
+    elif a.cmd == "step":
+        out = core.step(a.title, a.path, a.how, a.decisions)
+    elif a.cmd == "steps":
+        out = core.steps()
+    elif a.cmd == "stop":
+        out = core.stop(a.id)
+    elif a.cmd == "cleanup":
+        out = core.cleanup(a.id)
+    elif a.cmd == "engines":
+        out = core.engines()
+    elif a.cmd == "doctor":
+        from . import doctor
+
+        out = doctor.report(a.json)
+    elif a.cmd == "gc":
+        from . import gc
+
+        out = gc.run(a.days, a.apply)
+    elif a.cmd == "du":
+        from . import gc
+
+        out = "\n".join(f"{k}: {v / 1e6:.1f} MB" for k, v in gc.du().items())
+    elif a.cmd == "roi":
+        from . import roi
+
+        out = roi.report()
+    elif a.cmd == "routing":
+        from . import policy, router
+
+        wanted = policy.demand(a.readonly, a.policy)
+        out = router.explain(a.kind, None, wanted) if a.action == "explain" else router.calibrate()
+    elif a.cmd == "watch":
+        return _watch(a.ids, a.interval)
+    else:
+        out = core.spend()
+    print(out)
+    return 0
+
+
+def _watch(ids: list[str], interval: float) -> int:
+    import time
+
+    from . import jobs
+    from .progress import Reporter
+
+    reporter = Reporter(lambda _v, message, _t: print(message, flush=True), ids, min_interval=interval)
+    try:
+        while True:
+            reporter.poll()
+            if all(jobs.status(j).get("state") in jobs.FINAL for j in ids):
+                reporter.phase(reporter.summary(), force=True)
+                return 0
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        return 130
+
+
+def run() -> int:
+    try:
+        return main()
+    except ValueError as exc:  # bad id or argument: one line, no traceback
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(run())

subtask/config.py

@@ -0,0 +1,59 @@
+"""Settings, all overridable from the environment. No personal data lives here."""
+
+from __future__ import annotations
+
+import math
+import os
+from pathlib import Path
+
+HOME = Path(os.environ.get("SUBTASK_HOME", Path.home() / ".local" / "share" / "subtask"))
+JOBS = HOME / "jobs"
+WORKTREES = HOME / "worktrees"
+LEDGER = HOME / "ledger.jsonl"
+
+# KEY=VALUE file holding ANTHROPIC_API_KEY (and optionally ANTHROPIC_WORKSPACE_ID).
+# Keep it chmod 600; it is read by the worker only, never returned by a tool.
+ENV_FILE = Path(os.environ.get("SUBTASK_ENV_FILE", Path.home() / ".config" / "subtask" / "env"))
+
+
+def _money(name: str, default: str) -> float:
+    try:
+        value = float(os.environ.get(name, default))
+    except ValueError:
+        value = float(default)
+    return value if math.isfinite(value) and value >= 0 else float(default)
+
+
+MONTHLY_CAP_USD = _money("SUBTASK_MONTHLY_CAP_USD", "180")
+DEFAULT_MAX_USD = _money("SUBTASK_DEFAULT_MAX_USD", "2")
+MAX_JOB_USD = _money("SUBTASK_MAX_JOB_USD", "20")
+MAX_RUNNING = int(_money("SUBTASK_MAX_RUNNING", "4")) or 4
+SUMMARY_LINES = 12
+
+# DeepSeek (engine "dsh"): key file and list price in USD per million tokens.
+# Peak rates, checked 2026-09-10; override if the price list changes.
+DSH_KEY_FILE = Path(os.environ.get("SUBTASK_DSH_KEY_FILE", Path.home() / ".config" / "deepseek" / "api-key"))
+DSH_INPUT_USD_M = _money("SUBTASK_DSH_INPUT_USD_M", "0.30")
+DSH_CACHED_USD_M = _money("SUBTASK_DSH_CACHED_USD_M", "0.006")
+DSH_OUTPUT_USD_M = _money("SUBTASK_DSH_OUTPUT_USD_M", "1.20")
+
+
+def deepseek_key() -> str:
+    """DEEPSEEK_API_KEY from the env file, else the key file. Never from the environment."""
+    key = load_secrets().get("DEEPSEEK_API_KEY", "")
+    if not key and DSH_KEY_FILE.is_file():
+        key = DSH_KEY_FILE.read_text().strip()
+    return key
+
+
+def load_secrets() -> dict[str, str]:
+    """Read the env file. The key is never taken from the environment."""
+    values: dict[str, str] = {}
+    if ENV_FILE.is_file():
+        for line in ENV_FILE.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, value = line.removeprefix("export ").partition("=")
+            values[key.strip()] = value.strip().strip('"').strip("'")
+    return values