subtask-mcp 0.2.3__py3-none-any.whl

subtask/schemacheck.py

@@ -0,0 +1,131 @@
+"""Semantic checks for published tool schemas, independent of how they were generated.
+
+The slimming in server.py once dropped every key named "title", including the
+real `step.title` parameter: the published schema then required a property it
+never declared. A parity test could not see it, because both sides went
+through the same transformation. These checks look at the meaning instead.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+TYPES = {"string", "number", "integer", "boolean", "object", "array", "null"}
+MAX_DEPTH = 32
+
+
+def problems(schema: Any, where: str = "$") -> list[str]:
+    """Every semantic defect found in a JSON Schema object (2020-12 subset)."""
+    out: list[str] = []
+    _walk(schema, schema, where, out, 0)
+    return out
+
+
+def _resolve(root: dict, ref: str) -> Any:
+    if not ref.startswith("#/"):
+        raise ValueError(f"non-local $ref not allowed: {ref}")
+    node: Any = root
+    for part in ref[2:].split("/"):
+        part = part.replace("~1", "/").replace("~0", "~")
+        if not isinstance(node, dict) or part not in node:
+            raise KeyError(ref)
+        node = node[part]
+    return node
+
+
+def _declared(root: dict, schema: dict, seen: frozenset = frozenset()) -> set[str] | None:
+    """Property names an object schema declares, following $ref and allOf. None = open."""
+    if "$ref" in schema:
+        ref = schema["$ref"]
+        if ref in seen:
+            return set()
+        return _declared(root, _resolve(root, ref), seen | {ref})
+    names = set(schema.get("properties", {}))
+    for sub in schema.get("allOf", []):
+        if isinstance(sub, dict):
+            more = _declared(root, sub, seen)
+            if more is None:
+                return None
+            names |= more
+    if schema.get("patternProperties"):
+        return None  # required names may be matched by a pattern: cannot judge
+    return names
+
+
+def _walk(root: Any, node: Any, where: str, out: list[str], depth: int) -> None:
+    if depth > MAX_DEPTH:
+        out.append(f"{where}: deeper than {MAX_DEPTH}")
+        return
+    if isinstance(node, list):
+        for i, item in enumerate(node):
+            _walk(root, item, f"{where}[{i}]", out, depth + 1)
+        return
+    if not isinstance(node, dict):
+        return
+    if "$ref" in node:
+        try:
+            _resolve(root, node["$ref"])
+        except (KeyError, ValueError) as exc:
+            out.append(f"{where}: unresolved $ref {exc}")
+    kind = node.get("type")
+    kinds = kind if isinstance(kind, list) else [kind] if kind else []
+    for k in kinds:
+        if k not in TYPES:
+            out.append(f"{where}: unknown type {k!r}")
+    if "properties" in node and not isinstance(node["properties"], dict):
+        out.append(f"{where}: properties is not an object")
+    required = node.get("required")
+    if required is not None:
+        if not isinstance(required, list) or not all(isinstance(r, str) for r in required):
+            out.append(f"{where}: required must be a list of names")
+        else:
+            declared = _declared(root, node) if isinstance(root, dict) else set()
+            if declared is not None:
+                missing = [r for r in required if r not in declared]
+                # A required name nobody declares is a contract bug, closed or open:
+                # clients build forms and calls from `properties`.
+                for name in missing:
+                    out.append(f"{where}: required {name!r} not declared in properties")
+    for key, value in node.items():
+        if key == "properties" and isinstance(value, dict):
+            for name, sub in value.items():
+                _walk(root, sub, f"{where}.properties.{name}", out, depth + 1)
+        elif key in ("items", "additionalProperties", "not", "if", "then", "else", "contains") or key in (
+            "anyOf",
+            "oneOf",
+            "allOf",
+            "prefixItems",
+        ):
+            _walk(root, value, f"{where}.{key}", out, depth + 1)
+        elif key in ("$defs", "definitions") and isinstance(value, dict):
+            for name, sub in value.items():
+                _walk(root, sub, f"{where}.{key}.{name}", out, depth + 1)
+    if "default" in node and kinds and not _matches(node["default"], kinds):
+        out.append(f"{where}: default {node['default']!r} is not {kinds}")
+
+
+def _matches(value: Any, kinds: list[str]) -> bool:
+    checks = {
+        "string": lambda v: isinstance(v, str),
+        "number": lambda v: isinstance(v, (int, float)) and not isinstance(v, bool),
+        "integer": lambda v: isinstance(v, int) and not isinstance(v, bool),
+        "boolean": lambda v: isinstance(v, bool),
+        "object": lambda v: isinstance(v, dict),
+        "array": lambda v: isinstance(v, list),
+        "null": lambda v: v is None,
+    }
+    return any(checks[k](value) for k in kinds if k in checks)
+
+
+def tool_problems(tools: list[dict]) -> list[str]:
+    out: list[str] = []
+    names = [t.get("name") for t in tools]
+    for dup in {n for n in names if names.count(n) > 1}:
+        out.append(f"duplicate tool {dup}")
+    for tool in tools:
+        schema = tool.get("inputSchema")
+        if not isinstance(schema, dict) or schema.get("type") != "object":
+            out.append(f"{tool.get('name')}: inputSchema must be an object schema")
+            continue
+        out += problems(schema, tool.get("name", "?"))
+    return out

subtask/server.py

@@ -0,0 +1,192 @@
+"""MCP server (stdio).
+
+Instructions and tool descriptions are injected into every client session, so
+they are kept short. The full usage guide is the `subtask` skill (subtask/skill/SKILL.md).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from mcp.server.fastmcp import Context, FastMCP
+
+from . import core
+
+mcp = FastMCP(
+    "subtask",
+    instructions=(
+        "Background sub-agents for parallel, long or review work; small edits do yourself. "
+        "Pattern: ONE start_many([...]) with every job, then ONE wait(ids): it blocks and returns "
+        "the summaries. Never poll status(); call wait() again only if it said 'still running'. "
+        "result(id, full/evidence) only when the summary is not enough. "
+        "Call step() before each significant step."
+    ),
+)
+
+
+@mcp.tool(structured_output=False)
+def start(
+    task: str,
+    kind: str = "code",
+    repo: str | None = None,
+    cwd: str | None = None,
+    files: list[str] | None = None,
+    readonly: bool = False,
+    engine: str = "auto",
+    max_usd: float | None = None,
+    effort: str = "medium",
+    base: str = "HEAD",
+    max_turns: int = 60,
+    policy: str | None = None,
+    verify: str | None = None,
+) -> str:
+    """Start a job. kind: read|code|review|hard. repo: new worktree. policy: worktree|sandbox|isolated|untrusted. verify: check command."""
+    return core.start(
+        task, engine, repo, cwd, base, readonly, max_usd, max_turns, effort,
+        kind=kind, files=files, policy=policy, verify=verify,
+    )  # fmt: skip
+
+
+@mcp.tool(structured_output=False)
+def start_many(tasks: list[dict]) -> str:
+    """Items take start()'s arguments."""
+    return core.start_many(tasks)
+
+
+@mcp.tool(structured_output=False)
+async def wait(
+    ids: list[str],
+    timeout: int = 300,
+    any: bool = False,
+    since: str | None = None,
+    ctx: Context | None = None,
+) -> str:
+    """Wait for jobs (any=True: first); returns summaries. since: cursor for changes."""
+    # Poll on the event loop with asyncio.sleep: no thread is held while waiting,
+    # so any number of waits never delays stop() or status().
+    loop = asyncio.get_running_loop()
+    reporter = None
+    pending: list = []
+    token = ctx.request_context.meta.progressToken if ctx and ctx.request_context.meta else None
+    if token is not None:
+        from .progress import Reporter
+
+        def send(value: float, message: str, total: float | None) -> None:
+            pending.append(ctx.report_progress(value, total, message))  # awaited before the reply
+
+        reporter = Reporter(send, [i for i in ids if core.known(i)])
+    deadline = loop.time() + max(1, min(timeout, 600))
+    while True:
+        if reporter:
+            reporter.poll()
+            while pending:
+                await pending.pop(0)  # never after the result: progress stops at completion
+        out = core.wait(ids, 0, any, since=since)
+        if not out.startswith("still running") or loop.time() >= deadline:
+            return out
+        await asyncio.sleep(1)
+
+
+@mcp.tool(structured_output=False)
+def status(id: str | None = None) -> str:
+    """One line per job."""
+    return core.status(id)
+
+
+@mcp.tool(structured_output=False)
+def result(id: str, full: bool = False, evidence: bool = False) -> str:
+    """Job summary; full=True for all; evidence=True for the JSON envelope."""
+    return core.result(id, full, evidence)
+
+
+@mcp.tool(structured_output=False)
+def reply(id: str, message: str) -> str:
+    """Continue a finished job."""
+    return core.reply(id, message)
+
+
+@mcp.tool(structured_output=False)
+async def stop(id: str) -> str:
+    """Stop a job."""
+    return await asyncio.to_thread(core.stop, id)
+
+
+@mcp.tool(structured_output=False)
+def cleanup(id: str) -> str:
+    """Remove a job's worktree, keep branch."""
+    return core.cleanup(id)
+
+
+@mcp.tool(structured_output=False)
+def engines() -> str:
+    """Free quota and API spend."""
+    return core.engines() + "\n" + core.spend()
+
+
+@mcp.tool(structured_output=False)
+async def step(
+    title: str, path: str, how: str, decisions: list[str] | None = None, repo: str | None = None
+) -> str:
+    """Before each significant step. Paste the reply verbatim; on STOP ask the user."""
+    return await asyncio.to_thread(core.step, title, path, how, decisions, repo)
+
+
+ANNOTATIONS = ("title",)
+
+
+def _slim(schema: object, names: bool = False) -> object:
+    """Drop what the client never needs: annotation titles, and the null branch of optionals.
+
+    `names=True` means `schema` maps property names to subschemas (the value of
+    "properties", "$defs"...): its keys are names, never annotations, so a
+    parameter called `title` survives.
+    """
+    if isinstance(schema, list):
+        return [_slim(item) for item in schema]
+    if not isinstance(schema, dict):
+        return schema
+    if names:
+        return {k: _slim(v) for k, v in schema.items()}
+    out = {
+        k: _slim(v, names=k in ("properties", "$defs", "definitions", "patternProperties"))
+        for k, v in schema.items()
+        if k not in ANNOTATIONS
+    }
+    branches = out.get("anyOf")
+    if isinstance(branches, list):
+        kept = [b for b in branches if b != {"type": "null"}]
+        if len(kept) == 1:
+            out.pop("anyOf")
+            out.update(kept[0])
+    if out.get("default", 0) is None:
+        out.pop("default")
+    return out
+
+
+for _tool in mcp._tool_manager.list_tools():
+    _tool.parameters = _slim(_tool.parameters)
+
+
+def dump_tools() -> dict:
+    """The canonical published spec; tools.json is generated from it (`--dump-tools`)."""
+    tools = asyncio.run(mcp.list_tools())
+    return {
+        "instructions": mcp.instructions,
+        "tools": [
+            {"name": t.name, "description": t.description, "inputSchema": t.inputSchema} for t in tools
+        ],
+    }
+
+
+def main() -> None:
+    import sys
+
+    if "--dump-tools" in sys.argv:
+        print(json.dumps(dump_tools(), ensure_ascii=False, indent=1))
+        return
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

subtask/skill/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: subtask
+description: Delegate work to background sub-agents through the subtask MCP tools (or the `subtask` CLI). Use when there are 2+ independent pieces to run in parallel, long or noisy work whose details you do not need, or complex code that needs an independent reviewer. Not for small edits.
+---
+
+# subtask: delegate cheaply
+
+Every token you spend on delegation must be cheaper than doing the work
+yourself. Follow these rules.
+
+## Delegate or not
+
+Delegate when one of these is true:
+- 2 or more independent pieces can run at the same time;
+- the work is long or noisy and you only need the outcome (broad search,
+  audit, refactor over many files, test-and-fix loop);
+- complex code needs a reviewer who did not write it (concurrency, saved data
+  or migrations, security, money, logic shared by many callers).
+
+Do NOT delegate when:
+- the change is small (a few lines, one file) or you already know the fix;
+- it needs what is in your context right now (a decision you just made with
+  the user, a half-read stack trace): the brief would be longer than the work;
+- the next step depends on the answer within a minute: just do it;
+- the pieces touch the same lines: run them one after the other yourself.
+
+## The cheap call pattern
+
+1. One call to start everything: `start_many([...])`, or `start(...)` for one job.
+2. One call to collect: `wait(ids)`. It blocks until all jobs end and returns
+   each summary. Do not poll `status()` in a loop.
+3. Only if a summary is not enough: `result(id, full=True)`; for checkable
+   facts (commits, changed files, test exit codes, cost):
+   `result(id, evidence=True)`.
+4. To correct a finished job: `reply(id, "also handle X")`. It keeps the
+   sub-agent's context, so the brief is not sent again.
+
+## Writing the brief
+
+- State the goal, the done condition and how to verify it, in a few lines.
+- Pass paths in `files=[...]`. Never paste file contents: the sub-agent reads them.
+- Set `kind`: `read` (search, summarize: cheapest), `code`, `review`, `hard`.
+- Set `readonly=True` for questions and audits. Use `repo=` for changes: the job
+  gets its own worktree and branch `subtask/<id>`, commits there, never pushes.
+- Give `verify="pytest -q tests/test_x.py"` when there is a check: subtask runs
+  it itself on the commit the worker left, so "tests pass" is a fact, not a claim.
+- `policy`: `worktree` (default, git isolation only, NOT a host sandbox),
+  `sandbox` (engine sandbox), `isolated` (bubblewrap: only the worktree is
+  writable, the home is hidden), `untrusted` (for repositories you do not trust).
+  A job that cannot get the policy is refused, never silently downgraded.
+- Leave `engine="auto"`: it filters engines by policy, install, budget and
+  quota, then ranks them; the start reply says why it picked one.
+
+## While jobs run
+
+- Clients that show MCP progress display a live line during `wait`
+  (`Subtask · 01:16 · 2/3 ended — st-b2 running tests`). You do not need to
+  repeat it.
+- If your client does not show progress, use `wait(ids, timeout=120, since="")`
+  and pass back the returned `cursor=` next time: each reply lists only what
+  changed. Tell the user one short line when something significant changed
+  (a job ended, failed, or is blocked); stay silent otherwise.
+- Cancelling a `wait` does not stop the jobs; `stop(id)` does.
+
+## After the job
+
+- A summary is what the worker reports. Trust a `verified` status or the
+  evidence envelope over a sentence like "all tests pass".
+- Review the branch diff yourself before merging: `git diff <base>..subtask/<id>`.
+- Merge the exact commits you reviewed, then `cleanup(id)`.
+- If something failed, decide: `reply()` once with a precise fix, or take it
+  over. Do not loop.
+
+## Announce every significant step
+
+Before each significant step (new phase, choice of approach, a change with
+risk, a merge or release) call `step(title, path, how, decisions)` and show
+the returned text to the user verbatim. A separate cheap model reads your
+declaration, the repo state and the observed sub-task activity, and keeps
+intention and facts apart. Small edits and reads are not steps.
+
+## Example
+
+```
+start_many([
+  {"task": "Find every caller of parse_date() and list the formats each passes.",
+   "kind": "read", "readonly": true, "cwd": "/src/app"},
+  {"task": "Make tests/test_sync.py pass without changing its assertions.",
+   "kind": "code", "repo": "/src/app", "files": ["src/sync.py", "tests/test_sync.py"],
+   "verify": "pytest -q tests/test_sync.py"}
+])
+wait(["st-1a2b3c", "st-4d5e6f"])
+```
+
+CLI equivalent: `subtask start "..." --kind read --readonly --cwd .`,
+`subtask wait ID ID`, `subtask result ID --evidence`.

subtask/telemetry.py

@@ -0,0 +1,76 @@
+"""Local, versioned, redacted telemetry: one row per finished attempt.
+
+<HOME>/telemetry/YYYY-MM.jsonl. Nothing leaves the machine. Rows older than
+SUBTASK_TELEMETRY_DAYS (default 90) are dropped by `subtask gc`.
+Every number says what it is: exact (observed from the engine or git),
+estimated (e.g. tokens = bytes/4) or missing (None).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+from . import config
+from .redact import redact
+
+VERSION = 1
+RETENTION_DAYS = int(os.environ.get("SUBTASK_TELEMETRY_DAYS", "90"))
+
+
+def _dir() -> Path:
+    return config.HOME / "telemetry"
+
+
+def record(row: dict) -> None:
+    folder = _dir()
+    folder.mkdir(parents=True, exist_ok=True)
+    row = {"v": VERSION, "ts": time.time(), **row}
+    line = redact(json.dumps(row, ensure_ascii=False))
+    with (folder / f"{time.strftime('%Y-%m')}.jsonl").open("a", encoding="utf-8") as fh:
+        fh.write(line + "\n")
+
+
+def rows(months: int = 3) -> list[dict]:
+    folder = _dir()
+    if not folder.is_dir():
+        return []
+    out: list[dict] = []
+    for path in sorted(folder.glob("????-??.jsonl"))[-months:]:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return out
+
+
+def count_call(job_ids: list[str], tool: str) -> None:
+    """One parent round trip touching these jobs (counted by the servers and the CLI)."""
+    for job_id in job_ids:
+        path = config.JOBS / job_id / "calls.jsonl"
+        if path.parent.is_dir():
+            with path.open("a") as fh:
+                fh.write(json.dumps({"ts": time.time(), "tool": tool}) + "\n")
+
+
+def calls(job_id: str) -> list[dict]:
+    path = config.JOBS / job_id / "calls.jsonl"
+    try:
+        return [json.loads(x) for x in path.read_text().splitlines() if x.strip()]
+    except (OSError, json.JSONDecodeError):
+        return []
+
+
+def prune(days: int = RETENTION_DAYS, dry_run: bool = True) -> list[Path]:
+    folder = _dir()
+    if not folder.is_dir():
+        return []
+    cutoff = time.strftime("%Y-%m", time.gmtime(time.time() - days * 86400))
+    old = [p for p in folder.glob("????-??.jsonl") if p.stem < cutoff]
+    if not dry_run:
+        for path in old:
+            path.unlink()
+    return old