subtask-mcp 0.2.3__py3-none-any.whl

subtask/doctor.py

@@ -0,0 +1,120 @@
+"""Diagnostics without spending: platform, tools, engines, state, protocol.
+
+Each check says what was checked and how: installed, configured and
+authenticated are different facts, and quota or sandbox availability are
+reported separately. Nothing here calls a paid API.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import stat
+import sys
+
+from . import __version__, config
+
+
+def _check(name: str, ok: bool | None, detail: str) -> dict:
+    return {"check": name, "ok": ok, "detail": detail}
+
+
+def engines() -> list[dict]:
+    from .engines import registry
+
+    out = []
+    for name, adapter in registry.all_engines().items():
+        probe = adapter.probe()
+        out.append(
+            {
+                "engine": name,
+                "installed": probe.installed,
+                "version": probe.version,
+                "compatible": probe.compatible,
+                "auth": probe.auth,
+                "problems": probe.problems,
+                "capabilities": adapter.capabilities.as_dict(),
+                "capacity": adapter.capacity().as_dict() if probe.installed else None,
+            }
+        )
+    for err in registry.plugin_errors():
+        out.append({"engine": "plugin", "installed": False, "problems": [err]})
+    return out
+
+
+def _bwrap() -> bool:
+    from .runners import bwrap_available
+
+    return bwrap_available()
+
+
+def checks() -> list[dict]:
+    out = [
+        _check("subtask", True, f"{__version__} on Python {platform.python_version()} ({sys.executable})"),
+        _check(
+            "platform",
+            sys.platform.startswith("linux") or None,
+            f"{platform.system()} {platform.release()}: Linux supported; macOS degraded (no /proc start times, "
+            "no bwrap); Windows not supported (fcntl)",
+        ),
+        _check("git", bool(shutil.which("git")), shutil.which("git") or "git not found: repo= jobs need it"),
+        _check(
+            "bwrap",
+            bool(shutil.which("bwrap")) or None,
+            "available: policy=isolated works"
+            if shutil.which("bwrap")
+            else "missing: policy=isolated refused",
+        ),
+        _check("socat", bool(shutil.which("socat")) or None, "Claude Code sandbox network proxy on Linux"),
+    ]
+    env = config.ENV_FILE
+    if env.is_file():
+        mode = stat.S_IMODE(env.stat().st_mode)
+        out.append(_check("secret file", mode & 0o077 == 0, f"{env} mode {oct(mode)} (want 600)"))
+    else:
+        out.append(_check("secret file", None, f"{env} missing: *-api engines unavailable"))
+    try:
+        config.HOME.mkdir(parents=True, exist_ok=True)
+        writable = os.access(config.HOME, os.W_OK)
+    except OSError:
+        writable = False
+    out.append(_check("state dir", writable, str(config.HOME)))
+    try:
+        from . import admission, ledger
+
+        out.append(
+            _check("active jobs", True, f"{len(admission.active())} of {config.MAX_RUNNING} slots used")
+        )
+        out.append(
+            _check("spend", True, f"{ledger.committed():.2f}$ committed of {config.MONTHLY_CAP_USD:.0f}$")
+        )
+    except Exception as exc:  # noqa: BLE001
+        out.append(_check("state", False, f"{type(exc).__name__}: {exc}"))
+    out.append(
+        _check(
+            "mcp protocol", True, "dual-era: 2026-07-28 (stateless) and 2025-11-25..2024-11-05 (initialize)"
+        )
+    )
+    return out
+
+
+def report(as_json: bool = False) -> str:
+    data = {"checks": checks(), "engines": engines()}
+    if as_json:
+        return json.dumps(data, indent=1, default=str)
+    mark = {True: "ok ", False: "BAD", None: "-- "}
+    lines = [f"{mark[c['ok']]} {c['check']}: {c['detail']}" for c in data["checks"]]
+    for e in data["engines"]:
+        if e["engine"] == "plugin":
+            lines.append(f"BAD plugin: {'; '.join(e['problems'])}")
+            continue
+        state = "ok " if e["installed"] and e["compatible"] else "-- " if not e["installed"] else "BAD"
+        cap = e.get("capacity") or {}
+        free = "?" if cap.get("value") is None else f"{cap['value']:.0f}%"
+        lines.append(
+            f"{state} {e['engine']:12} {e['version'] or 'not installed'} · auth {e['auth']} · free {free} "
+            f"({cap.get('confidence', 'none')}) {'; '.join(e['problems'])}"[:200]
+        )
+    return "\n".join(lines)

subtask/engines/__init__.py

@@ -0,0 +1 @@
+"""Engine adapters. `registry.get(name)` returns one; the core knows no provider flags."""

subtask/engines/base.py

@@ -0,0 +1,297 @@
+"""Engine adapter protocol: what the core may ask of an engine, and nothing about MCP or chat.
+
+An adapter declares capabilities, probes the local install, reads capacity,
+and runs one attempt. Third-party adapters register through the
+`subtask.engines` entry point group (see registry.py); the core never changes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import threading
+import time
+from collections.abc import Callable, Iterable
+from pathlib import Path
+
+ADAPTER_API = 1  # bump when the protocol below changes incompatibly
+
+# Security levels, weakest first. A job asks for a minimum; adapters list what they enforce.
+LEVELS = ("worktree", "sandbox", "isolated")
+
+
+class _Factory:
+    def __init__(self, make: Callable[[], object]) -> None:
+        self.make = make
+
+
+def field(default_factory: Callable[[], object]) -> object:
+    return _Factory(default_factory)
+
+
+def record(cls: type) -> type:
+    """A tiny stand-in for @dataclass: `dataclasses` pulls in `inspect` (~10 ms per cold start)."""
+    names = list(cls.__annotations__)  # own annotations (strings: postponed evaluation)
+    defaults = {n: cls.__dict__[n] for n in names if n in cls.__dict__}
+
+    def __init__(self, *args: object, **kwargs: object) -> None:
+        values = dict(zip(names, args, strict=False))
+        values.update(kwargs)
+        for name in names:
+            if name not in values:
+                if name not in defaults:
+                    raise TypeError(f"{cls.__name__}() missing argument {name!r}")
+                d = defaults[name]
+                values[name] = d.make() if isinstance(d, _Factory) else d
+            object.__setattr__(self, name, values[name])
+
+    def as_dict(self) -> dict:
+        return {n: getattr(self, n) for n in names}
+
+    cls.__init__ = __init__
+    cls.__eq__ = lambda self, other: type(other) is type(self) and as_dict(self) == as_dict(other)
+    cls.__repr__ = lambda self: f"{cls.__name__}({as_dict(self)!r})"
+    if "as_dict" not in cls.__dict__:
+        cls.as_dict = as_dict
+    cls._fields = tuple(names)
+    return cls
+
+
+def asdict(obj: object) -> dict:
+    return {n: getattr(obj, n) for n in obj._fields}  # type: ignore[attr-defined]
+
+
+@record
+class Capabilities:
+    readonly: bool  # can enforce a read-only run
+    levels: tuple[str, ...]  # write isolation levels the adapter can enforce
+    command_network_off: bool  # can deny network to the worker's shell commands
+    cost: str  # "usd" observed, "quota" (subscription share), "none"
+    resume: bool
+    structured_events: bool
+    paid: bool  # books money against the monthly cap
+    notes: str = ""
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+@record
+class Probe:
+    installed: bool
+    version: str | None = None
+    path: str | None = None
+    flags: dict[str, bool] = field(default_factory=dict)
+    auth: str = "unknown"  # ok | missing | unknown: from local evidence only, never a paid call
+    problems: list[str] = field(default_factory=list)
+    checked: float = field(default_factory=time.time)
+    compatible: bool = True
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+@record
+class Capacity:
+    value: float | None  # None = unknown, never a silent 50
+    unit: str  # "pct_free" | "usd_left"
+    source: str
+    ts: float
+    confidence: str  # high | medium | low | none
+    note: str = ""
+    resets_at: float | None = None
+
+    @property
+    def freshness_s(self) -> float:
+        return max(0.0, time.time() - self.ts)
+
+    def as_dict(self) -> dict:
+        return {**asdict(self), "freshness_s": round(self.freshness_s, 1)}
+
+
+@record
+class RunContext:
+    job_id: str
+    spec: dict
+    prompt: str
+    resume: str | None
+    attempt: int
+    folder: Path
+    emit: Callable[..., object]  # emit(phase, msg, source="adapter")
+    started: threading.Event  # set once the engine may have spent anything
+    wrap: Callable[[list[str], dict[str, str]], tuple[list[str], dict[str, str]]]  # isolation runner
+    env: dict[str, str]  # minimal environment for the engine process
+
+
+@record
+class Outcome:
+    ok: bool
+    subtype: str
+    result: str
+    session_id: str | None
+    cost_usd: float | None = None  # None = unknown
+    turns: int | None = None
+    tokens: dict[str, int] = field(default_factory=dict)
+    commands: list[dict] = field(default_factory=list)  # runner_observed: {"command", "exit_code"}
+    quota_exhausted: bool = False
+
+
+class Adapter:
+    """Base class. Subclasses set the class attributes and override build/parse."""
+
+    name = ""
+    family = ""
+    binary: str | None = None
+    model: str | None = None
+    supported = ""  # human description of tested versions, e.g. ">=2.1"
+    capabilities: Capabilities
+
+    def probe(self) -> Probe:
+        if not self.binary:
+            return Probe(installed=True, version="sdk", path=None)
+        path = shutil.which(self.binary)
+        if not path:
+            return Probe(installed=False, problems=[f"{self.binary} not on PATH"])
+        version = _run([path, "--version"])
+        probe = Probe(installed=True, version=version.splitlines()[0][:80] if version else None, path=path)
+        help_text = _run([path, *self.help_args()]) if self.help_args() else ""
+        for flag in self.required_flags():
+            probe.flags[flag] = flag in help_text
+            if help_text and flag not in help_text:
+                probe.problems.append(f"flag {flag} not in `{self.binary} {' '.join(self.help_args())}`")
+        probe.compatible = not probe.problems
+        probe.auth = self.auth_state()
+        return probe
+
+    def available(self) -> bool:
+        """Cheap installed check for routing (no subprocess): binary on PATH or module importable."""
+        if self.binary:
+            return shutil.which(self.binary) is not None
+        module = getattr(self, "module", None)
+        if module:
+            import importlib.util
+
+            return importlib.util.find_spec(module) is not None
+        return True
+
+    def help_args(self) -> list[str]:
+        return []
+
+    def required_flags(self) -> list[str]:
+        return []
+
+    def auth_state(self) -> str:
+        return "unknown"
+
+    def capacity(self) -> Capacity:
+        return Capacity(None, "pct_free", "none", time.time(), "none", "no quota data")
+
+    def run(self, ctx: RunContext) -> Outcome:
+        raise NotImplementedError
+
+
+class CliAdapter(Adapter):
+    """An engine driven as a headless CLI that prints JSON lines on stdout."""
+
+    def argv(self, ctx: RunContext) -> list[str]:
+        raise NotImplementedError
+
+    def parse(self, line: str, state: dict) -> str | None:
+        """Update `state` from one stdout line; return a short activity text or None."""
+        return None
+
+    def run(self, ctx: RunContext) -> Outcome:
+        argv, env = ctx.wrap(self.argv(ctx), dict(ctx.env))
+        state: dict = {"text": [], "commands": [], "session": None, "tokens": {}, "cost": None}
+        raw = ctx.folder / f"output-{ctx.attempt}.jsonl"
+        with raw.open("a") as keep, (ctx.folder / "worker-stderr.log").open("a") as err:
+            proc = subprocess.Popen(
+                argv,
+                cwd=ctx.spec["cwd"],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=err,
+                text=True,
+                env=env,
+            )
+            ctx.started.set()
+            assert proc.stdout is not None
+            last_emit = 0.0
+            for line in proc.stdout:
+                keep.write(line)
+                if not line.lstrip().startswith("{"):
+                    state.setdefault("plain", []).append(line.rstrip("\n"))
+                try:
+                    activity = self.parse(line, state)
+                except (ValueError, KeyError, TypeError, AttributeError):
+                    activity = None
+                    state.setdefault("format_errors", 0)
+                    state["format_errors"] += 1
+                if activity and time.monotonic() - last_emit >= 1.0:
+                    ctx.emit("tool", activity, source="adapter")
+                    last_emit = time.monotonic()
+            code = proc.wait()
+        text = "\n".join(state["text"]).strip()
+        if not text and state.get("plain"):
+            text = "\n".join(state["plain"]).strip()  # engine printed no structured events: keep its output
+        if state.get("error") and not text:
+            text = state["error"]
+        return Outcome(
+            ok=code == 0 and not state.get("error") and bool(text),
+            subtype=state.get("error_kind") or f"exit {code}",
+            result=text[-20000:],
+            session_id=state.get("session")
+            or ctx.resume
+            or ("continue" if self.capabilities.resume else None),
+            cost_usd=state.get("cost"),
+            tokens=state["tokens"],
+            commands=state["commands"],
+            quota_exhausted=bool(state.get("quota")),
+        )
+
+
+def _run(argv: list[str], timeout: float = 10) -> str:
+    try:
+        done = subprocess.run(
+            argv, capture_output=True, text=True, timeout=timeout, check=False, stdin=subprocess.DEVNULL
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    return (done.stdout or done.stderr or "").strip()
+
+
+def short_command(command: object) -> str:
+    """A shell command as one short line, for progress (never full scripts)."""
+    if isinstance(command, list):
+        command = " ".join(str(c) for c in command)
+    text = str(command or "").strip()
+    for prefix in ("bash -lc ", "/bin/bash -lc ", "sh -c ", "/bin/sh -c "):
+        if text.startswith(prefix):
+            text = text[len(prefix) :].strip("'\"")
+    first = text.splitlines()[0] if text else ""
+    return first[:70] + ("…" if len(first) > 70 or "\n" in text else "")
+
+
+def describe_command(command: str) -> str:
+    low = command.lower()
+    if any(k in low for k in ("pytest", "npm test", "go test", "cargo test", "unittest", "jest", "vitest")):
+        return f"running tests: {command}"
+    if low.startswith(("git commit", "git add")):
+        return f"committing: {command}"
+    if low.startswith(("rg ", "grep ", "find ", "ls ", "cat ", "sed -n", "head ", "tail ")):
+        return f"reading: {command}"
+    return f"running: {command}"
+
+
+def json_line(line: str) -> dict | None:
+    line = line.strip()
+    if not line.startswith("{"):
+        return None
+    data = json.loads(line)
+    return data if isinstance(data, dict) else None
+
+
+def env_names(names: Iterable[str]) -> dict[str, str]:
+    return {k: os.environ[k] for k in names if k in os.environ}

subtask/engines/claude_api.py

@@ -0,0 +1,204 @@
+"""Claude models through the Claude Agent SDK, paid with the API key (monthly cap)."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+from .. import config
+from .base import Adapter, Capabilities, Capacity, Outcome, RunContext, describe_command, short_command
+
+READONLY_TOOLS = ["Read", "Grep", "Glob", "WebSearch"]
+SUMMARY_RULE = (
+    "\n\nWhen you finish, end your answer with a section that starts with the exact "
+    'line "## Summary" and has at most 10 short lines. Put the answer itself first '
+    "(the findings, the decision, the numbers), then files touched, commits, tests "
+    "run, what is left. The caller reads only this section. Use the task language."
+)
+
+
+def key_helper() -> Path:
+    """Script that prints the key, so the key is never in the agent's environment."""
+    helper = config.HOME / "key-helper.sh"
+    helper.parent.mkdir(parents=True, exist_ok=True)
+    tmp = helper.with_suffix(f".{os.getpid()}.tmp")
+    tmp.write_text(
+        f"#!{sys.executable}\nfrom subtask.config import load_secrets\nprint(load_secrets().get('ANTHROPIC_API_KEY', ''))\n"
+    )
+    tmp.chmod(0o700)
+    os.replace(tmp, helper)  # atomic: other workers may be running it right now
+    return helper
+
+
+def settings(sandbox: bool, git_dir: str | None, network_off: bool = False) -> str:
+    """Per-run settings: OS sandbox for Bash, and best-effort read denies on secrets.
+
+    Not a hard boundary: an agent running as the same user can still find a way to
+    read files it may not Read. Use level="isolated" for a filesystem boundary.
+    """
+    secret_paths = [
+        str(config.ENV_FILE),
+        str(config.HOME / "key-helper.sh"),
+        str(Path.home() / ".claude" / ".credentials.json"),
+    ]
+    data: dict = {
+        "permissions": {
+            "deny": [f"{tool}(/{p})" for p in secret_paths for tool in ("Read", "Edit", "Write")]
+            + [f"Bash(*{p}*)" for p in secret_paths]
+            + [f"Bash(*{p.replace(str(Path.home()), '~')}*)" for p in secret_paths]
+        },
+        "apiKeyHelper": str(key_helper()),
+    }
+    if sandbox:
+        data["sandbox"] = {
+            "enabled": True,
+            "allowUnsandboxedCommands": False,
+            "failIfUnavailable": True,
+            "filesystem": {
+                # git data of a worktree lives in the main repo's .git: commits need it
+                "allowWrite": [str(Path.home() / ".cache")] + ([git_dir] if git_dir else []),
+                "denyRead": secret_paths,
+                "denyWrite": secret_paths,
+            },
+        }
+        if network_off:
+            data["sandbox"]["network"] = {"allowedDomains": []}
+    return json.dumps(data)
+
+
+def api_env() -> dict[str, str]:
+    env = {"IS_SANDBOX": "1", "ANTHROPIC_API_KEY": ""}  # key comes from apiKeyHelper only
+    secrets = config.load_secrets()
+    if not secrets.get("ANTHROPIC_API_KEY"):
+        raise RuntimeError(f"ANTHROPIC_API_KEY missing (file {config.ENV_FILE})")
+    if secrets.get("ANTHROPIC_WORKSPACE_ID"):
+        env["ANTHROPIC_CUSTOM_HEADERS"] = f"anthropic-workspace-id: {secrets['ANTHROPIC_WORKSPACE_ID']}"
+    return env
+
+
+class ClaudeApi(Adapter):
+    family = "api"
+    module = "claude_agent_sdk"
+    capabilities = Capabilities(
+        readonly=True,
+        levels=("worktree", "sandbox"),
+        command_network_off=True,
+        cost="usd",
+        resume=True,
+        structured_events=True,
+        paid=True,
+        notes="sandbox = Claude Code OS sandbox (bubblewrap on Linux), same user",
+    )
+
+    def __init__(self, name: str, model: str) -> None:
+        self.name, self.model = name, model
+
+    def auth_state(self) -> str:
+        return "present" if config.load_secrets().get("ANTHROPIC_API_KEY") else "missing"
+
+    def probe(self):
+        probe = super().probe()
+        try:
+            import importlib.metadata as md
+
+            probe.version = "claude-agent-sdk " + md.version("claude-agent-sdk")
+        except Exception:  # noqa: BLE001
+            probe.installed, probe.problems = False, ["claude-agent-sdk not installed"]
+        probe.auth = self.auth_state()
+        return probe
+
+    def capacity(self) -> Capacity:
+        from .. import ledger
+
+        cap = config.MONTHLY_CAP_USD
+        left = cap - ledger.committed()
+        return Capacity(
+            max(0.0, 100 * left / cap) if cap > 0 else 0.0,
+            "pct_free",
+            "local ledger vs monthly cap",
+            time.time(),
+            "high",
+            f"{left:.2f}$ of {cap:.0f}$ left this month",
+        )
+
+    def run(self, ctx: RunContext) -> Outcome:
+        import asyncio  # lazy: 60+ ms at import, only the worker needs it
+
+        return asyncio.run(self._run(ctx))
+
+    async def _run(self, ctx: RunContext) -> Outcome:
+        from claude_agent_sdk import (
+            AssistantMessage,
+            ClaudeAgentOptions,
+            ResultMessage,
+            ToolResultBlock,
+            ToolUseBlock,
+            UserMessage,
+            query,
+        )
+
+        spec = ctx.spec
+        readonly = spec.get("readonly", False)
+        policy = spec.get("policy") or {}
+        sandbox = not readonly and policy.get("level", "sandbox") != "worktree"
+        options = ClaudeAgentOptions(
+            cwd=spec["cwd"],
+            model=spec.get("model") or self.model,
+            max_turns=spec["max_turns"],
+            max_budget_usd=spec["max_usd"],
+            effort=spec["effort"],
+            permission_mode="dontAsk" if readonly else "bypassPermissions",
+            allowed_tools=READONLY_TOOLS if readonly else [],
+            disallowed_tools=["mcp__*", "WebFetch"] if readonly else ["mcp__*"],
+            settings=settings(sandbox, spec.get("git_dir"), policy.get("untrusted", False)),
+            system_prompt={"type": "preset", "preset": "claude_code", "append": SUMMARY_RULE},
+            env={**ctx.env, **api_env()},
+            resume=ctx.resume,
+        )
+        out = Outcome(ok=False, subtype="no result", result="", session_id=ctx.resume)
+        pending: dict[str, str] = {}
+        turns = 0
+        async for message in query(prompt=ctx.prompt, options=options):
+            ctx.started.set()
+            if isinstance(message, AssistantMessage):
+                turns += 1
+                for block in message.content:
+                    if isinstance(block, ToolUseBlock):
+                        text = _tool_text(block.name, block.input)
+                        if block.name == "Bash":
+                            pending[block.id] = short_command(block.input.get("command"))
+                        ctx.emit("tool", text, source="adapter")
+            elif isinstance(message, UserMessage) and isinstance(message.content, list):
+                for block in message.content:
+                    if isinstance(block, ToolResultBlock) and block.tool_use_id in pending:
+                        out.commands.append(
+                            {
+                                "command": pending.pop(block.tool_use_id),
+                                "exit_code": 1 if block.is_error else 0,
+                            }
+                        )
+            elif isinstance(message, ResultMessage):
+                usage = message.usage or {}
+                out = Outcome(
+                    ok=not message.is_error and message.subtype == "success",
+                    subtype=message.subtype,
+                    result=message.result or "",
+                    session_id=message.session_id,
+                    cost_usd=message.total_cost_usd or 0.0,
+                    turns=message.num_turns,
+                    tokens={k: v for k, v in usage.items() if isinstance(v, int)},
+                    commands=out.commands,
+                )
+        out.turns = out.turns or turns
+        return out
+
+
+def _tool_text(name: str, args: dict) -> str:
+    if name == "Bash":
+        return describe_command(short_command(args.get("command")))
+    target = args.get("file_path") or args.get("path") or args.get("pattern") or args.get("query") or ""
+    verb = {"Read": "reading", "Edit": "editing", "Write": "writing", "Grep": "searching", "Glob": "listing"}
+    return f"{verb.get(name, name)} {Path(str(target)).name if '/' in str(target) else target}".strip()[:90]