taskproof 0.3.0__py3-none-any.whl

taskproof/errors.py

@@ -0,0 +1,55 @@
+"""Exit codes and the error hierarchy.
+
+The exit codes are part of the public contract: callers (agents, scripts, humans)
+must be able to distinguish "the agent failed" from "the agent succeeded but
+verification failed" without parsing stdout.
+
+Keep this table in sync with docs/DESIGN.md.
+"""
+
+EXIT_OK = 0
+EXIT_REGISTRY = 2
+EXIT_USAGE = 64
+EXIT_ADAPTER = 70
+EXIT_VERIFY = 71
+EXIT_CONCURRENCY = 75
+
+
+class TaskproofError(Exception):
+    """Base class. Carries the process exit code this failure maps to."""
+
+    exit_code = 1
+
+    def __init__(self, message, *, hint=None):
+        super().__init__(message)
+        self.hint = hint
+
+
+class UsageError(TaskproofError):
+    """Bad invocation — wrong flags, unreadable input. -> 64"""
+
+    exit_code = EXIT_USAGE
+
+
+class RegistryError(TaskproofError):
+    """Project not found, registry malformed, missing acceptance command. -> 2"""
+
+    exit_code = EXIT_REGISTRY
+
+
+class AdapterError(TaskproofError):
+    """The agent CLI failed to run, or its result could not be parsed. -> 70"""
+
+    exit_code = EXIT_ADAPTER
+
+
+class VerifyError(TaskproofError):
+    """Acceptance command or artifact self-check failed. -> 71"""
+
+    exit_code = EXIT_VERIFY
+
+
+class ConcurrencyError(TaskproofError):
+    """Same-group serialisation or the global cap blocked this dispatch. -> 75"""
+
+    exit_code = EXIT_CONCURRENCY

taskproof/ledger.py

@@ -0,0 +1,185 @@
+"""Append-only audit stream.
+
+WRITE-ONLY WITH RESPECT TO LOGIC. Nothing in this package decides anything by
+reading these files. The database is the query surface; this is the audit trail
+and the "read it once tomorrow morning" surface.
+
+Layout (workspace = ~/.taskproof by default):
+
+    events-2026-10.jsonl        current month
+    events-2026-09.jsonl.gz     rotated + compressed
+
+Rotation is driven by `gc` (see `rotate`), not by a background daemon.
+"""
+
+import gzip
+import json
+import os
+import re
+import shutil
+from typing import Iterator, Optional
+
+from .storage import now_iso
+
+EVENT_PREFIX = "events-"
+
+
+def month_key(iso_ts: Optional[str] = None) -> str:
+    """`2026-10` for the given timestamp (or now)."""
+    ts = iso_ts or now_iso()
+    return ts[:7]
+
+
+def stream_path(audit_dir: str, month: Optional[str] = None) -> str:
+    return os.path.join(audit_dir, f"{EVENT_PREFIX}{month or month_key()}.jsonl")
+
+
+def append(audit_dir: str, event: dict) -> str:
+    """Append one JSON object as a single line. Returns the file written.
+
+    Must be atomic enough that a concurrent reader never sees a partial line:
+    one `write()` of a complete line, opened in append mode.
+    """
+    if audit_dir:
+        ensure_dir(audit_dir)
+    path = stream_path(audit_dir, month_key(event.get("ts")))
+    line = json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n"
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(line)  # one write() of a complete line
+        fh.flush()
+        os.fsync(fh.fileno())
+    return path
+
+
+def rotate(audit_dir: str, *, keep_months: int = 6, compress: bool = True) -> list:
+    """Compress rotated months, prune beyond `keep_months`.
+
+    Returns the list of paths touched, so `gc` can report what it did.
+    NEVER deletes the current month. Never touches a file it did not create.
+
+    A "month we own" is a file whose name matches ``events-<YYYY>-<MM>.jsonl``
+    (optionally ``.gz``). Anything else in the directory — a workspace's other
+    ``*.jsonl``, a stray lock file — is invisible to this function.
+
+    Retention is deliberately coarse: files are per-month, but a month file is
+    pruned once its calendar year is at least ``keep_months`` years behind the
+    current one, so the newest ``keep_months`` years of months are kept.
+    """
+    touched: list = []
+    months = _months_on_disk(audit_dir)
+    if not months:
+        return touched
+    current = month_key()
+    current_year = int(current[:4])
+    for month in sorted(months):
+        if month == current:
+            # The live month is never compressed and never deleted.
+            continue
+        files = months[month]
+        plain = files.get("plain")
+        gz = files.get("gz")
+        if plain is not None and compress:
+            if gz is None:
+                gz = _gzip_copy(plain)
+            os.remove(plain)
+            touched.append(plain)
+            touched.append(gz)
+        if current_year - int(month[:4]) >= keep_months:
+            # Beyond the window: drop whatever representation survives.
+            for stale in (plain, gz):
+                if stale and os.path.exists(stale):
+                    os.remove(stale)
+                    touched.append(stale)
+    return touched
+
+
+def iter_events(audit_dir: str, *, task_id: Optional[str] = None) -> Iterator[dict]:
+    """Read events back, oldest first. Transparently reads `.gz` months.
+
+    This exists for `taskproof log` and for human/audit use. No decision logic
+    may depend on it.
+
+    Only files this module created are read (same pattern as :func:`rotate`).
+    A torn final line — a process killed mid-append — is skipped, and a
+    truncated gzip stream stops that month rather than raising.
+    """
+    months = _months_on_disk(audit_dir)
+    for month in sorted(months):
+        files = months[month]
+        # Prefer the compressed copy: if a crash left both behind, the `.gz` is
+        # the completed rotation and the `.jsonl` is a leftover duplicate.
+        path = files.get("gz") or files.get("plain")
+        if not path:
+            continue
+        for event in _iter_jsonl_tolerant(path):
+            if task_id is not None and event.get("task_id") != task_id:
+                continue
+            yield event
+
+
+_MONTH_PATTERN = re.compile(r"^events-(\d{4})-(\d{2})\.jsonl(\.gz)?$")
+
+
+def _months_on_disk(audit_dir: str) -> dict:
+    """``{month: {"plain": path, "gz": path}}`` for files THIS module owns."""
+    found: dict = {}
+    try:
+        names = os.listdir(audit_dir)
+    except OSError:
+        return found
+    for name in names:
+        m = _MONTH_PATTERN.match(name)
+        if m is None:
+            continue
+        path = os.path.join(audit_dir, name)
+        if not os.path.isfile(path):
+            continue
+        kind = "gz" if name.endswith(".gz") else "plain"
+        found.setdefault(f"{m.group(1)}-{m.group(2)}", {})[kind] = path
+    return found
+
+
+def _gzip_copy(plain_path: str) -> str:
+    """Gzip ``plain_path`` in place to ``<plain_path>.gz``; return the new path."""
+    gz_path = plain_path + ".gz"
+    tmp = gz_path + ".tmp"
+    with open(plain_path, "rb") as src, gzip.open(tmp, "wb") as dst:
+        shutil.copyfileobj(src, dst)
+    os.replace(tmp, gz_path)  # atomic: readers never see a half-written .gz
+    return gz_path
+
+
+def _iter_jsonl_tolerant(path: str) -> Iterator[dict]:
+    """``_read_jsonl`` that also survives a truncated gzip stream."""
+    try:
+        for event in _read_jsonl(path):
+            yield event
+    except (OSError, EOFError):
+        # gzip.BadGzipFile is an OSError; a torn plain line is already skipped
+        # inside `_read_jsonl`. Either way an audit read must not explode.
+        return
+
+
+def _read_jsonl(path: str) -> Iterator[dict]:
+    opener = gzip.open if path.endswith(".gz") else open
+    with opener(path, "rt", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                yield json.loads(line)
+            except json.JSONDecodeError:
+                # A torn line must never break an audit read.
+                continue
+
+
+def ensure_dir(path: str) -> str:
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def copy_for_export(audit_dir: str, dest: str) -> str:
+    """Bundle the audit dir for sharing (used by `board --out` snapshots)."""
+    shutil.make_archive(dest.rstrip("/"), "gztar", audit_dir)
+    return dest + ".tar.gz"

taskproof/models.py

@@ -0,0 +1,155 @@
+"""Plain data carriers.
+
+Deliberately dependency-free dataclasses (no ORM, no pydantic) — the package
+promises standard library only.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+
+# Task lifecycle. Terminal states: DONE, FAILED, BLOCKED, TIMEOUT, CANCELLED.
+STATUS_RUNNING = "running"
+STATUS_VERIFYING = "verifying"
+STATUS_DONE = "done"
+STATUS_FAILED = "failed"
+STATUS_BLOCKED = "blocked"
+STATUS_TIMEOUT = "timeout"
+STATUS_CANCELLED = "cancelled"
+
+TERMINAL_STATUSES = (
+    STATUS_DONE,
+    STATUS_FAILED,
+    STATUS_BLOCKED,
+    STATUS_TIMEOUT,
+    STATUS_CANCELLED,
+)
+
+
+@dataclass
+class Project:
+    """A repository / filter unit: where the work happens and what to call it.
+
+    A project is *not* dispatchable on its own — it is the shared identity and
+    default path that one or more :class:`Taskgroup` lanes hang off. Renaming a
+    project (or adding a lane) never splits its history.
+    """
+
+    id: str
+    path: str
+    aliases: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Taskgroup:
+    """One lane ("道"): the unit a task is dispatched onto.
+
+    It owns the acceptance command, the forbidden-path rules and the structured
+    result contract; ``path`` defaults to the owning project's path but may
+    point anywhere (an independent clone, a subdirectory, ...).
+    """
+
+    id: str
+    project: str
+    path: str
+    aliases: List[str] = field(default_factory=list)
+    verify: Optional[str] = None
+    verify_kind: str = "none"  # check | build | none
+    forbidden_paths: List[str] = field(default_factory=list)
+    auto_registered: bool = False
+    #: Structured-result contract: "default" (package-shipped schema), "none"
+    #: (fall back to free text, never silent), or an absolute path to a custom
+    #: JSON Schema. See `registry.result_schema_path`.
+    result_schema: str = "default"
+    #: Long-lived workspace policy. ``"none"`` (the default) runs in-place;
+    #: ``"worktree"`` asks taskproof to lazily create one persistent git
+    #: worktree for this lane. It is a per-lane opt-in, never a global default.
+    workspace: str = "none"
+    #: Relative paths to symlink from the main checkout into a lane workspace
+    #: (for example ``desktop/node_modules``). Empty means the dispatcher may
+    #: probe for package-manager dependency directories.
+    link: List[str] = field(default_factory=list)
+    #: Concurrency lock name. Empty means this lane's own id; loading fills the
+    #: default in so callers never need to special-case an unset value.
+    group: str = ""
+    #: Per-lane hard timeout in seconds. ``None`` (the default) means "no lane
+    #: budget": the effective timeout then falls through to ``[defaults]
+    #: timeout`` and finally the built-in fallback. A ``--timeout`` on the
+    #: command line overrides it for that one run. See `registry.resolve_timeout`.
+    timeout: Optional[int] = None
+    #: Per-lane no-progress watchdog budget in seconds (card 83). ``0`` — the
+    #: shipped default — disables it; a positive value stops a card whose log
+    #: AND working tree have both been quiet for that long. ``None`` means the
+    #: lane did not name one, so the chain falls through to the built-in default
+    #: (also off). A ``--idle-timeout`` on the command line overrides it for that
+    #: one run. See `registry.resolve_idle_timeout`.
+    idle_timeout: Optional[int] = None
+
+    def __post_init__(self):
+        if not isinstance(self.group, str) or not self.group.strip():
+            self.group = self.id
+
+
+@dataclass
+class Task:
+    """One dispatched unit of work. Mirrors the `tasks` table."""
+
+    id: str
+    project: str
+    group: str
+    brief: str
+    status: str = STATUS_RUNNING
+    adapter: str = "codex"
+    model: Optional[str] = None
+    reasoning: Optional[str] = None
+    attempt: int = 1
+    exit_code: Optional[int] = None
+    pid: Optional[int] = None
+    #: Process-group id that locates the whole adapter tree (`_run_adapter`
+    #: spawns it with ``start_new_session=True``, so this is the adapter's own
+    #: session/group, not the dispatching process' group). `cancel` signals
+    #: exactly this group.
+    pgid: Optional[int] = None
+    workdir: Optional[str] = None
+    result_path: Optional[str] = None
+    verify_cmd: Optional[str] = None
+    verify_exit: Optional[int] = None
+    files_changed: Optional[int] = None
+    created_at: Optional[str] = None
+    started_at: Optional[str] = None
+    finished_at: Optional[str] = None
+
+    def to_row(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Claim:
+    """A held concurrency slot. `scope` is either `group:<name>` or `global`."""
+
+    scope: str
+    task_id: str
+    pid: Optional[int]
+    claimed_at: str
+    expires_at: str
+
+
+@dataclass
+class AdapterResult:
+    """Normalised outcome of one adapter invocation.
+
+    `summary` is the agent's own claim — it is displayed but NEVER treated as
+    proof of success. Only the independently run acceptance command decides.
+    """
+
+    exit_code: int
+    summary: str = ""
+    payload: Optional[Dict[str, Any]] = None
+    files_changed: Optional[int] = None
+    raw_stdout: str = ""
+    raw_stderr: str = ""
+    parse_degraded: bool = False
+    result_path: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0