subtask-mcp 0.2.3__py3-none-any.whl

subtask/engines/codex.py

@@ -0,0 +1,182 @@
+"""Codex CLI (`codex exec --json`). Tested with codex-cli 0.162."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from datetime import datetime
+from pathlib import Path
+
+from .base import Capabilities, Capacity, CliAdapter, RunContext, describe_command, json_line, short_command
+
+LIMIT_RE = re.compile(
+    r"try again at ([A-Z][a-z]{2}) (\d{1,2})(?:st|nd|rd|th)?, (\d{4}) (\d{1,2}:\d{2} [AP]M)"
+)
+
+
+class Codex(CliAdapter):
+    name = "codex"
+    family = "codex"
+    binary = "codex"
+    supported = "codex-cli >=0.160"
+    capabilities = Capabilities(
+        readonly=True,
+        levels=("worktree", "sandbox", "isolated"),
+        command_network_off=True,
+        cost="quota",
+        resume=True,
+        structured_events=True,
+        paid=False,
+        notes="sandbox = codex workspace-write (same user); worktree = no codex sandbox, opt-in only",
+    )
+
+    def help_args(self) -> list[str]:
+        return ["exec", "--help"]
+
+    def required_flags(self) -> list[str]:
+        return ["--json", "--sandbox", "--output-last-message", "--add-dir", "--skip-git-repo-check"]
+
+    def auth_state(self) -> str:
+        return "present" if (Path.home() / ".codex" / "auth.json").is_file() else "missing"
+
+    def argv(self, ctx: RunContext) -> list[str]:
+        spec = ctx.spec
+        level = spec.get("policy", {}).get("level", "sandbox")
+        if spec.get("readonly"):
+            mode = ["-s", "read-only"]
+        elif level == "worktree":
+            mode = ["--dangerously-bypass-approvals-and-sandbox"]
+        else:  # sandbox, isolated: codex's own workspace-write sandbox, network off for commands
+            mode = ["-s", "workspace-write", "-c", 'approval_policy="never"']
+            if spec.get("git_dir"):
+                mode += ["--add-dir", spec["git_dir"]]  # commits need the main repo's .git
+        argv = ["codex", "exec", "--json", "--skip-git-repo-check", "-C", spec["cwd"], *mode]
+        argv += ["-o", str(ctx.folder / f"last-message-{ctx.attempt}.txt")]
+        if spec.get("model"):
+            argv += ["-m", spec["model"]]
+        argv += ["resume", ctx.resume, "--", ctx.prompt] if ctx.resume else ["--", ctx.prompt]
+        return argv
+
+    def parse(self, line: str, state: dict) -> str | None:
+        event = json_line(line)
+        if not event:
+            return None
+        kind = event.get("type")
+        if kind == "thread.started":
+            state["session"] = event.get("thread_id")
+        elif kind in ("item.started", "item.completed"):
+            item = event.get("item") or {}
+            if item.get("type") == "command_execution":
+                cmd = short_command(item.get("command"))
+                if kind == "item.completed":
+                    state["commands"].append({"command": cmd, "exit_code": item.get("exit_code")})
+                    return None
+                return describe_command(cmd)
+            if item.get("type") == "agent_message" and kind == "item.completed":
+                state["text"].append(item.get("text") or "")
+            if item.get("type") == "file_change" and kind == "item.completed":
+                files = [c.get("path", "") for c in item.get("changes") or []]
+                return "editing " + ", ".join(Path(f).name for f in files[:3])
+        elif kind == "turn.completed":
+            usage = event.get("usage") or {}
+            for key, value in usage.items():
+                if isinstance(value, int):
+                    state["tokens"][key] = state["tokens"].get(key, 0) + value
+        elif kind in ("error", "turn.failed"):
+            message = event.get("message") or (event.get("error") or {}).get("message") or "error"
+            state["error"] = message
+            if "usage limit" in message.lower():
+                state["quota"] = True
+                state["error_kind"] = "quota exhausted"
+                state["resets_at"] = parse_reset(message)
+        return None
+
+    def run(self, ctx: RunContext):
+        outcome = super().run(ctx)
+        last = ctx.folder / f"last-message-{ctx.attempt}.txt"
+        if last.is_file() and last.read_text().strip():
+            outcome.result = last.read_text()[-20000:]
+            outcome.ok = outcome.ok or (outcome.subtype == "exit 0")
+        return outcome
+
+    def capacity(self) -> Capacity:
+        return codex_capacity()
+
+
+def parse_reset(message: str) -> float | None:
+    match = LIMIT_RE.search(message)
+    if not match:
+        return None
+    try:
+        when = datetime.strptime(" ".join(match.groups()), "%b %d %Y %I:%M %p")
+    except ValueError:
+        return None
+    return when.timestamp()
+
+
+def _tail(path: Path, size: int = 256 * 1024) -> str:
+    with path.open("rb") as fh:
+        fh.seek(0, 2)
+        fh.seek(max(0, fh.tell() - size))
+        return fh.read().decode(errors="replace")
+
+
+def _find(obj: object, key: str) -> dict | None:
+    if isinstance(obj, dict):
+        if key in obj:
+            return obj[key]
+        for value in obj.values():
+            found = _find(value, key)
+            if found is not None:
+                return found
+    return None
+
+
+def codex_capacity(root: Path | None = None) -> Capacity:
+    """Free share from the newest `rate_limits` in local Codex session files.
+
+    Couples to Codex's local storage format: when it changes, this says
+    "unknown" with the reason instead of guessing.
+    """
+    root = root or Path.home() / ".codex" / "sessions"
+    try:
+        files = sorted(root.glob("*/*/*/*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True)[:5]
+    except OSError:
+        files = []
+    if not files:
+        return Capacity(None, "pct_free", "codex sessions", time.time(), "none", "no Codex session files")
+    for path in files:
+        for line in reversed(_tail(path).splitlines()):
+            if '"rate_limits"' not in line:
+                continue
+            try:
+                limits = _find(json.loads(line), "rate_limits")
+            except json.JSONDecodeError:
+                continue
+            worst = None
+            for key in ("primary", "secondary"):
+                win = (limits or {}).get(key)
+                if not win:
+                    continue
+                expired = float(win.get("resets_at") or 0) < time.time()
+                used = 0.0 if expired else float(win.get("used_percent", 0))
+                if worst is None or used > worst[0]:
+                    worst = (used, win.get("resets_at"))
+            if worst:
+                observed = path.stat().st_mtime
+                age = time.time() - observed
+                confidence = "high" if age < 3600 else "medium" if age < 86400 else "low"
+                when = time.strftime("%m-%d %H:%M", time.localtime(worst[1])) if worst[1] else "?"
+                return Capacity(
+                    100 - worst[0],
+                    "pct_free",
+                    f"codex session file ({path.name})",
+                    observed,
+                    confidence,
+                    f"{worst[0]:.0f}% used (resets {when})",
+                    resets_at=worst[1],
+                )
+    return Capacity(
+        None, "pct_free", "codex sessions", time.time(), "none", "no rate_limits block (format changed?)"
+    )

subtask/engines/demo.py

@@ -0,0 +1,50 @@
+"""Deterministic demo engine: no model, no network, no cost. Enabled with SUBTASK_DEMO=1.
+
+It exists to show progress in a real client and to test the whole path.
+The task text picks a script: "fail", "silent" (no activity details),
+"long" (about 3 minutes), anything else succeeds in about 25 seconds.
+"""
+
+from __future__ import annotations
+
+import time
+
+from .base import Adapter, Capabilities, Capacity, Outcome, RunContext
+
+STEPS = [
+    (4, "reading: rg -n 'def start' subtask/"),
+    (5, "editing core.py"),
+    (6, "running tests: pytest -q tests/test_core.py"),
+    (5, "committing: git commit -m 'demo'"),
+]
+
+
+class Demo(Adapter):
+    name = "demo"
+    family = "demo"
+    capabilities = Capabilities(
+        readonly=True, levels=("worktree", "sandbox", "isolated"), command_network_off=True, cost="none",
+        resume=True, structured_events=True, paid=False, notes="demo: runs nothing, spends nothing",
+    )  # fmt: skip
+
+    def capacity(self) -> Capacity:
+        return Capacity(100.0, "pct_free", "demo", time.time(), "high", "demo engine")
+
+    def run(self, ctx: RunContext) -> Outcome:
+        task = ctx.prompt.lower()
+        steps = STEPS * 6 if "long" in task else STEPS
+        commands = []
+        for i, (seconds, text) in enumerate(steps):
+            if "silent" not in task:
+                ctx.emit("tool", text, source="adapter")
+            time.sleep(seconds)
+            if text.startswith("running tests"):
+                code = 1 if "fail" in task else 0
+                commands.append({"command": "pytest -q tests/test_core.py", "exit_code": code})
+                if code:
+                    return Outcome(False, "tests failed", "## Summary\n- demo: tests failed (1 failing)", "demo",
+                                   commands=commands)  # fmt: skip
+            if "fail" in task and i == 2:
+                break
+        return Outcome(True, "success", "## Summary\n- demo finished: 1 file changed, tests passed", "demo",
+                       commands=commands)  # fmt: skip

subtask/engines/dsh.py

@@ -0,0 +1,96 @@
+"""DeepSeek Harness SDK (optional dependency `subtask-mcp[dsh]`), paid from the monthly cap."""
+
+from __future__ import annotations
+
+import json
+import time
+
+from .. import config
+from .base import Adapter, Capabilities, Capacity, Outcome, RunContext
+from .claude_api import SUMMARY_RULE
+
+
+def dsh_cost(events: list[dict]) -> float:
+    """USD from the usage of each model message; rates in config (DeepSeek list price)."""
+    total = 0.0
+    for event in events:
+        usage = event.get("data", {}).get("usage") if isinstance(event.get("data"), dict) else None
+        if not usage:
+            usage = event.get("usage")
+        if not isinstance(usage, dict):
+            continue
+        total += (
+            usage.get("inputTokens", 0) * config.DSH_INPUT_USD_M
+            + usage.get("cacheReadTokens", 0) * config.DSH_CACHED_USD_M
+            + usage.get("outputTokens", 0) * config.DSH_OUTPUT_USD_M
+        ) / 1e6
+    return total
+
+
+class Dsh(Adapter):
+    name = "dsh"
+    family = "dsh"
+    module = "deepseek_harness"
+    model = "deepseek-v4-flash"
+    capabilities = Capabilities(
+        readonly=False,
+        levels=("worktree",),
+        command_network_off=False,
+        cost="usd",
+        resume=True,
+        structured_events=True,
+        paid=True,
+        notes="harness-dependent sandbox, not enforced by subtask",
+    )
+
+    def probe(self):
+        probe = super().probe()
+        try:
+            import importlib.metadata as md
+
+            probe.version = "deepseek-harness-sdk " + md.version("deepseek-harness-sdk")
+        except Exception:  # noqa: BLE001
+            probe.installed, probe.problems = False, ["deepseek-harness-sdk not installed (extra: dsh)"]
+        probe.auth = "present" if config.deepseek_key() else "missing"
+        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",
+        )  # fmt: skip
+
+    def run(self, ctx: RunContext) -> Outcome:
+        from deepseek_harness import DeepSeekHarness
+
+        key = config.deepseek_key()
+        if not key:
+            raise RuntimeError(f"DeepSeek key missing (file {config.DSH_KEY_FILE})")
+        home = ctx.folder / "dsh-home"
+        home.mkdir(mode=0o700, exist_ok=True)
+        ctx.started.set()
+        with DeepSeekHarness(
+            cwd=ctx.spec["cwd"],
+            dsh_home=str(home),
+            model=self.model,
+            reasoning_effort=ctx.spec.get("effort") or "medium",
+            api_key=key,  # reaches the dsh process only; its shell tool does not inherit it
+            env={"PATH": "/usr/local/bin:/usr/bin:/bin", "HOME": str(home), "LANG": "C.UTF-8"},
+        ) as harness:
+            prompt = ctx.prompt + SUMMARY_RULE
+            run = harness.run(prompt, session_id=ctx.resume) if ctx.resume else harness.run(prompt)
+        with (ctx.folder / f"output-{ctx.attempt}.jsonl").open("a") as log:
+            for event in run.events:
+                if event.get("type") in ("assistant/message", "turn/end"):
+                    log.write(json.dumps(event)[:4000] + "\n")
+        return Outcome(
+            ok=run.finish_reason == "completed" and bool(run.final_response),
+            subtype=run.finish_reason or "error",
+            result=run.final_response or "",
+            session_id=run.session_id,
+            cost_usd=dsh_cost(run.events),
+        )

subtask/engines/kimi.py

@@ -0,0 +1,75 @@
+"""Kimi Code CLI (`kimi -p --output-format stream-json`). Tested with 2.1.1.
+
+Kimi 2.1 refuses `--prompt` together with `--auto` ("Cannot combine --prompt
+with --auto"); prompt mode already runs tools without asking.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .base import Capabilities, CliAdapter, RunContext, describe_command, json_line, short_command
+
+
+class Kimi(CliAdapter):
+    name = "kimi"
+    family = "kimi"
+    binary = "kimi"
+    supported = "kimi >=2.1"
+    capabilities = Capabilities(
+        readonly=False,  # --plan is a mode, not an enforced read-only boundary
+        levels=("worktree", "isolated"),
+        command_network_off=False,
+        cost="none",
+        resume=True,
+        structured_events=True,
+        paid=False,
+        notes="no engine sandbox: use level=isolated for a filesystem boundary",
+    )
+
+    def help_args(self) -> list[str]:
+        return ["--help"]
+
+    def required_flags(self) -> list[str]:
+        return ["--output-format", "--prompt", "--session"]
+
+    def auth_state(self) -> str:
+        return "present" if (Path.home() / ".kimi").is_dir() else "unknown"
+
+    def argv(self, ctx: RunContext) -> list[str]:
+        argv = ["kimi", "--output-format", "stream-json"]
+        if ctx.spec.get("model"):
+            argv += ["-m", ctx.spec["model"]]
+        if ctx.resume:
+            argv += ["-S", ctx.resume] if ctx.resume != "continue" else ["-c"]
+        return argv + ["-p", ctx.prompt]
+
+    def parse(self, line: str, state: dict) -> str | None:
+        event = json_line(line)
+        if not event:
+            return None
+        role = event.get("role")
+        if role == "meta" and event.get("type") == "session.resume_hint":
+            state["session"] = event.get("session_id")
+        elif role == "assistant":
+            if event.get("content"):
+                content = event["content"]
+                state["text"].append(content if isinstance(content, str) else json.dumps(content))
+            for call in event.get("tool_calls") or []:
+                fn = call.get("function") or {}
+                name = fn.get("name", "tool")
+                try:
+                    args = json.loads(fn.get("arguments") or "{}")
+                except json.JSONDecodeError:
+                    args = {}
+                state.setdefault("pending", {})[call.get("id")] = args.get("command")
+                if args.get("command"):
+                    return describe_command(short_command(args["command"]))
+                target = args.get("path") or args.get("file_path") or args.get("pattern") or ""
+                return f"{name} {Path(str(target)).name}".strip()
+        elif role == "tool":
+            command = state.get("pending", {}).pop(event.get("tool_call_id"), None)
+            if command:
+                state["commands"].append({"command": short_command(command), "exit_code": None})
+        return None

subtask/engines/opencode.py

@@ -0,0 +1,87 @@
+"""OpenCode CLI (`opencode run --format json`). Tested with v2.0.28."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .base import Capabilities, CliAdapter, RunContext, describe_command, json_line, short_command
+
+
+class OpenCode(CliAdapter):
+    name = "opencode"
+    family = "opencode"
+    binary = "opencode"
+    supported = "opencode >=2.0"
+    extra: tuple[str, ...] = ()
+    capabilities = Capabilities(
+        readonly=False,
+        levels=("worktree", "isolated"),
+        command_network_off=False,
+        cost="usd",
+        resume=True,
+        structured_events=True,
+        paid=False,
+        notes="cost is what OpenCode reports per step; billed by the provider, not the subtask cap",
+    )
+
+    def help_args(self) -> list[str]:
+        return ["run", "--help"]
+
+    def required_flags(self) -> list[str]:
+        return ["--format", "--auto", "--session", "--model"]
+
+    def auth_state(self) -> str:
+        auth = Path.home() / ".local" / "share" / "opencode" / "auth.json"
+        return "present" if auth.is_file() else "unknown"
+
+    def argv(self, ctx: RunContext) -> list[str]:
+        argv = ["opencode", "run", "--format", "json", "--auto", *self.extra]
+        model = ctx.spec.get("model") or self.model
+        if model:
+            argv += ["--model", model]
+        if ctx.resume:
+            argv += ["--session", ctx.resume] if ctx.resume != "continue" else ["--continue"]
+        return argv + ["--", ctx.prompt]
+
+    def parse(self, line: str, state: dict) -> str | None:
+        event = json_line(line)
+        if not event:
+            return None
+        state["session"] = event.get("sessionID") or state.get("session")
+        part = event.get("part") or {}
+        kind = event.get("type")
+        if kind == "tool_use":
+            tool = part.get("tool", "tool")
+            st = part.get("state") or {}
+            args = st.get("input") or {}
+            if args.get("command"):
+                cmd = short_command(args["command"])
+                if st.get("status") == "completed":
+                    exit_code = (st.get("metadata") or {}).get("exit")
+                    state["commands"].append({"command": cmd, "exit_code": exit_code})
+                return describe_command(cmd)
+            target = args.get("filePath") or args.get("path") or args.get("pattern") or ""
+            return f"{tool} {Path(str(target)).name}".strip()
+        if kind == "text":
+            state["text"].append(part.get("text") or "")
+        elif kind == "step_finish":
+            if isinstance(part.get("cost"), (int, float)):
+                state["cost_reported"] = state.get("cost_reported", 0.0) + part["cost"]
+            for key, value in (part.get("tokens") or {}).items():
+                if isinstance(value, int):
+                    state["tokens"][key] = state["tokens"].get(key, 0) + value
+        elif kind == "error":
+            err = event.get("error") or {}
+            state["error"] = str(err.get("message") or err)[:500]
+            if "quota" in str(err.get("type", "")) or err.get("status") == 402:
+                state["quota"] = True
+                state["error_kind"] = "quota exhausted"
+        return None
+
+
+class OpenCodeGo(OpenCode):
+    """OpenCode on the opencode-go subscription: fixed model, private server per job."""
+
+    name = "opencode-go"
+    model = "opencode-go/deepseek-v4.1-flash#max"
+    extra = ("--standalone",)

subtask/engines/registry.py

@@ -0,0 +1,124 @@
+"""Engine registry: built-ins plus plugins, without touching the core.
+
+Plugins: a package declares `[project.entry-points."subtask.engines"] name = "module:factory"`,
+or the environment lists `SUBTASK_ENGINE_PLUGINS=module:factory,...` (useful for tests).
+A factory returns an Adapter instance. Plugins with a different ADAPTER_API are refused.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from functools import cache
+
+from .base import ADAPTER_API, Adapter
+
+
+def _builtins() -> dict[str, Adapter]:
+    from .claude_api import ClaudeApi
+    from .codex import Codex
+    from .dsh import Dsh
+    from .kimi import Kimi
+    from .opencode import OpenCode, OpenCodeGo
+
+    engines: list[Adapter] = [
+        ClaudeApi("sonnet-api", "sonnet"),
+        ClaudeApi("haiku-api", "haiku"),
+        ClaudeApi("opus-api", "opus"),
+        Codex(),
+        Kimi(),
+        OpenCodeGo(),
+        OpenCode(),
+        Dsh(),
+    ]
+    if os.environ.get("SUBTASK_DEMO") == "1":
+        from .demo import Demo
+
+        engines.append(Demo())
+    return {e.name: e for e in engines}
+
+
+def _load(spec: str) -> Adapter:
+    module, _, attr = spec.partition(":")
+    factory = getattr(importlib.import_module(module), attr or "adapter")
+    adapter = factory() if callable(factory) and not isinstance(factory, Adapter) else factory
+    if not isinstance(adapter, Adapter):
+        raise TypeError(f"{spec} did not return an Adapter")
+    if getattr(adapter, "api", ADAPTER_API) != ADAPTER_API:
+        raise TypeError(f"{spec} targets adapter API {adapter.api}, this is {ADAPTER_API}")
+    return adapter
+
+
+GROUP = "subtask.engines"
+
+
+def _entry_points() -> list[str]:
+    """`subtask.engines` entry points, read straight from dist-info files.
+
+    importlib.metadata costs ~20 ms to import; this scan costs ~1 ms and reads
+    the same entry_points.txt files.
+    """
+    import sys
+    from pathlib import Path
+
+    found: list[str] = []
+    for root in sys.path:
+        try:
+            files = list(Path(root or ".").glob("*.dist-info/entry_points.txt"))
+        except OSError:
+            continue
+        for path in files:
+            try:
+                text = path.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            if f"[{GROUP}]" not in text:
+                continue
+            section = text.split(f"[{GROUP}]", 1)[1].split("\n[", 1)[0]
+            for line in section.splitlines():
+                name, sep, value = line.partition("=")
+                if sep and name.strip() and not line.lstrip().startswith(("#", ";")):
+                    found.append(value.strip())
+    return found
+
+
+@cache
+def _all() -> tuple[dict[str, Adapter], tuple[str, ...]]:
+    engines = _builtins()
+    errors: list[str] = []
+    specs = [s for s in os.environ.get("SUBTASK_ENGINE_PLUGINS", "").split(",") if s.strip()]
+    try:
+        specs += _entry_points()
+    except Exception as exc:  # noqa: BLE001 - broken metadata must not break the built-ins
+        errors.append(f"entry points unreadable: {type(exc).__name__}: {exc}")
+    for spec in specs:
+        try:
+            adapter = _load(spec.strip())
+        except Exception as exc:  # noqa: BLE001
+            errors.append(f"{spec}: {type(exc).__name__}: {exc}")
+            continue
+        if adapter.name in engines:
+            errors.append(f"{spec}: name {adapter.name!r} already taken")
+            continue
+        engines[adapter.name] = adapter
+    return engines, tuple(errors)
+
+
+def all_engines() -> dict[str, Adapter]:
+    return _all()[0]
+
+
+def plugin_errors() -> tuple[str, ...]:
+    return _all()[1]
+
+
+def get(name: str) -> Adapter | None:
+    return all_engines().get(name)
+
+
+def names() -> list[str]:
+    return list(all_engines())
+
+
+def reset() -> None:
+    _all.cache_clear()