taskops-cli 0.2.0__py3-none-any.whl

taskops/__init__.py

@@ -0,0 +1,39 @@
+"""taskops — the coordination substrate Claude Code does not have.
+
+Persistent tasks with a dependency DAG, atomic claims that survive a crashed
+agent, every commit bound to the task that motivated it, and a live board a
+human can watch while a hundred agents work.
+
+The error types are exported eagerly because a caller has to be able to write
+`except taskops.LeaseHeld` before it has opened anything. Everything else stays
+behind its own module so that importing this package costs a dict lookup — the
+MCP host imports it to list tools long before it asks for any work.
+"""
+
+from __future__ import annotations
+
+from ._errors import (
+    AlreadyWritten,
+    BadRequest,
+    GuardFailed,
+    IllegalTransition,
+    LeaseHeld,
+    NoLease,
+    NoSuchTask,
+    NotInitialized,
+    TaskopsError,
+)
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "TaskopsError",
+    "NotInitialized",
+    "NoSuchTask",
+    "IllegalTransition",
+    "LeaseHeld",
+    "NoLease",
+    "GuardFailed",
+    "BadRequest",
+    "AlreadyWritten",
+]

taskops/_clock.py

@@ -0,0 +1,32 @@
+"""Layer 0 — the one place that asks what time it is.
+
+Leases expire, heartbeats renew and events are ordered, so "now" is load-bearing
+here rather than incidental. Routing it through one function is what lets a test
+of "the agent died and its lease lapsed" run in microseconds instead of waiting
+fifteen real minutes for the TTL.
+
+`time.time()` and not `monotonic()`: these timestamps are compared ACROSS
+machines and survive a restart, which a monotonic clock cannot do. The cost is
+that a badly skewed clock skews a TTL — bounded, and visible in the studio,
+where a lease from the future is obvious.
+"""
+
+from __future__ import annotations
+
+import time
+
+__all__ = ["now", "LEASE_TTL", "HEARTBEAT_GRACE"]
+
+LEASE_TTL = 900.0
+"""Seconds a claim survives without a heartbeat. Every taskops call an agent
+makes renews it, so this bounds how long a task stays stuck after a CRASH —
+not how long a legitimately slow task may run."""
+
+HEARTBEAT_GRACE = 60.0
+"""Extra seconds the studio waits before calling a session dead. A lease renews
+on tool calls, and an agent that spends two minutes thinking has not gone away."""
+
+
+def now() -> float:
+    """Wall-clock seconds since the epoch."""
+    return time.time()

taskops/_errors.py

@@ -0,0 +1,160 @@
+"""Structured errors: a small taxonomy every boundary maps ONCE.
+
+Errors are data, not strings — a stable machine `code` plus an `http_status` — so
+each transport translates the TYPE at one catch site instead of matching message
+text. Each subclass also inherits the builtin a caller would plausibly already be
+catching (the `json.JSONDecodeError(ValueError)` trick). Every message names what
+to DO: the reader is an agent mid-turn, and this is all it gets to act on.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = [
+    "TaskopsError", "NotInitialized", "NoSuchTask", "IllegalTransition", "LeaseHeld", "NoLease",
+    "GuardFailed", "BadRequest", "AlreadyWritten", "AlreadyNarrating", "NarrationFailed",
+    "ReportConflict", "Unreachable",
+]
+
+
+class TaskopsError(Exception):
+    """Root. `except TaskopsError` catches everything the engine raises."""
+
+    code = "error"
+    http_status = 500
+
+
+class NotInitialized(TaskopsError, FileNotFoundError):
+    """No `.taskops/` at or above the given path."""
+
+    code = "not_initialized"
+    http_status = 404
+
+    @classmethod
+    def at(cls, path: str | Path) -> "NotInitialized":
+        return cls(f"no taskops project at or above {path} — run `taskops init` in the "
+                   f"repository root")
+
+
+class NoSuchTask(TaskopsError, KeyError):
+    """A task id nobody created — usually a hallucinated or a stale one."""
+
+    code = "no_such_task"
+    http_status = 404
+
+    @classmethod
+    def named(cls, task: str) -> "NoSuchTask":
+        return cls(f"no task {task} — list what exists with `taskops report board`")
+
+
+class IllegalTransition(TaskopsError, ValueError):
+    """A status move the machine does not allow."""
+
+    code = "illegal_transition"
+    http_status = 409
+
+    @classmethod
+    def between(
+        cls, *, task: str, old: str, new: str, allowed: tuple[str, ...]
+    ) -> "IllegalTransition":
+        legal = ", ".join(allowed) if allowed else "nothing — it is terminal"
+        return cls(f"{task} is {old} and cannot go to {new}; from {old} it can go to {legal}")
+
+
+class LeaseHeld(TaskopsError, RuntimeError):
+    """Somebody else is on it and their lease has not expired."""
+
+    code = "lease_held"
+    http_status = 409
+
+    @classmethod
+    def by(cls, *, task: str, actor: str, seconds: int) -> "LeaseHeld":
+        return cls(f"{task} is claimed by {actor} for another {seconds}s — "
+                   f"pick another task, or message them on it")
+
+
+class NoLease(TaskopsError, RuntimeError):
+    """Working on a task nobody claimed. Its own type, not a GuardFailed,
+    because it has ONE fix the agent can apply unaided — which the message is."""
+
+    code = "no_lease"
+    http_status = 409
+
+    @classmethod
+    def on(cls, *, task: str, actor: str) -> "NoLease":
+        return cls(f"{actor} holds no live lease on {task} — claim it with "
+                   f"taskops_next, or `taskops claim {task}`")
+
+
+class GuardFailed(TaskopsError, ValueError):
+    """A transition the machine allows but the project's rules refuse. Separate
+    from IllegalTransition: that one is "the arrow does not exist", this one is
+    "you have not earned it yet" — and only this one is fixable by doing work."""
+
+    code = "guard_failed"
+    http_status = 400
+
+
+class BadRequest(TaskopsError, ValueError):
+    """An argument that cannot mean anything. Raised at the edges, not inside."""
+
+    code = "bad_request"
+    http_status = 400
+
+
+class AlreadyWritten(TaskopsError, FileExistsError):
+    """A generated file that exists and would be OVERWRITTEN. 409, never 500.
+
+    A written report is something somebody may have already read, cited, or narrated by
+    hand; silently regenerating it would rewrite history under them. Refusing and naming
+    `--force` leaves the choice with the person who knows whether the old one mattered.
+    """
+
+    code = "already_written"
+    http_status = 409
+
+
+class AlreadyNarrating(TaskopsError, RuntimeError):
+    """A narration of that report is already running IN THIS PROCESS. 409.
+
+    Two models writing the same file is not a slow path, it is corruption: both hold the
+    dossier they read at the start and each rewrites the whole file when it flushes, so
+    whichever finishes last silently erases the other. Refusing the second is the only
+    outcome that leaves a readable report — and the first one is still streaming, so the
+    person who clicked twice is already looking at what they asked for.
+    """
+
+    code = "already_narrating"
+    http_status = 409
+
+
+class NarrationFailed(TaskopsError, RuntimeError):
+    """The `claude` CLI could not write the narration. 502: an upstream did not answer.
+
+    Its own type because the fix is never in taskops — the binary is missing, the session is
+    not logged in, or the model refused — and the message has to say which. Everything else
+    about the report still worked: the dossier is on disk either way, so this never costs the
+    facts, only the prose.
+    """
+
+    code = "narration_failed"
+    http_status = 502
+
+
+class ReportConflict(TaskopsError, FileExistsError):
+    """A DIFFERENT narration of one report, not a newer one — `ours`/`theirs` are the stamps."""
+
+    code = "report_conflict"
+    http_status = 409
+    ours = -1
+    theirs = -1
+
+
+class Unreachable(TaskopsError, ConnectionError):
+    """The server did not answer at all — no status, no body. 502, and never a reason to
+    write locally instead: that is how two machines end up holding one card. Its own type
+    so `usecases._routing` can catch exactly it and say which URL went quiet."""
+
+    code = "unreachable"
+    http_status = 502

taskops/_ids.py

@@ -0,0 +1,63 @@
+"""Layer 0 — how a task and an event get their names.
+
+Two different jobs, and the difference is the whole design:
+
+**Task ids are RANDOM** (`tk-4f2a9c`). Many machines create tasks without
+talking to each other, so an id must be collision-free without coordination —
+which rules out a counter. Random also means unguessable, so a task id in a
+branch name leaks no ordering information about the project.
+
+**Event ids are the CONTENT, hashed.** The event log is replicated by `git pull`
+and by the relay, and the same event can arrive by both paths: with a content
+hash, importing it twice is a primary-key no-op instead of a duplicate comment
+in somebody's inbox. It also makes the log verifiable — an event whose id does
+not match its content was edited after the fact.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import secrets
+from typing import Any
+
+__all__ = ["new_task_id", "event_id", "slugify", "TASK_PREFIX"]
+
+TASK_PREFIX = "tk-"
+_TASK_BYTES = 3  # 6 hex chars: 16.7M ids, and the whole id fits a branch name
+_EVENT_CHARS = 16
+
+
+def new_task_id() -> str:
+    """A fresh task id. Uniqueness is checked at INSERT, not assumed here."""
+    return TASK_PREFIX + secrets.token_hex(_TASK_BYTES)
+
+
+def event_id(*, task: str, actor: str, kind: str, body: dict[str, Any], ts: float) -> str:
+    """The id of an event, derived from everything the event says.
+
+    `sort_keys` and a fixed float format matter more than they look: two
+    machines must hash the same event to the same id, and Python's dict order
+    and `repr(float)` are not a contract across versions.
+    """
+    payload = json.dumps(
+        {"task": task, "actor": actor, "kind": kind, "body": body, "ts": f"{ts:.6f}"},
+        sort_keys=True,
+        separators=(",", ":"),
+        default=str,
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:_EVENT_CHARS]
+
+
+def slugify(text: str, *, limit: int = 32) -> str:
+    """A title -> the branch-safe half of `tk/<id>/<slug>`.
+
+    Deliberately lossy and never parsed back: the id is what identifies the
+    task, so this only has to be readable in a `git branch` listing. Everything
+    git or a shell would treat as special becomes a dash.
+    """
+    kept = [c.lower() if c.isalnum() else "-" for c in text.strip()]
+    slug = "".join(kept).strip("-")
+    while "--" in slug:
+        slug = slug.replace("--", "-")
+    return slug[:limit].strip("-") or "task"

taskops/_types.py

@@ -0,0 +1,106 @@
+"""Layer 0 — the vocabulary. Every state and every event kind, named once.
+
+These are `Literal`s rather than enums on purpose: the values cross a JSON
+boundary in both directions (the MCP wire, the event log in git, the studio's
+fetch), and a Literal IS the wire value, so there is no encode/decode step where
+a rename can half-land. The MCP `inputSchema` generator turns them into an
+`enum`, which is how an agent learns the allowed values before it guesses one.
+
+Imports nothing from the package, so any layer may import it without thinking
+about cycles. `tests/architecture` enforces that.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, get_args
+
+__all__ = [
+    "Status",
+    "ActorKind",
+    "EventKind",
+    "OPEN_STATUSES",
+    "CLOSED_STATUSES",
+    "WORKING_STATUSES",
+    "STATUSES",
+    "EVENT_KINDS",
+    "LOCAL_ONLY_KINDS",
+    "EDITABLE_FIELDS",
+]
+
+Status = Literal[
+    "backlog", "ready", "claimed", "in_progress", "blocked", "review", "done", "cancelled"
+]
+"""Where a task is. See `engine.machine` for which moves between these are legal.
+
+`ready` is a stored status and not a derived view, so that "what can I pick up"
+is one indexed read rather than a graph walk per caller. `engine.machine.unblock`
+is the ONE writer that moves a task between `backlog` and `ready`, which is what
+keeps the stored value from drifting from the dependency graph.
+"""
+
+ActorKind = Literal["dev", "agent"]
+"""A human or one of their agents. The distinction is not cosmetic: guards that
+demand a justification accept one from a dev and reject it from an agent."""
+
+EventKind = Literal[
+    "created",
+    "claimed",
+    "released",
+    "status",
+    "comment",
+    "commit",
+    "branch",
+    "blocked",
+    "unblocked",
+    "handoff",
+    "review",
+    "eval",
+    "done",
+    "message",  # directed chat: agent↔agent, dev↔agent
+    "activity",  # a session's heartbeat: a tool ran, a file was touched
+    "edited",  # a field of the card itself changed: title, spec or priority
+]
+"""What happened. The event log is append-only and every projection — the board,
+a standup, an inbox — is derived from it, so a new fact about a task is a new
+kind here rather than a column somewhere."""
+
+STATUSES: tuple[Status, ...] = (
+    "backlog",
+    "ready",
+    "claimed",
+    "in_progress",
+    "blocked",
+    "review",
+    "done",
+    "cancelled",
+)
+
+EVENT_KINDS: tuple[EventKind, ...] = get_args(EventKind)
+"""The same values as the `Literal`, DERIVED rather than retyped.
+
+Two hand-written lists is how a kind ends up legal at the type level and unknown to the
+MCP schema that iterates the tuple — a mismatch nothing catches, because the type check
+passes and the runtime list is merely short. `STATUSES` keeps its literal spelling: it is
+also the display order, which is a separate decision that happens to agree today."""
+
+EDITABLE_FIELDS: tuple[str, ...] = ("title", "spec", "priority")
+"""The columns a person may rewrite after a card exists. Named here rather than in
+`storage` because three layers ask the same question — the CLI validates a flag, the
+use case records one event per field, and replay refuses a body naming anything else."""
+
+OPEN_STATUSES: frozenset[str] = frozenset(
+    {"backlog", "ready", "claimed", "in_progress", "blocked", "review"}
+)
+"""A dependency in one of these still blocks whatever waits on it."""
+
+CLOSED_STATUSES: frozenset[str] = frozenset({"done", "cancelled"})
+"""`cancelled` closes a dependency as surely as `done` does: a task nobody will
+ever do must not hold its dependents hostage forever."""
+
+WORKING_STATUSES: frozenset[str] = frozenset({"claimed", "in_progress", "review"})
+"""Statuses that require a live lease. Losing the lease drops the task out."""
+
+LOCAL_ONLY_KINDS: frozenset[str] = frozenset({"activity"})
+"""Kinds that never reach the git-committed log. `activity` is a per-keystroke
+heartbeat: replicating it through git would add thousands of lines a day to a
+file whose whole value is that a human can read its diff."""

taskops/_version.py

@@ -0,0 +1,7 @@
+"""The single source of the version. `pyproject.toml` reads this attribute."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

taskops/assets/GUIDE.md

@@ -0,0 +1,220 @@
+# taskops — how work happens in this repository
+
+You are reading the shared task list's manual. One document for agents and humans, on
+purpose: two documents drift, and then the two audiences are told different things.
+
+`taskops init` copies this to `.taskops/GUIDE.md`. If anything here contradicts what the
+tools actually do, the tools are right and this file is a bug.
+
+---
+
+## The one-paragraph version
+
+Tasks live in this repository, not in anybody's session. You **claim** one before you code,
+and the claim is a lease nobody else can take. Your commits are bound to the task that
+motivated them — enforced, not suggested. When you finish, whatever was waiting on your task
+becomes available to everyone else automatically. Every developer's agents share the same
+list, and it travels by `git push` and `git pull` with no server involved.
+
+## The loop
+
+```
+  taskops_next ──▶  work  ──▶  git commit  ──▶  taskops_update status=done
+       │                            │                     │
+   a lease, the spec,          the guard adds        whatever was waiting
+   and a collision             `Task: tk-…`         on you becomes ready
+   warning                     for you              for everyone
+```
+
+**Start every session by finding out where you stand.** If you do not already hold a task,
+call `taskops_next`. It returns the spec, the exact branch to create, the conversation so
+far, and a warning listing any other agent editing the same files. If nothing is available
+it tells you *why*, which is usually something you can act on.
+
+**Work on the branch it names** — `tk/<task-id>/<slug>`. Not a branch of your own choosing:
+the commit guard matches this exact shape, and an invented name gets your own commits denied.
+
+**Commit normally.** The guard adds the `Task:` trailer. You do not write it.
+
+**Close with `taskops_update status=done`.** It will be refused if no commit is bound to the
+task. That refusal is the feature — see below.
+
+## The two rules the server enforces
+
+These are not conventions. The server rejects the call.
+
+**1. A commit belongs to a claimed task.** You must be on the task's branch and hold its
+lease. Why: a commit nobody can attribute is a commit nobody can review against the work it
+was supposed to do, and the moment one is allowed the board stops being a complete picture of
+what changed.
+
+**2. `done` requires a commit bound to the task.** Otherwise "done" means only that an agent
+said so — which is exactly what a human reading a board instead of the diff is trying to
+avoid. If a task legitimately produced no code (research, a decision, docs elsewhere), pass
+`no_code: true` **with a comment saying what it produced instead**. That is recorded, so a
+review can see which closures had no code and why.
+
+## Your claim is a lease, not an assignment
+
+It expires. Every taskops call you make renews it, so a task that takes an hour is fine — you
+do not have to do anything special. What the deadline actually bounds is a **crash**: if your
+process dies, the lease lapses within fifteen minutes and the task returns to the queue
+instead of sitting there looking claimed forever.
+
+Two consequences worth knowing:
+
+- If a write is refused for a missing lease, **claim again**. Do not work around it. Another
+  agent may genuinely have taken the task while you were gone.
+- If you are out of context or out of depth, use `status: released` **with a comment** saying
+  where you got to. That is the honest move and it is always allowed. Abandoning the task
+  silently also works, eventually — but it throws away everything you learned.
+
+## Talking to other agents
+
+`taskops_update` with `mentions` puts a message in another actor's inbox:
+
+```
+taskops_update task=tk-4f2a9c
+  comment="I'm rewriting the tokenizer in parser.py — hold off until I land this."
+  mentions="agent:ana/api-1,dev:ana"
+```
+
+They see it within one tool call of their own, and it appears live on the board. The message
+lives in the task's thread, so it is still findable in three weeks — which is why there is no
+separate chat tool.
+
+**When to use it:** the collision warning in `taskops_next` and `taskops_ask` lists other
+tasks touching your files. That list is the one thing that prevents a merge conflict rather
+than reporting it afterwards. Message them *before* you edit, not after the merge.
+
+## Writing a spec that works
+
+`taskops_plan` is where most of the damage gets done, because the reader of a `spec` is a
+**fresh agent with none of your context** — possibly on another developer's machine, three
+days from now.
+
+A spec that works says:
+
+- what **done** looks like, concretely enough to disagree with
+- what must **not** change
+- **where to start** — the files, the sibling to copy, the test that pins the behaviour
+
+A one-line spec is the single most common cause of an agent doing the wrong thing correctly.
+
+Also name `files`. It is how the scheduler avoids handing two agents the same file, and it is
+what the collision warning is computed from.
+
+## Dependencies
+
+`after` in `taskops_plan` accepts the 0-based **index** of an earlier task in the same batch,
+so a whole plan lands in one call:
+
+```json
+[
+  {"title": "Add the events table",  "spec": "…", "files": ["storage/_events.py"]},
+  {"title": "Board reads the table", "spec": "…", "after": [0]}
+]
+```
+
+Nothing polls. When a task closes, everything that was only waiting on it becomes ready
+immediately, and `taskops_update` tells you what you just handed to the fleet.
+
+If you discover a dependency mid-task, use `blocked_on` — it adds the edge **and** marks you
+blocked. A dependency that lives only in a comment is one the scheduler will walk somebody
+straight into.
+
+## If you are an ORCHESTRATOR: dispatching workers
+
+`taskops_dispatch` assigns cards, creates a git worktree per card, and hands you a **brief per
+card**. It starts nothing. You then spawn ONE SUB-AGENT PER BRIEF, all in a single message so they
+run in parallel — they use the session you are already in.
+
+```
+taskops_plan      →  the cards
+taskops_dispatch  →  N briefs           ← nothing is running yet
+your Agent tool   →  N sub-agents       ← paste one brief each, in ONE message
+```
+
+Two rules for the workers, and both are in the brief already:
+
+- **Each works inside its own worktree** (`.taskops/trees/<id>/`), which is already checked out on
+  the card's branch. A worktree is per CARD, not per agent.
+- **Nobody ever runs `git switch`.** Sub-agents share the repository, so switching would move the
+  branch under every other worker at once. This is the whole reason the worktree exists.
+
+Pass `spawn: true` only if you want detached processes that outlive your session — each one opens a
+NEW Claude session, which is rarely what you want.
+
+A spawned worker inherits your environment MINUS the Anthropic credentials
+(`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`). The `claude` CLI prefers an
+exported key over the logged-in subscription, so without this every worker would quietly bill per
+token against a plan you already pay for. `taskops run --use-api-key` asks for the other mode out
+loud; no MCP tool can.
+
+**If you dispatch and then do not spawn**, the cards sit assigned to workers that never existed. Run
+`taskops recover` to hand them back.
+
+## When a fleet dies
+
+Workers get killed: a session ends, a balance runs out, somebody hits ctrl-C. Their cards stay
+`claimed` until their leases expire, which is fifteen minutes of a board that looks busy and is not.
+
+```
+taskops recover           # releases every card whose worker has gone quiet
+taskops recover --force   # …including the ones still reporting, for a fleet that is alive and wrong
+```
+
+It clears the assignment as well as the lease — a card handed back still assigned to a dead worker is
+one NOBODY can pick up, since the scheduler hides it from everyone else.
+
+And it writes on each card what survived: commits are safe in git, and **uncommitted work is named
+with its path**, because a killed agent writes before it commits. Read that before starting over.
+
+## Reading the board
+
+- `taskops_report board` — every column, who holds what
+- `taskops_report standup --since 24h` — what changed, per actor, and what needs a human
+- `taskops_report fleet` — which agents are alive right now, on what, touching what file
+
+In `fleet`, `SILENT` means the agent still holds a claim but has gone quiet past the grace
+period. That row is shown rather than hidden, because it is the one somebody needs to act on.
+
+## Multi-developer, no server
+
+`.taskops/events.jsonl` is an append-only log, and it is **committed**. Two developers'
+agents converge through `git pull`: appending to different ends of a file is the one edit git
+merges without help, and every event's id is its content hashed, so importing the same event
+twice does nothing.
+
+`.taskops/db.sqlite` is a **cache** and is gitignored. It can be rebuilt from the log, so
+deleting it loses nothing but live leases.
+
+The `post-merge` hook syncs for you. Run `taskops sync` by hand any time; it is idempotent.
+
+## Three doors, and which one is yours
+
+```
+taskops <cmd>                       a person, at a terminal. seven commands.
+taskops_* (MCP)                     you. seven tools — this is your door.
+python -m taskops.transports.hooks  git and Claude Code. never type it.
+```
+
+Yours is the MCP tools. If one of them is refused, the refusal names what to do — read it
+rather than reaching for the CLI, which no longer carries `next`, `update`, `ask`, `plan` or
+`log` at all. What a person types is `taskops tasks …`, and what a hook runs is the third
+line, which exists only because git cannot speak MCP.
+
+## If something looks wrong
+
+- **"no taskops project"** — run `taskops init` in the repository root.
+- **A commit was denied** — read the message; it names the branch to switch to or the task to
+  claim. Do not use `--no-verify` to get around it. The `post-commit` hook will record the
+  commit anyway, and you will have a commit whose task nobody agreed on.
+- **`taskops_next` says nothing is ready** — read the reason. "Everything blocked" is worth
+  reporting to a human; "everything claimed" means ask again shortly.
+- **Hooks are not firing** — they live in `.git/hooks`, which is not tracked, so a fresh
+  clone has none, and a repository set up by an older taskops has a line naming a command that
+  has since moved. `taskops init` again repairs both: it chains onto hooks somebody else put
+  there, and rewrites the line it wrote itself. Worth knowing why nothing warned you — every
+  hook line ends in `|| true`, so a hook pointing at a command that does not exist fails
+  completely silently, and commits just stop appearing on their cards.