taskproof 0.3.0__py3-none-any.whl

taskproof/__init__.py

@@ -0,0 +1,23 @@
+"""taskproof — a conveyor belt for AI coding agents.
+
+It does not decide what to do. It guarantees that what was dispatched gets
+independently verified and recorded.
+"""
+
+import sys
+
+# The single source of the version: `pyproject.toml` reads it from here
+# (`[tool.setuptools.dynamic]`), so cutting a release bumps exactly one string.
+__version__ = "0.3.0"
+
+# Fail early and in plain language. Without this, running from a source checkout
+# under an older interpreter surfaces as `ModuleNotFoundError: No module named
+# 'tomllib'` from somewhere deep in the registry loader — which says nothing
+# about the real problem (the interpreter is too old).
+if sys.version_info < (3, 11):
+    raise RuntimeError(
+        "taskproof requires Python 3.11 or newer: the project registry is parsed "
+        f"with the standard library's tomllib. This interpreter is {sys.version.split()[0]}. "
+        "Use a newer Python, or install the packaged version with "
+        "`pipx install taskproof` (which will refuse incompatible interpreters for you)."
+    )

taskproof/__main__.py

@@ -0,0 +1,8 @@
+"""`python -m taskproof` — same entry point as the `taskproof` script."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

taskproof/adapters/__init__.py

@@ -0,0 +1,101 @@
+"""Adapter registry.
+
+`get(name)` resolves a built-in adapter or a `custom:<cmd>` fallback.
+
+The resolution order matters: a registry entry saying `custom:my-agent --flag`
+always wins over any built-in of the same prefix, and an unknown bare name is a
+usage error rather than a silent fallback — silently running the wrong agent is
+exactly the class of failure this project exists to prevent.
+"""
+
+import importlib
+import shutil
+from typing import Dict, List, Type
+
+from ..errors import UsageError
+from .base import Adapter
+from .custom import CustomAdapter
+
+_BUILTINS: Dict[str, str] = {
+    # name -> module attribute path, resolved lazily in get()
+    "codex": "codex",
+    "claude": "claude",
+    "gemini": "gemini",
+    "opencode": "opencode",
+}
+
+#: Every adapter name this build knows about (used by doctor / --help).
+KNOWN = tuple(sorted(_BUILTINS)) + ("custom:<cmd>",)
+
+
+def load_class(module_name: str) -> Type[Adapter]:
+    """Import `taskproof.adapters.<module_name>` and return its Adapter class.
+
+    Kept as a function so `get()` can resolve built-ins lazily: importing a
+    module never executes the CLI it wraps.
+    """
+    try:
+        module = importlib.import_module(f".{module_name}", __package__)
+    except ImportError as exc:
+        raise UsageError(
+            f"adapter module not available: {module_name} ({exc})",
+            hint=f"known adapters: {', '.join(KNOWN)}",
+        )
+    candidates = [
+        obj
+        for obj in vars(module).values()
+        if isinstance(obj, type)
+        and issubclass(obj, Adapter)
+        and obj is not Adapter
+        and obj.__module__ == module.__name__
+    ]
+    if not candidates:
+        raise UsageError(f"adapter module '{module_name}' defines no Adapter subclass")
+    # Deterministic: prefer the conventional `<Name>Adapter` class.
+    candidates.sort(key=lambda cls: (not cls.__name__.endswith("Adapter"), cls.__name__))
+    return candidates[0]
+
+
+def available() -> List[str]:
+    """Names whose CLI is actually present on PATH (does not execute them)."""
+    found: List[str] = []
+    for name, module_name in _BUILTINS.items():
+        try:
+            adapter_cls = load_class(module_name)
+        except UsageError:
+            continue
+        binary = getattr(adapter_cls, "binary", "") or name
+        if shutil.which(binary):
+            found.append(name)
+    return found
+
+
+def get(name, **kwargs) -> Adapter:
+    """Instantiate an adapter by name.
+
+    `name` may be:
+      * a built-in name (`codex`, `claude`, ...)
+      * `custom:<shell command>` — the command is templated, not executed here
+
+    Unknown bare names raise UsageError (exit 64).
+    """
+    if not isinstance(name, str) or not name.strip():
+        raise UsageError("adapter name is required")
+    name = name.strip()
+
+    if name.startswith("custom:"):
+        command = name[len("custom:"):].strip()
+        if not command:
+            raise UsageError(
+                "custom adapter needs a command",
+                hint="usage: custom:<command template with {prompt} / {workdir}>",
+            )
+        return CustomAdapter(command, **kwargs)
+
+    if name in _BUILTINS:
+        return load_class(_BUILTINS[name])(**kwargs)
+
+    raise UsageError(
+        f"unknown adapter: {name}",
+        hint=f"known adapters: {', '.join(KNOWN)}",
+    )

taskproof/adapters/base.py

@@ -0,0 +1,228 @@
+"""Adapter contract.
+
+An adapter is one command template plus one result-parsing convention. It knows
+how to invoke a coding agent CLI and how to salvage a structured outcome from
+its output. It knows nothing about concurrency, verification or storage.
+
+The contract exists because agent CLIs lie, crash, and wrap their output in
+markdown. Documented incidents that shaped it:
+
+  * result JSON wrapped in a ```json fence -> structured parse failed and the
+    whole run looked like it had done nothing
+  * "I verified this in the browser, screenshot attached" with zero browser
+    activity in the event stream -> hence: the adapter's summary is reported,
+    never trusted
+  * an out-of-scope HTTP login attempt -> hence: `forbidden_paths` are checked
+    after the run, and adapters are invoked in the narrowest sandbox they offer
+"""
+
+import json
+import re
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+from ..models import AdapterResult
+
+
+class ResultParseError(Exception):
+    """The adapter ran but its result could not be understood."""
+
+
+class Adapter(ABC):
+    """Base class for agent CLI adapters."""
+
+    #: Name used in the registry and on the command line.
+    name: str = ""
+
+    #: Executable looked up on PATH by `adapters.available()` / `preflight()`.
+    binary: str = ""
+
+    #: True when the CLI can be constrained to a machine-readable result.
+    supports_schema = False
+
+    #: True when the CLI offers a sandbox / approval mode worth using.
+    supports_sandbox = False
+
+    def __init__(self, *, model: Optional[str] = None, reasoning: Optional[str] = None,
+                 timeout: int = 1800, env: Optional[Dict[str, str]] = None):
+        self.model = model
+        self.reasoning = reasoning
+        self.timeout = timeout
+        self.env = env or {}
+
+    # -- required ---------------------------------------------------------
+
+    @abstractmethod
+    def build_command(self, *, brief: str, workdir: str,
+                      schema_path: Optional[str] = None,
+                      read_only: bool = False) -> list:
+        """Return argv for one invocation.
+
+        Must not include a shell: pass a list, never `shell=True`.
+        """
+
+    @abstractmethod
+    def parse_result(self, *, exit_code: int, stdout: str, stderr: str,
+                     result_path: Optional[str]) -> AdapterResult:
+        """Normalise the CLI's outcome.
+
+        Implementations MUST tolerate:
+          * a markdown code fence around the JSON payload
+          * a missing or empty result file
+          * trailing noise on stdout after the payload
+
+        Degrading to a summary parsed from stdout is allowed and must set
+        `parse_degraded=True`. Raising ResultParseError is allowed, and must be
+        surfaced as an adapter failure (exit 70) — never silently treated as
+        success.
+        """
+
+    # -- optional ---------------------------------------------------------
+
+    def preflight(self) -> Optional[str]:
+        """Return a human-readable problem if this CLI is unusable, else None.
+
+        Used by `taskproof doctor`. Must not execute the agent.
+        """
+        return None
+
+    #: Extra context appended to the brief, per CLI.
+    prompt_preamble: str = ""
+
+    def full_prompt(self, brief: str) -> str:
+        return f"{self.prompt_preamble}{brief}" if self.prompt_preamble else brief
+
+    def degraded_result(self, *, exit_code: int, stdout: str, stderr: str,
+                        result_path: Optional[str]) -> AdapterResult:
+        """Stdout-only fallback shared by adapters without structured output.
+
+        Salvages a JSON object from stdout when possible, otherwise keeps the
+        tail of the text as the summary. ALWAYS sets `parse_degraded=True`
+        because nothing here is schema-constrained. Raises `ResultParseError`
+        when there is nothing at all to salvage (the caller must treat that as
+        an adapter failure, exit 70 — never a silent success).
+        """
+        if not stdout or not stdout.strip():
+            raise ResultParseError(
+                f"{self.name}: produced no output to parse"
+            )
+        try:
+            decoded = extract_json(stdout)
+        except ResultParseError:
+            decoded = None
+        payload = decoded if isinstance(decoded, dict) else None
+        return AdapterResult(
+            exit_code=exit_code,
+            summary=_summarize(decoded, stdout),
+            payload=payload,
+            raw_stdout=stdout,
+            raw_stderr=stderr,
+            parse_degraded=True,
+            result_path=result_path,
+        )
+
+
+# ---------------------------------------------------------------------------
+# JSON recovery
+# ---------------------------------------------------------------------------
+
+_FENCE_RE = re.compile(r"```[ \t]*([A-Za-z0-9_+-]*)[ \t]*\r?\n?(.*?)```", re.DOTALL)
+
+
+def extract_json(text: str) -> Any:
+    """Best-effort JSON recovery used by adapters.
+
+    Order of attempts:
+      1. the whole string parses
+      2. a fenced block (```json ... ``` or ``` ... ```) parses
+      3. the first balanced `{...}` object parses
+
+    Returns the decoded object, or raises ResultParseError.
+    """
+    if text is None:
+        raise ResultParseError("no result to parse")
+    stripped = text.strip()
+    if not stripped:
+        raise ResultParseError("empty result")
+
+    # 1. the whole string is JSON
+    try:
+        return json.loads(stripped)
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    # 2. a fenced block
+    for match in _FENCE_RE.finditer(stripped):
+        block = match.group(2).strip()
+        if not block:
+            continue
+        try:
+            return json.loads(block)
+        except (json.JSONDecodeError, ValueError):
+            pass
+        balanced = _first_balanced_object(block)
+        if balanced is not _MISS:
+            return balanced
+
+    # 3. the first balanced {...} object anywhere in the string
+    balanced = _first_balanced_object(stripped)
+    if balanced is not _MISS:
+        return balanced
+
+    raise ResultParseError("could not extract JSON from result")
+
+
+class _Missing:
+    """Sentinel so `None` / `0` / `False` are still valid decoded values."""
+
+
+_MISS = _Missing()
+
+
+def _first_balanced_object(text: str):
+    """Decode the first brace-balanced `{...}` object, or return `_MISS`.
+
+    String literals and escapes are respected so a `}` inside a JSON string
+    does not close the object early.
+    """
+    start = text.find("{")
+    while start != -1:
+        depth = 0
+        in_string = False
+        escaped = False
+        for index in range(start, len(text)):
+            char = text[index]
+            if in_string:
+                if escaped:
+                    escaped = False
+                elif char == "\\":
+                    escaped = True
+                elif char == '"':
+                    in_string = False
+            else:
+                if char == '"':
+                    in_string = True
+                elif char == "{":
+                    depth += 1
+                elif char == "}":
+                    depth -= 1
+                    if depth == 0:
+                        candidate = text[start:index + 1]
+                        try:
+                            return json.loads(candidate)
+                        except (json.JSONDecodeError, ValueError):
+                            break  # start over from the next '{'
+        start = text.find("{", start + 1)
+    return _MISS
+
+
+def _summarize(payload: Any, text: str, tail: int = 40) -> str:
+    """Human-readable one-liner: prefer a summary field, else tail the text."""
+    if isinstance(payload, dict):
+        for key in ("summary", "message", "result", "text"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        return json.dumps(payload, ensure_ascii=False)
+    lines: List[str] = [line for line in text.splitlines() if line.strip()]
+    return "\n".join(lines[-tail:])

taskproof/adapters/claude.py

@@ -0,0 +1,46 @@
+"""Claude Code CLI adapter — NOT tested on this machine (claude not installed).
+
+Command shape (print mode, JSON output):
+
+    claude -p "<prompt>" [--model <m>] [--permission-mode plan|acceptEdits]
+
+`read_only=True` maps to `--permission-mode plan`, the non-mutating mode.
+Result parsing degrades to stdout: `parse_degraded=True` always. The Claude
+`--output-format json` envelope is not a JSON Schema, so `supports_schema`
+stays False.
+"""
+
+import shutil
+from typing import Optional
+
+from ..models import AdapterResult
+from .base import Adapter
+
+
+class ClaudeAdapter(Adapter):
+    name = "claude"
+    binary = "claude"
+    supports_schema = False
+    supports_sandbox = True
+
+    def build_command(self, *, brief: str, workdir: str,
+                      schema_path: Optional[str] = None,
+                      read_only: bool = False) -> list:
+        argv = ["claude", "-p", self.full_prompt(brief)]
+        if self.model:
+            argv += ["--model", self.model]
+        # read-only is the "plan" permission mode (no edits).
+        argv += ["--permission-mode", "plan" if read_only else "acceptEdits"]
+        return argv
+
+    def parse_result(self, *, exit_code: int, stdout: str, stderr: str,
+                     result_path: Optional[str]) -> AdapterResult:
+        return self.degraded_result(
+            exit_code=exit_code, stdout=stdout, stderr=stderr,
+            result_path=result_path,
+        )
+
+    def preflight(self) -> Optional[str]:
+        if shutil.which(self.binary) is None:
+            return "claude CLI not found on PATH (adapter not tested on this machine)"
+        return None

taskproof/adapters/codex.py

@@ -0,0 +1,140 @@
+"""Codex CLI adapter — the one built-in tested on this machine.
+
+Verified against `codex-cli 0.160.0`. The relevant lines from `codex exec
+--help` are:
+
+    Usage: codex exec [OPTIONS] [PROMPT]
+    -m, --model <MODEL>
+    -c, --config <key=value>
+    -s, --sandbox <SANDBOX_MODE>
+        [possible values: read-only, workspace-write, danger-full-access]
+    -C, --cd <DIR>
+    --output-schema <FILE>   Path to a JSON Schema file describing the model's
+                             final response shape
+    -o, --output-last-message <FILE>
+                             Specifies file where the last message from the
+                             agent should be written
+
+Command shape (from the real dispatch scripts):
+
+    codex exec -C <workdir> --sandbox read-only|workspace-write \\
+        --output-schema <schema.json> -o <result.json> \\
+        [--model <m>] [-c model_reasoning_effort=<r>] "<prompt>"
+
+The result file named by `-o` is read first; if it is missing (or holds no
+JSON) the adapter degrades to scraping stdout and sets `parse_degraded=True`.
+"""
+
+import os
+import shutil
+import tempfile
+from typing import List, Optional
+
+from ..models import AdapterResult
+from .base import Adapter, ResultParseError, _summarize, extract_json
+
+
+class CodexAdapter(Adapter):
+    name = "codex"
+    binary = "codex"
+    supports_schema = True
+    supports_sandbox = True
+
+    def __init__(self, *, model: Optional[str] = None, reasoning: Optional[str] = None,
+                 timeout: int = 1800, env: Optional[dict] = None,
+                 result_path: Optional[str] = None):
+        super().__init__(model=model, reasoning=reasoning, timeout=timeout, env=env)
+        #: Where `codex -o` writes the last message. Callers may set it; when
+        #: left None `build_command` allocates a per-run temp file.
+        self.result_path = result_path
+        self._seq = 0
+
+    def _allocate_result_path(self) -> str:
+        self._seq += 1
+        return os.path.join(
+            tempfile.gettempdir(),
+            f"taskproof-codex-{os.getpid()}-{self._seq}.json",
+        )
+
+    def build_command(self, *, brief: str, workdir: str,
+                      schema_path: Optional[str] = None,
+                      read_only: bool = False) -> list:
+        if self.result_path is None:
+            self.result_path = self._allocate_result_path()
+
+        # argv list, never a shell string: the prompt is passed as one element
+        # and can never inject a `;`/`&&`/backtick into a shell.
+        argv: List[str] = ["codex", "exec"]
+        argv += ["-C", workdir]
+        # read-only vs workspace-write is the whole point of the sandbox flag.
+        argv += ["--sandbox", "read-only" if read_only else "workspace-write"]
+        if schema_path:
+            argv += ["--output-schema", schema_path]
+        argv += ["-o", self.result_path]
+        if self.model:
+            argv += ["--model", self.model]
+        if self.reasoning:
+            argv += ["-c", f"model_reasoning_effort={self.reasoning}"]
+        argv += [self.full_prompt(brief)]
+        return argv
+
+    def parse_result(self, *, exit_code: int, stdout: str, stderr: str,
+                     result_path: Optional[str]) -> AdapterResult:
+        path = result_path or self.result_path
+
+        payload = None
+        raw = ""
+        if path and os.path.isfile(path):
+            try:
+                with open(path, "r", encoding="utf-8", errors="replace") as handle:
+                    raw = handle.read()
+            except OSError:
+                raw = ""
+        if raw.strip():
+            try:
+                payload = extract_json(raw)
+            except ResultParseError:
+                payload = None
+
+        if payload is not None:
+            # A structured result came back from the `-o` file. A fenced file is
+            # still the structured result (extract_json unwraps it), so this is
+            # NOT flagged as degraded.
+            return AdapterResult(
+                exit_code=exit_code,
+                summary=_summarize(payload, raw),
+                payload=payload if isinstance(payload, dict) else None,
+                raw_stdout=stdout,
+                raw_stderr=stderr,
+                parse_degraded=False,
+                result_path=path,
+            )
+
+        # Result file missing/empty/unparseable -> salvage stdout if we can.
+        if stdout and stdout.strip():
+            decoded = None
+            try:
+                decoded = extract_json(stdout)
+            except ResultParseError:
+                decoded = None
+            return AdapterResult(
+                exit_code=exit_code,
+                summary=_summarize(decoded, stdout),
+                payload=decoded if isinstance(decoded, dict) else None,
+                raw_stdout=stdout,
+                raw_stderr=stderr,
+                parse_degraded=True,
+                result_path=path,
+            )
+
+        raise ResultParseError(
+            f"codex: no parseable result (result_path={path!r}, empty stdout)"
+        )
+
+    def preflight(self) -> Optional[str]:
+        if shutil.which(self.binary) is None:
+            return (
+                "codex CLI not found on PATH — install codex-cli, or use "
+                "custom:<cmd> pointing at your agent"
+            )
+        return None

taskproof/adapters/custom.py

@@ -0,0 +1,61 @@
+"""Custom command adapter — `custom:<command template>`.
+
+The template is tokenised with `shlex.split` (shell-style quoting, but no
+shell is ever spawned). Two placeholders are substituted, per token, AFTER
+tokenisation so a prompt containing spaces/quotes stays a single argv element
+and cannot be re-interpreted as shell syntax:
+
+    {prompt}    the full brief (adapter `prompt_preamble` included)
+    {workdir}   the directory the task runs in
+
+Example registry value:
+
+    custom:my-agent --cwd {workdir} --task {prompt}
+
+There is no structured-output convention for an arbitrary command, so
+`supports_schema = False` and `parse_result` always degrades: it salvages a
+JSON object from stdout when present, otherwise keeps the tail of the text,
+and sets `parse_degraded=True`.
+"""
+
+import shlex
+from typing import Optional
+
+from ..models import AdapterResult
+from .base import Adapter
+
+
+class CustomAdapter(Adapter):
+    name = "custom"
+    supports_schema = False
+    supports_sandbox = False
+
+    def __init__(self, command: str = "", *, model: Optional[str] = None,
+                 reasoning: Optional[str] = None, timeout: int = 1800,
+                 env: Optional[dict] = None):
+        super().__init__(model=model, reasoning=reasoning, timeout=timeout, env=env)
+        #: The raw template (everything after the `custom:` prefix).
+        self.command = command
+
+    def build_command(self, *, brief: str, workdir: str,
+                      schema_path: Optional[str] = None,
+                      read_only: bool = False) -> list:
+        # `schema_path` / `read_only` are not expressible for an arbitrary
+        # command; they are accepted for interface compatibility and ignored.
+        prompt = self.full_prompt(brief)
+        argv = []
+        for token in shlex.split(self.command):
+            argv.append(token.replace("{workdir}", workdir).replace("{prompt}", prompt))
+        return argv
+
+    def parse_result(self, *, exit_code: int, stdout: str, stderr: str,
+                     result_path: Optional[str]) -> AdapterResult:
+        return self.degraded_result(
+            exit_code=exit_code, stdout=stdout, stderr=stderr,
+            result_path=result_path,
+        )
+
+    def preflight(self) -> Optional[str]:
+        # An arbitrary command cannot be validated without running it (which
+        # we never do here). Report nothing; `doctor` shows the template.
+        return None

taskproof/adapters/gemini.py

@@ -0,0 +1,45 @@
+"""Gemini CLI adapter — NOT tested on this machine (gemini not installed).
+
+Command shape (non-interactive prompt):
+
+    gemini -p "<prompt>" [-m <model>] [--approval-mode plan|auto_edit]
+
+`read_only=True` maps to `--approval-mode plan`. No structured schema output
+is assumed, so `supports_schema = False`; parsing degrades to stdout and sets
+`parse_degraded=True` always.
+"""
+
+import shutil
+from typing import Optional
+
+from ..models import AdapterResult
+from .base import Adapter
+
+
+class GeminiAdapter(Adapter):
+    name = "gemini"
+    binary = "gemini"
+    supports_schema = False
+    supports_sandbox = True
+
+    def build_command(self, *, brief: str, workdir: str,
+                      schema_path: Optional[str] = None,
+                      read_only: bool = False) -> list:
+        argv = ["gemini", "-p", self.full_prompt(brief)]
+        if self.model:
+            argv += ["-m", self.model]
+        # `plan` approval mode refuses side effects (read-only).
+        argv += ["--approval-mode", "plan" if read_only else "auto_edit"]
+        return argv
+
+    def parse_result(self, *, exit_code: int, stdout: str, stderr: str,
+                     result_path: Optional[str]) -> AdapterResult:
+        return self.degraded_result(
+            exit_code=exit_code, stdout=stdout, stderr=stderr,
+            result_path=result_path,
+        )
+
+    def preflight(self) -> Optional[str]:
+        if shutil.which(self.binary) is None:
+            return "gemini CLI not found on PATH (adapter not tested on this machine)"
+        return None