subtask-mcp 0.2.11__tar.gz → 0.4.4__tar.gz

{subtask_mcp-0.2.11/subtask_mcp.egg-info → subtask_mcp-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subtask-mcp
-Version: 0.2.11
+Version: 0.4.4
 Summary: Background sub-agents for Claude Code, Codex, Kimi and OpenCode, over MCP or CLI, with a spend cap
 License: MIT
 Project-URL: Homepage, https://github.com/tedin7/subtask
@@ -111,15 +111,48 @@ redaction is a second layer, not a guarantee. See [SECURITY.md](SECURITY.md).
 
 | tool | what it does |
 |---|---|
-| `start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify)` | start one job |
-| `start_many(tasks)` | start several; partial success is listed per item |
-| `wait(ids, timeout=300, any=False, since=None)` | block until they end; progress notifications while waiting; `since` cursor for clients without progress |
+| `start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify, isolation, max_retries, adversarial, context_refs, auto_repomap, tier, invariants, allowed_paths, symbol_scope, oracle_cmd)` | start one job (see below) |
+| `start_many(tasks)` | start several; partial success is listed per item. Items with `id` and `depends_on` form a group (`grp-…`) run as a DAG without extra turns; `foreach=<parent id>` makes one copy per item of the parent's `.subtask/fanout.json` (at most 8), and dependents wait for every copy; `after="any"` starts when one parent succeeded |
+| `integrate(ids, action="apply", auto_resolve=False)` | worktree jobs back: `diff`, `apply` (all or nothing, uncommitted), `discard`; `auto_resolve` starts a reconciliation job on conflict |
+| `consensus(prompt, engines, verify_cmd, isolation="worktree")` | 2 to 4 engines solve it blind in their own worktrees, then one job compares their diffs as anonymous patches and writes one solution, checked by `verify_cmd` and the invariants; returns a group id |
+| `bisect(good_ref, bad_ref, test_cmd, parallelism=4, auto_fix=False)` | first commit that makes `test_cmd` fail, testing up to `parallelism` (max 8) commits per round in temporary worktrees; returns the commit, author and diff; `auto_fix` starts a verified fix job |
+| `map_reduce(glob_pattern, prompt_template, batch_size=5, concurrency=3, verify_cmd, isolation="worktree")` | one job per batch of files (`{{files}}` in the template), at most `concurrency` at a time; returns a group id |
+| `wait(ids, timeout=300, mode="all", since=None, stall_timeout=None)` | block until they end (`any`: the first; `first_success`: the first done and verified, the others are stopped); returns early on a stalled job; progress notifications while waiting; `since` cursor for clients without progress |
+| `steer(id, action, instruction=None)` | `hint` (queued, sent as a reply when the attempt ends), `abort`, `retry` (fresh job with the instruction) |
+| `inspect(id, tail=80, grep=None)` | raw log lines, only when the summary is not enough |
 | `status(id)` / `result(id, full, evidence)` | one line / summary or full text or JSON envelope |
 | `reply(id, message)` / `stop(id)` / `cleanup(id)` | continue / stop the work / remove a clean worktree (branch kept) |
 | `engines()` | capacity per engine with source, freshness and confidence, plus spend |
 | `step(title, path, how, decisions)` | an independent cheap model narrates the step from the repo's real state |
 
-CLI only: `subtask doctor`, `gc [--apply]`, `du`, `roi`, `routing explain|calibrate`,
+Options of `start`:
+
+- `isolation="worktree"`: own worktree and branch (like `repo=`), plus `SUBTASK_PORT` (from 18100),
+  `SUBTASK_ID` and a private `TMPDIR`. The result lists `files_modified` and `diff_stat`.
+- `verify` + `max_retries`: a failed check resumes the job with the output; when every retry fails, a
+  worktree goes back to its best attempt (scored from "N passed / N failed").
+- `adversarial=True`: a Breaker job writes edge-case tests from the spec only; they are copied into the
+  Builder's worktree and run with `verify`.
+- `context_refs`: `file:PATH[:A-B]`, `git:diff[:REF]`, `subtask:ID:summary|diff`, resolved before start.
+  `auto_repomap=True` adds tracked files with their top-level symbols (cached per HEAD).
+- `invariants` (default `["no_test_deletion", "no_suppression"]`, `[]` turns them off): before `verify` counts,
+  test functions may not decrease, no new skip/xfail markers, no new `# type: ignore`, `# noqa` or
+  `# pragma: no cover`. A violation is a failed check with the reason, so a retry sees it.
+- `allowed_paths`: files changed outside these paths are put back and the revert is committed.
+- `symbol_scope=["path.py::name", ...]`: only those top-level functions or classes may change in those
+  files. `integrate` then merges several jobs' edits to one Python file symbol by symbol; overlaps,
+  import or constant changes, and symbols changed on the target meanwhile are a conflict, never a guess.
+- `oracle_cmd`: after a passing `verify`, runs the command on the job's base and on its result at the same
+  time and reports whether exit code and stdout match, plus `duration_ms_before`, `duration_ms_after`,
+  `speedup_pct`.
+- `tier`: `fast` (effort low), `deep` (effort high, kind hard), `free_only`. Past 75% of the monthly cap,
+  `auto` and `balanced` go to free engines and the reply carries `budget_warning`.
+
+Memory: when a check fails and a retry fixes it, subtask stores a short lesson for that repository in
+`$SUBTASK_HOME/engrams/` (at most 50, least recently used dropped). Jobs on the same paths get the top three.
+Groups have a blackboard file for shared notes; new notes show in `wait(since=...)`.
+
+CLI only: `subtask board [--json]` (the view the OpenCode plugin renders), `subtask doctor`, `gc [--apply]`, `du`, `roi`, `routing explain|calibrate`,
 `watch ID...`, `install`, `uninstall`, and `--model`, `--no-sandbox`, `--untrusted` on start.
 
 ## Progress in the chat

{subtask_mcp-0.2.11 → subtask_mcp-0.4.4}/README.md

@@ -80,15 +80,48 @@ redaction is a second layer, not a guarantee. See [SECURITY.md](SECURITY.md).
 
 | tool | what it does |
 |---|---|
-| `start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify)` | start one job |
-| `start_many(tasks)` | start several; partial success is listed per item |
-| `wait(ids, timeout=300, any=False, since=None)` | block until they end; progress notifications while waiting; `since` cursor for clients without progress |
+| `start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify, isolation, max_retries, adversarial, context_refs, auto_repomap, tier, invariants, allowed_paths, symbol_scope, oracle_cmd)` | start one job (see below) |
+| `start_many(tasks)` | start several; partial success is listed per item. Items with `id` and `depends_on` form a group (`grp-…`) run as a DAG without extra turns; `foreach=<parent id>` makes one copy per item of the parent's `.subtask/fanout.json` (at most 8), and dependents wait for every copy; `after="any"` starts when one parent succeeded |
+| `integrate(ids, action="apply", auto_resolve=False)` | worktree jobs back: `diff`, `apply` (all or nothing, uncommitted), `discard`; `auto_resolve` starts a reconciliation job on conflict |
+| `consensus(prompt, engines, verify_cmd, isolation="worktree")` | 2 to 4 engines solve it blind in their own worktrees, then one job compares their diffs as anonymous patches and writes one solution, checked by `verify_cmd` and the invariants; returns a group id |
+| `bisect(good_ref, bad_ref, test_cmd, parallelism=4, auto_fix=False)` | first commit that makes `test_cmd` fail, testing up to `parallelism` (max 8) commits per round in temporary worktrees; returns the commit, author and diff; `auto_fix` starts a verified fix job |
+| `map_reduce(glob_pattern, prompt_template, batch_size=5, concurrency=3, verify_cmd, isolation="worktree")` | one job per batch of files (`{{files}}` in the template), at most `concurrency` at a time; returns a group id |
+| `wait(ids, timeout=300, mode="all", since=None, stall_timeout=None)` | block until they end (`any`: the first; `first_success`: the first done and verified, the others are stopped); returns early on a stalled job; progress notifications while waiting; `since` cursor for clients without progress |
+| `steer(id, action, instruction=None)` | `hint` (queued, sent as a reply when the attempt ends), `abort`, `retry` (fresh job with the instruction) |
+| `inspect(id, tail=80, grep=None)` | raw log lines, only when the summary is not enough |
 | `status(id)` / `result(id, full, evidence)` | one line / summary or full text or JSON envelope |
 | `reply(id, message)` / `stop(id)` / `cleanup(id)` | continue / stop the work / remove a clean worktree (branch kept) |
 | `engines()` | capacity per engine with source, freshness and confidence, plus spend |
 | `step(title, path, how, decisions)` | an independent cheap model narrates the step from the repo's real state |
 
-CLI only: `subtask doctor`, `gc [--apply]`, `du`, `roi`, `routing explain|calibrate`,
+Options of `start`:
+
+- `isolation="worktree"`: own worktree and branch (like `repo=`), plus `SUBTASK_PORT` (from 18100),
+  `SUBTASK_ID` and a private `TMPDIR`. The result lists `files_modified` and `diff_stat`.
+- `verify` + `max_retries`: a failed check resumes the job with the output; when every retry fails, a
+  worktree goes back to its best attempt (scored from "N passed / N failed").
+- `adversarial=True`: a Breaker job writes edge-case tests from the spec only; they are copied into the
+  Builder's worktree and run with `verify`.
+- `context_refs`: `file:PATH[:A-B]`, `git:diff[:REF]`, `subtask:ID:summary|diff`, resolved before start.
+  `auto_repomap=True` adds tracked files with their top-level symbols (cached per HEAD).
+- `invariants` (default `["no_test_deletion", "no_suppression"]`, `[]` turns them off): before `verify` counts,
+  test functions may not decrease, no new skip/xfail markers, no new `# type: ignore`, `# noqa` or
+  `# pragma: no cover`. A violation is a failed check with the reason, so a retry sees it.
+- `allowed_paths`: files changed outside these paths are put back and the revert is committed.
+- `symbol_scope=["path.py::name", ...]`: only those top-level functions or classes may change in those
+  files. `integrate` then merges several jobs' edits to one Python file symbol by symbol; overlaps,
+  import or constant changes, and symbols changed on the target meanwhile are a conflict, never a guess.
+- `oracle_cmd`: after a passing `verify`, runs the command on the job's base and on its result at the same
+  time and reports whether exit code and stdout match, plus `duration_ms_before`, `duration_ms_after`,
+  `speedup_pct`.
+- `tier`: `fast` (effort low), `deep` (effort high, kind hard), `free_only`. Past 75% of the monthly cap,
+  `auto` and `balanced` go to free engines and the reply carries `budget_warning`.
+
+Memory: when a check fails and a retry fixes it, subtask stores a short lesson for that repository in
+`$SUBTASK_HOME/engrams/` (at most 50, least recently used dropped). Jobs on the same paths get the top three.
+Groups have a blackboard file for shared notes; new notes show in `wait(since=...)`.
+
+CLI only: `subtask board [--json]` (the view the OpenCode plugin renders), `subtask doctor`, `gc [--apply]`, `du`, `roi`, `routing explain|calibrate`,
 `watch ID...`, `install`, `uninstall`, and `--model`, `--no-sandbox`, `--untrusted` on start.
 
 ## Progress in the chat

{subtask_mcp-0.2.11 → subtask_mcp-0.4.4}/subtask/__init__.py

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

subtask_mcp-0.4.4/subtask/ast_merge.py

@@ -0,0 +1,124 @@
+"""Merge Python files by top-level symbol instead of by line.
+
+Each job's change to a file is read as a set of replaced, added or removed
+top-level functions and classes. When the jobs' sets do not overlap, and none
+of them changes module-level statements (imports, constants), the symbols are
+grafted onto the base text one by one. Anything else is a conflict: nothing is
+guessed.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+
+MODULE = "<module>"
+DEFS = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+
+
+class Conflict(Exception):
+    pass
+
+
+def _lines(text: str) -> list[str]:
+    """Lines as ast counts them: only \\n ends a line (splitlines also splits on form feeds)."""
+    if re.search(r"\r(?!\n)", text):
+        raise SyntaxError("lone carriage return")
+    return re.findall(r"[^\n]*\n|[^\n]+$", text)
+
+
+def _main_guard(tree: ast.Module) -> int | None:
+    """First line of a top-level `if __name__ == "__main__":`, where new symbols must go before."""
+    for node in tree.body:
+        test = getattr(node, "test", None)
+        is_compare = isinstance(node, ast.If) and isinstance(test, ast.Compare)
+        if is_compare and isinstance(test.left, ast.Name) and test.left.id == "__name__":
+            return node.lineno
+    return None
+
+
+def _parts(text: str) -> tuple[dict[str, tuple[int, int, str]], list[str]]:
+    """{name: (first line, last line, source)} for top-level defs, and everything else.
+
+    A second def with the same name is keyed name#2. Everything outside the defs (statements,
+    comments) is kept as non-blank text, so a change there is a module-level change.
+    """
+    tree = ast.parse(text)
+    lines = _lines(text)
+    defs: dict[str, tuple[int, int, str]] = {}
+    taken = [False] * (len(lines) + 1)
+    for node in tree.body:
+        if not isinstance(node, DEFS):
+            continue
+        start = min([node.lineno] + [d.lineno for d in node.decorator_list])
+        end = node.end_lineno or node.lineno
+        name, n = node.name, 1
+        while name in defs:
+            n += 1
+            name = f"{node.name}#{n}"
+        defs[name] = (start, end, "".join(lines[start - 1 : end]))
+        for i in range(start, end + 1):
+            taken[i] = True
+    other = [line.strip() for i, line in enumerate(lines, 1) if not taken[i] and line.strip()]
+    return defs, other
+
+
+def changed_symbols(old: str, new: str) -> set[str]:
+    """Top-level names whose source differs; MODULE when other statements differ. Raises SyntaxError."""
+    old_defs, old_other = _parts(old) if old else ({}, [])
+    new_defs, new_other = _parts(new) if new else ({}, [])
+    names = {
+        n
+        for n in old_defs.keys() | new_defs.keys()
+        if (old_defs.get(n) or (0, 0, ""))[2] != (new_defs.get(n) or (0, 0, ""))[2]
+    }
+    if old_other != new_other:
+        names.add(MODULE)
+    return names
+
+
+def graft(base: str, versions: list[tuple[str, str, str]]) -> str:
+    """Apply each (job id, its base text, its new text) symbol by symbol onto base. Raises Conflict."""
+    try:
+        base_defs, _ = _parts(base)
+    except SyntaxError as exc:
+        raise Conflict(f"base is not valid Python ({exc.msg})") from exc
+    owner: dict[str, str] = {}
+    edits: list[tuple[str, str | None]] = []  # (name, new source or None for removed)
+    for job_id, old, text in versions:
+        try:
+            new_defs, _ = _parts(text)
+            old_defs, _ = _parts(old) if old else ({}, [])
+            names = changed_symbols(old, text)
+        except SyntaxError as exc:
+            raise Conflict(f"{job_id}: not valid Python ({exc.msg})") from exc
+        if MODULE in names:
+            raise Conflict(f"{job_id} changes module-level statements (imports or constants)")
+        for name in names:
+            if name in owner:
+                raise Conflict(f"{owner[name]} and {job_id} both change {name}")
+            owner[name] = job_id
+            if (base_defs.get(name) or (0, 0, ""))[2] != (old_defs.get(name) or (0, 0, ""))[2]:
+                raise Conflict(f"{name} changed on the target too since {job_id} started")
+            edits.append((name, new_defs[name][2] if name in new_defs else None))
+    lines = _lines(base)
+    added = "".join(
+        source.rstrip("\n") + "\n\n\n"
+        for _, source in sorted(e for e in edits if e[0] not in base_defs)
+        if source
+    )
+    guard = _main_guard(ast.parse(base))
+    # (first line, last line, new text); applied bottom-up so earlier line numbers stay valid
+    ops = [(base_defs[n][0], base_defs[n][1], src or "") for n, src in edits if n in base_defs]
+    if added and guard is not None:  # before the main block, which may call them
+        ops.append((guard, guard - 1, added))
+    for start, end, src in sorted(ops, key=lambda o: (-o[0], -o[1])):
+        lines[start - 1 : end] = [src] if src else []
+    text = "".join(lines)
+    if added and guard is None:
+        text = text.rstrip("\n") + "\n\n\n" + added.rstrip("\n") + "\n"
+    try:
+        ast.parse(text)
+    except SyntaxError as exc:
+        raise Conflict(f"merged file is not valid Python ({exc.msg})") from exc
+    return text

subtask_mcp-0.4.4/subtask/bisect_tool.py

@@ -0,0 +1,141 @@
+"""K-ary parallel bisect: test up to K commits at once to find the first one that breaks a check.
+
+The commits between good (passes) and bad (fails) are taken in first-parent
+order. Each round tests K evenly spaced commits in temporary worktrees, at the
+same time, and keeps the interval between the last pass and the first failure.
+Rounds needed: about log_(K+1) of the commit count. Worktrees are always removed.
+"""
+
+from __future__ import annotations
+
+import secrets
+import shutil
+import subprocess
+import time
+from concurrent.futures import ThreadPoolExecutor
+
+from . import config, jobs
+
+TIMEOUT_S = 900
+MAX_COMMITS = 5000
+MAX_DIFF = 12000
+
+
+def _git(repo: str, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", repo, *args], capture_output=True, text=True, timeout=120, check=False
+    )
+
+
+def _passes(repo: str, commit: str, cmd: str) -> bool:
+    scratch = str(config.HOME / "bisect" / secrets.token_hex(4))
+    try:
+        if _git(repo, "worktree", "add", "-q", "--detach", scratch, commit).returncode != 0:
+            raise RuntimeError(f"worktree for {commit[:9]} not created")
+        try:
+            done = subprocess.run(
+                ["sh", "-c", cmd], cwd=scratch, capture_output=True, timeout=TIMEOUT_S, check=False,
+                stdin=subprocess.DEVNULL,
+            )  # fmt: skip
+            return done.returncode == 0
+        except subprocess.TimeoutExpired:
+            return False
+    finally:
+        _git(repo, "worktree", "remove", "--force", scratch)
+        shutil.rmtree(scratch, ignore_errors=True)
+
+
+def _note(run: str, **fields) -> None:
+    """Progress a client panel can show while the bisect runs (subtask board)."""
+    path = config.HOME / "bisect-runs" / f"{run}.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():  # keep the folder small: the 20 newest runs
+        for stale in sorted(path.parent.glob("*.json"), key=lambda p: p.stat().st_mtime)[:-19]:
+            stale.unlink(missing_ok=True)
+    old = jobs.read_json(path) if path.is_file() else {}
+    jobs.write_json(path, {**old, **fields, "updated": time.time()})
+
+
+def recent(limit: int = 3, max_age_s: float = 86400) -> list[dict]:
+    folder = config.HOME / "bisect-runs"
+    if not folder.is_dir():
+        return []
+    rows = [
+        jobs.read_json(p)
+        for p in sorted(folder.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+    ]
+    return [r for r in rows if time.time() - float(r.get("updated") or 0) < max_age_s][:limit]
+
+
+def find(repo: str, good: str, bad: str, cmd: str, parallelism: int = 4) -> dict:
+    """{'commit', 'rounds', 'tested'} or {'error'}."""
+    resolved = []
+    for ref in (good, bad):
+        if ref.startswith("-"):
+            return {"error": f"invalid ref: {ref}"}
+        done = _git(repo, "rev-parse", "--verify", "--end-of-options", ref + "^{commit}")
+        if done.returncode != 0:
+            return {"error": f"unknown ref: {ref}"}
+        resolved.append(done.stdout.strip())
+    good_sha, bad_sha = resolved
+    if _git(repo, "merge-base", "--is-ancestor", good_sha, bad_sha).returncode != 0:
+        return {"error": "good_ref is not an ancestor of bad_ref"}
+    commits = _git(repo, "rev-list", "--first-parent", "--reverse", f"{good_sha}..{bad_sha}").stdout.split()
+    if not commits or len(commits) > MAX_COMMITS:
+        return {"error": f"{len(commits)} commits between good and bad (1 to {MAX_COMMITS} allowed)"}
+    k = max(1, min(int(parallelism), 8))
+    run = "bis-" + secrets.token_hex(4)
+    _note(run, id=run, test_cmd=cmd, candidates=len(commits), round=0, tested=0, state="running")
+    try:
+        return _search(repo, commits, cmd, k, run)
+    except (RuntimeError, OSError, subprocess.SubprocessError) as exc:
+        _note(run, state="failed", error=str(exc)[:200])
+        return {"error": f"bisect stopped: {exc}"}
+
+
+def _search(repo: str, commits: list[str], cmd: str, k: int, run: str) -> dict:
+    lo, hi = -1, len(commits) - 1  # commits[lo] passes (-1 = good), commits[hi] fails (bad)
+    rounds, tested = 0, 0
+    with ThreadPoolExecutor(k) as pool:
+        confirmed = False  # bad_ref itself is tested in the first round
+        while hi - lo > 1 or not confirmed:
+            span = hi - lo - 1
+            picks = sorted({lo + 1 + (span * (i + 1)) // (k + 1) for i in range(min(k, span))})
+            if not confirmed:
+                picks = sorted(set(picks) | {hi})
+            results = dict(zip(picks, pool.map(lambda i: _passes(repo, commits[i], cmd), picks)))
+            if not confirmed:
+                confirmed = True
+                if results[hi]:
+                    _note(run, state="failed", error="test_cmd passes on bad_ref")
+                    return {"error": "test_cmd passes on bad_ref: nothing to find"}
+            rounds, tested = rounds + 1, tested + len(picks)
+            _note(run, round=rounds, tested=tested, left=max(hi - lo - 1, 0))
+            for i in picks:  # the interval ends at the first failing pick
+                if results[i]:
+                    lo = i
+                else:
+                    hi = i
+                    break
+    _note(run, state="done", commit=commits[hi], round=rounds, tested=tested, left=0)
+    return {"commit": commits[hi], "rounds": rounds, "tested": tested, "candidates": len(commits)}
+
+
+def report(repo: str, found: dict) -> str:
+    if found.get("error"):
+        return found["error"]
+    sha = found["commit"]
+    meta = _git(repo, "show", "-s", "--format=%H%n%an <%ae>%n%ad%n%s", sha).stdout.strip()
+    diff = _git(repo, "show", "--stat", "--patch", "--format=", sha).stdout
+    diff = diff[:MAX_DIFF] + ("\n… diff cut" if len(diff) > MAX_DIFF else "")
+    head = (
+        f"first bad commit: {meta}\n"
+        f"{found['candidates']} candidates, {found['tested']} tested in {found['rounds']} parallel rounds"
+    )
+    return head + "\n\n" + diff
+
+
+FIX_TASK = (
+    "Commit {sha} made `{cmd}` fail. Fix the regression without undoing what that commit was for. "
+    "Run the check, commit, and finish with a ## Summary.\n\nThe commit:\n{diff}"
+)

{subtask_mcp-0.2.11 → subtask_mcp-0.4.4}/subtask/cli.py

@@ -3,6 +3,8 @@
 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 steer ID hint|abort|retry ["text"] | inspect ID [--tail N] [--grep W] | board [--json]
+subtask integrate ID... [--action diff|apply|discard] [--auto-resolve] | map-reduce GLOB "tpl {{files}}"
 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...
 
@@ -48,6 +50,7 @@ def main() -> int:
     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")
+    w.add_argument("--mode", choices=["all", "any", "first_success"])
     st = sub.add_parser("status")
     st.add_argument("id", nargs="?")
     r = sub.add_parser("result")
@@ -81,6 +84,30 @@ def main() -> int:
     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")
+    bo = sub.add_parser("board", help="groups, jobs, verify and budget in one view (the OpenCode panel)")
+    bo.add_argument("--json", action="store_true")
+    bo.add_argument("--limit", type=int, default=10)
+    se = sub.add_parser("steer")
+    se.add_argument("id")
+    se.add_argument("action", choices=["hint", "abort", "retry"])
+    se.add_argument("instruction", nargs="?")
+    ins = sub.add_parser("inspect")
+    ins.add_argument("id")
+    ins.add_argument("--tail", type=int, default=80)
+    ins.add_argument("--grep")
+    ig = sub.add_parser("integrate")
+    ig.add_argument("ids", nargs="+")
+    ig.add_argument("--action", default="apply", choices=["diff", "apply", "discard"])
+    ig.add_argument("--auto-resolve", action="store_true")
+    mr = sub.add_parser("map-reduce")
+    mr.add_argument("glob")
+    mr.add_argument("template", help="prompt with {{files}}")
+    mr.add_argument("--batch-size", type=int, default=5)
+    mr.add_argument("--concurrency", type=int, default=3)
+    mr.add_argument("--verify")
+    mr.add_argument("--isolation", default="worktree", choices=["shared", "worktree"])
+    mr.add_argument("--repo")
+    mr.add_argument("--engine", default="auto")
     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)
@@ -90,6 +117,9 @@ def main() -> int:
         from . import stephook
 
         return stephook.main()
+    if a.cmd == "install-skill":
+        print("\n".join(install_commands.install_skill(a.dest, a.client)))
+        return 0
     if a.cmd in ("install", "uninstall") or (a.cmd == "doctor" and a.client):
         return install_commands.run(a)
 
@@ -114,7 +144,7 @@ def main() -> int:
             untrusted=a.untrusted,
         )
     elif a.cmd == "wait":
-        out = core.wait(a.ids, a.timeout, a.any, not a.no_results, since=a.since)
+        out = core.wait(a.ids, a.timeout, a.any, not a.no_results, since=a.since, mode=a.mode)
     elif a.cmd == "status":
         out = core.status(a.id)
     elif a.cmd == "result":
@@ -152,6 +182,23 @@ def main() -> int:
 
         wanted = policy.demand(a.readonly, a.policy)
         out = router.explain(a.kind, None, wanted) if a.action == "explain" else router.calibrate()
+    elif a.cmd == "board":
+        import json
+
+        out = json.dumps(core.board_data(a.limit)) if a.json else core.board(a.limit)
+    elif a.cmd == "steer":
+        out = core.steer(a.id, a.action, a.instruction)
+    elif a.cmd == "inspect":
+        out = core.inspect(a.id, a.tail, a.grep)
+    elif a.cmd == "integrate":
+        from .integrate import integrate
+
+        out = integrate(a.ids, a.action, a.auto_resolve)
+    elif a.cmd == "map-reduce":
+        from .map_reduce import map_reduce
+
+        out = map_reduce(a.glob, a.template, a.batch_size, a.concurrency, a.verify, a.isolation, a.repo,
+                         None, a.engine)  # fmt: skip
     elif a.cmd == "watch":
         return _watch(a.ids, a.interval)
     else:

subtask_mcp-0.4.4/subtask/context.py

@@ -0,0 +1,140 @@
+"""Context resolved on the server before a job starts, so the worker does not spend turns finding it.
+
+References:
+  file:PATH            file:PATH:START-END     (inside the job's folder only)
+  git:diff             git:diff:REF
+  subtask:ID:summary   subtask:ID:diff
+Plus an optional repo map: tracked files with their top-level symbols, cached per HEAD.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import re
+import subprocess
+from pathlib import Path
+
+from . import config
+
+MAX_REF = 20_000
+MAX_TOTAL = 60_000
+MAX_MAP = 15_000
+SYMBOL = {
+    ".ts": re.compile(
+        r"^(?:export\s+)?(?:async\s+)?(?:function|class|interface|type|const)\s+(\w+)", re.MULTILINE
+    ),
+    ".js": re.compile(r"^(?:export\s+)?(?:async\s+)?(?:function|class|const)\s+(\w+)", re.MULTILINE),
+    ".go": re.compile(r"^(?:func|type)\s+(?:\([^)]*\)\s*)?(\w+)", re.MULTILINE),
+    ".rs": re.compile(r"^\s*(?:pub\s+)?(?:fn|struct|enum|trait)\s+(\w+)", re.MULTILINE),
+}
+SYMBOL[".tsx"] = SYMBOL[".ts"]
+
+
+def _git(root: str, *args: str) -> str:
+    done = subprocess.run(["git", "-C", root, *args], capture_output=True, text=True, timeout=30, check=False)
+    return done.stdout if done.returncode == 0 else ""
+
+
+def _file(root: Path, ref: str) -> str:
+    match = re.fullmatch(r"(.+?)(?::(\d+)-(\d+))?", ref)
+    assert match
+    path = (root / match.group(1)).resolve()
+    if not path.is_relative_to(root.resolve()):
+        raise ValueError(f"outside the job folder: {match.group(1)}")
+    if not path.is_file():
+        raise ValueError(f"no such file: {match.group(1)}")
+    lines = path.read_text(errors="replace").splitlines()
+    if match.group(2):
+        a, b = int(match.group(2)), int(match.group(3))
+        lines = lines[max(a - 1, 0) : b]
+    return "\n".join(lines)
+
+
+def _subtask(ref: str) -> str:
+    from . import core, jobs
+
+    job_id, _, what = ref.partition(":")
+    if not core.known(job_id):
+        raise ValueError(f"unknown job: {job_id}")
+    if what == "summary":
+        path = jobs.job_dir(job_id) / "result.md"
+        return core.summary_of(path.read_text()) if path.is_file() else ""
+    if what == "diff":
+        sp = jobs.spec(job_id)
+        if not sp.get("branch"):
+            raise ValueError(f"{job_id} has no branch")
+        return _git(sp["repo"], "diff", f"{sp['base']}..{sp['branch']}")
+    raise ValueError("subtask refs end in :summary or :diff")
+
+
+def resolve(refs: list[str], root: str) -> str:
+    """The <subtask_context> block for `refs`. Raises ValueError on a bad reference."""
+    if not isinstance(refs, list) or not all(isinstance(r, str) for r in refs):
+        raise ValueError("context_refs must be a list of strings")
+    parts, total = [], 0
+    for ref in refs:
+        kind, _, rest = ref.partition(":")
+        if kind == "file":
+            body = _file(Path(root), rest)
+        elif kind == "git":
+            if rest != "diff" and not rest.startswith("diff:"):
+                raise ValueError(f"unknown git ref: {ref}")
+            target = rest.removeprefix("diff").removeprefix(":")
+            if target.startswith("-"):
+                raise ValueError(f"invalid git ref: {ref}")
+            body = _git(root, "diff", *([target] if target else []))
+        elif kind == "subtask":
+            body = _subtask(rest)
+        else:
+            raise ValueError(f"unknown reference: {ref}")
+        body = body[:MAX_REF] + ("\n… cut" if len(body) > MAX_REF else "")
+        if total + len(body) > MAX_TOTAL:
+            parts.append(f'<ref name="{ref}">left out: context limit reached</ref>')
+            continue
+        total += len(body)
+        parts.append(f'<ref name="{ref}">\n{body}\n</ref>')
+    return "<subtask_context>\n" + "\n".join(parts) + "\n</subtask_context>" if parts else ""
+
+
+MAX_FILE = 1_000_000
+
+
+def _symbols(path: Path) -> list[str]:
+    """Top-level names of a regular file; symlinks, FIFOs and devices are never opened."""
+    try:
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_FILE:
+            return []
+        text = path.read_text(errors="replace")
+    except OSError:
+        return []
+    if path.suffix == ".py":
+        try:
+            tree = ast.parse(text)
+        except (SyntaxError, ValueError):
+            return []
+        return [
+            n.name for n in tree.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
+        ]
+    pattern = SYMBOL.get(path.suffix)
+    return pattern.findall(text) if pattern else []
+
+
+def repomap(root: str) -> str:
+    """Tracked files with their top-level symbols; cached until HEAD changes."""
+    head = _git(root, "rev-parse", "HEAD").strip()
+    if not head:
+        return ""
+    key = hashlib.sha256(f"{Path(root).resolve()}@{head}".encode()).hexdigest()[:16]
+    cache = config.HOME / "repomap" / f"{key}.txt"
+    if cache.is_file():
+        return cache.read_text()
+    lines = []
+    for name in _git(root, "ls-files").splitlines():
+        symbols = _symbols(Path(root) / name)
+        lines.append(f"{name}: {', '.join(symbols[:12])}" if symbols else name)
+    text = "\n".join(lines)
+    text = text[:MAX_MAP] + ("\n… map cut" if len(text) > MAX_MAP else "")
+    cache.parent.mkdir(parents=True, exist_ok=True)
+    cache.write_text(text)
+    return text