taskops-cli 0.2.0__py3-none-any.whl

taskops/contracts/__init__.py

@@ -0,0 +1,96 @@
+"""Layer 1 — every payload that crosses a boundary, defined once.
+
+ZERO logic lives here: only types. `storage` reads and writes them, `engine`
+decides with them, `render` turns them into text, the three transports serialize
+them, and the studio mirrors them in TypeScript. One definition, six readers.
+
+TypedDict on purpose, not dataclasses and not pydantic: at runtime these ARE
+dicts, so a consumer writes `task["status"]`, the wire format is the same object
+serialized, and the package keeps its zero dependencies.
+
+⚠️ Optionality uses the `total=False` SPLIT, never `NotRequired`. Under
+`from __future__ import annotations` every annotation is a string, so TypedDict
+cannot see a `NotRequired[...]` marker at class-creation time: `__optional_keys__`
+comes back EMPTY and every field reads as required to anything that introspects
+the class — including the MCP schema generator, which would then advertise every
+optional parameter as mandatory. Totality is class-level, so the split is immune.
+`tests/contracts/test_optionality.py` pins this.
+
+This package imports nothing but layer 0, so it can never introduce a cycle —
+which is what lets every layer above depend on it freely.
+"""
+
+from __future__ import annotations
+
+from .actor import Actor
+from .board import (
+    Activity,
+    ActorRoll,
+    Board,
+    Burndown,
+    Card,
+    Column,
+    Fleet,
+    FleetMember,
+    Standup,
+)
+from .commit import CommitRef
+from .day import ClosedCard, CommitStat, DayReport, OpenedCard, PeriodReport, ReportFile
+from .dep import Dep
+from .event import Event, Inbox
+from .gitstate import BranchState
+from .index import ReportEntry
+from .lease import Lease
+from .log import EntryKind, LogEntry, SessionLog
+from .remote import Remote
+from .results import Claim, EditResult, NextResult, PlanResult, UpdateResult
+from .task import Task, TaskView
+from .tools import AskParams, NextParams, PlanParams, ReportParams, UpdateParams
+from .wire import WireMessage
+
+__all__ = [
+    # the entities
+    "Task",
+    "TaskView",
+    "Dep",
+    "Lease",
+    "Actor",
+    "Event",
+    "WireMessage",
+    "Inbox",
+    "BranchState",
+    "CommitRef",
+    "LogEntry",
+    "SessionLog",
+    "EntryKind",
+    "Remote",
+    # what the use cases return
+    "PlanResult",
+    "Claim",
+    "NextResult",
+    "UpdateResult",
+    "EditResult",
+    # the projections
+    "Board",
+    "Column",
+    "Card",
+    "Standup",
+    "Activity",
+    "ActorRoll",
+    "Burndown",
+    "DayReport",
+    "PeriodReport",
+    "ClosedCard",
+    "OpenedCard",
+    "CommitStat",
+    "ReportFile",
+    "ReportEntry",
+    "Fleet",
+    "FleetMember",
+    # what a tool call carries in
+    "PlanParams",
+    "NextParams",
+    "UpdateParams",
+    "AskParams",
+    "ReportParams",
+]

taskops/contracts/_fields.py

@@ -0,0 +1,113 @@
+"""The field descriptions, and the aliases shared across tool contracts.
+
+Prose in a data structure, so it is split out for the same reason `transports/mcp/_descriptions` is:
+reviewing a change to which fields a tool takes should not mean re-reading sixty lines of unchanged
+text. The strings themselves are the contract — they are the only thing a calling agent reads before
+it chooses arguments.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+__all__ = ["Repo", "Actor", "Session", "TaskId", "TASKS", "DRY_RUN", "STATUS", "COMMENT",
+           "MENTIONS", "BLOCKED_ON", "NO_CODE", "LABELS", "CLAIM_ONE", "ASK_TASK",
+           "ASK_QUERY", "DISPATCH_TASKS", "DISPATCH_COUNT", "PREFIX", "MODEL",
+           "RECOVER_FORCE", "RECOVER_GRACE", "REPORT_KIND", "REPORT_ACTOR", "SINCE", "DATE"]
+
+Repo = Annotated[str, "path to the repository root; a path INSIDE it also works — "
+                      "the root is found from .taskops"]
+
+Actor = Annotated[str, "who is calling: `agent:<dev>/<name>` or `dev:<name>`. Omit "
+                       "and it resolves from $TASKOPS_ACTOR or the git identity"]
+
+Session = Annotated[str, "your Claude Code session id. It links this work to your "
+                         "transcript on the live board"]
+
+TaskId = Annotated[str, "a task id, e.g. tk-4f2a9c"]
+
+
+
+TASKS = ("the tasks to create: a list of {title, spec, priority?, labels?, files?, parent?, "
+         "after?, blocks?, assignee?}. `spec` is the brief a FRESH agent reads to do the work "
+         "with no other context — what done looks like, what must not change, where to start. "
+         "`after` lists what must finish BEFORE this card, each an existing id or the 0-based "
+         "INDEX of an earlier entry in this same list. `blocks` is the inverse: existing cards "
+         "that must wait for this one — that is how an agent mid-task creates the prerequisite it "
+         "just discovered and makes its own task wait, in one call. `files` is the edit surface: "
+         "name it and no two agents get the same file")
+
+STATUS = ("the new status. `released` returns the task to the queue with your progress in "
+          "`comment` — the honest move when out of context. `done` needs a commit bound to "
+          "this task")
+
+COMMENT = ("what happened, for the task's thread. Write the decision and the surprise; the next "
+           "agent and the human reviewing at 9am read this and nothing else")
+
+MENTIONS = ("comma-separated actor ids to notify, e.g. 'agent:ana/api-1,dev:ana'. It reaches "
+            "their inbox and the live board — this is how you raise a shared file with another "
+            "developer's agent")
+
+BLOCKED_ON = ("a task id that must finish first. Adds the dependency AND sets you blocked, so a "
+              "discovery lands in the graph instead of a comment")
+
+NO_CODE = ("declare that this task produces no commit (research, a decision, docs elsewhere). "
+           "Required to close one, and recorded with your comment as the justification")
+
+LABELS = "comma-separated labels to restrict the pick to"
+
+CLAIM_ONE = ("claim THIS task rather than letting the scheduler choose. Use it when a human named "
+             "one — otherwise the scheduler also avoids files another live agent is in")
+
+ASK_TASK = ("the task to read in full: spec, conversation, commits, what blocks it, what it "
+            "blocks, and which other tasks touch the same files")
+
+ASK_QUERY = "free text over titles, specs and comments, when you have no id. Search once, then ask by id"
+
+DISPATCH_TASKS = ("comma-separated task ids to dispatch, one worker each. Omit to let the "
+                  "scheduler pick the best `count` ready cards")
+
+DISPATCH_COUNT = ("how many workers to launch when you did not name tasks (default 3, ceiling "
+                  "12). Every worker is a real Claude Code process, so ask for what you need "
+                  "rather than for everything")
+
+PREFIX = ("names the workers `agent:<you>/<prefix>1..n` (default 'w'), so a fleet view reads as "
+          "api1, api2 instead of three hashes")
+
+MODEL = ("model for the workers, e.g. claude-sonnet-5. Omit for their default — a cheap model is "
+         "often right for mechanical cards")
+
+REPORT_KIND = ("board (default) every column; standup what changed in a window, per actor; "
+               "day the full dossier of ONE calendar day — every card closed with its "
+               "commits and their diff sizes, what is still in flight, and the conversation; "
+               "range the same dossier over MANY days, grouped by day (pass `last`, or "
+               "`from`/`to`, and omit both for the WHOLE project)")
+
+REPORT_ACTOR = "restrict a standup to one actor"
+
+SINCE = "how far back a standup looks: '24h', '7d', '30m'"
+
+LAST = ("with kind=range: how far back from `to`, e.g. '7d', '2w', '1m'. Inclusive of both "
+        "ends — '7d' is seven days of work. Leave `last`, `from` and `to` all empty and a "
+        "range covers the project from its first event, which is what to ask for when "
+        "somebody wants everything evaluated and not just one day")
+
+FROM_DATE = ("with kind=range: the first day, 'YYYY-MM-DD'. Use it instead of `last` when the "
+             "window is a specific span rather than a distance back from today")
+
+TO_DATE = ("with kind=range: the last day, INCLUSIVE, 'YYYY-MM-DD'. Defaults to today")
+
+DATE = ("which day a `day` report covers: 'today' (default), 'yesterday', or a date like "
+        "2026-07-28. It is a CALENDAR day in local time, not a rolling window — ask for the "
+        "same date tomorrow and you get the same report")
+
+DRY_RUN = ("show which cards WOULD get a worker and stop — nothing assigned, nothing launched. "
+           "Worth doing first when you are about to spend several models on a plan you just wrote")
+
+RECOVER_FORCE = ("release cards even from workers that are STILL reporting. For a fleet that is "
+                 "alive and WRONG — chasing a bad spec, say. Without it, only workers that have "
+                 "gone silent are touched")
+
+RECOVER_GRACE = ("seconds of silence before a worker counts as gone. Defaults to the same grace "
+                 "the fleet view uses to print SILENT, so what you see on the board is exactly "
+                 "what this acts on")

taskops/contracts/actor.py

@@ -0,0 +1,30 @@
+"""Who did it — the identity that outlives a session.
+
+The "50 First Dates" problem in one type: a Claude Code session is anonymous and
+gone tomorrow, so anything it writes has to be attributed to something that is
+neither. An actor id is `dev:<name>` or `agent:<dev>/<name>`, and the second half
+of the agent form is what makes a hundred agents belonging to four developers
+legible on one board — every agent answers to a human by construction.
+
+Format handling lives in `engine.identity`, not here: this layer is types only.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from .._types import ActorKind
+
+__all__ = ["Actor"]
+
+
+class Actor(TypedDict):
+    """A developer or one of their agents."""
+
+    id: str
+    """`dev:berna` or `agent:berna/polecat-1`. The wire form, and what the event
+    log stores — a nested object would make every event three lines of JSON."""
+
+    kind: ActorKind
+    dev: str
+    """The human accountable for this actor. For a dev, itself."""

taskops/contracts/board.py

@@ -0,0 +1,142 @@
+"""The projections — what a human or an agent gets to LOOK at.
+
+Every one of these is derived from tasks plus the event log, never stored. That is
+the property that makes them safe to change: a new column or a different standup
+window is a rendering decision, not a migration.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from .._types import Status
+from .event import Event
+from .gitstate import BranchState
+from .lease import Lease
+from .task import Task
+
+__all__ = ["Card", "Column", "Board", "Standup", "Burndown", "FleetMember", "Fleet",
+           "ActorRoll", "Activity"]
+
+
+class Card(TypedDict):
+    """One task as the board shows it: the row, plus who is on it right now."""
+
+    task: Task
+    lease: Lease | None
+    blocked_by: int
+    blocks: int
+    commits: int
+
+
+class Column(TypedDict):
+    status: Status
+    cards: list[Card]
+
+
+class Board(TypedDict):
+    """The whole project, column by column, in declaration order of `STATUSES`."""
+
+    repo: str
+    columns: list[Column]
+    ready: int
+    """How many tasks could be picked up this second. The one number that says
+    whether adding another agent would help or just add contention."""
+
+    total: int
+
+
+class Standup(TypedDict):
+    """What happened in a window, per actor — generated, never written by hand."""
+
+    repo: str
+    since: float
+    actors: list[str]
+    events: list[Event]
+    done: list[Task]
+    in_flight: list[Task]
+    blocked: list[Task]
+
+
+class ActorRoll(TypedDict):
+    """One actor's whole record in the window — what they touched, not whether they are free.
+
+    Availability is not a question worth answering when agents are created on demand: there is no
+    pool to allocate from. What survives an agent's session is what it DID, and that is this.
+    """
+
+    actor: str
+    tasks: int
+    """Distinct tasks touched. Deliberately not "events": an actor that commented forty times on
+    one card has done less than one that closed four."""
+
+    commits: int
+    comments: int
+    done: int
+    first_seen: float
+    last_seen: float
+
+
+class Activity(TypedDict):
+    """The event log as something a person can read: a timeline, plus who did what.
+
+    A projection like every other one here — nothing is stored for it. The log already holds every
+    fact it shows, which is why this could be added without a migration and why it cannot drift.
+    """
+
+    repo: str
+    since: float
+    events: list[Event]
+    """Newest FIRST, unlike the log's own order. A timeline is read from the top, and a reader who
+    has to scroll to the bottom to find out what just happened will stop opening it."""
+
+    titles: dict[str, str]
+    """Task id -> title, for the tasks these events name. Sent with the timeline rather than fetched
+    per row: a hundred events would otherwise be a hundred requests to render one screen."""
+
+    actors: list[ActorRoll]
+    kinds: list[str]
+    """The kinds actually present, so the filter offers what exists instead of a hardcoded list that
+    goes stale the day a new kind is written."""
+
+    truncated: bool
+
+
+class Burndown(TypedDict):
+    """Open versus closed over time. Deliberately coarse: a day-level series is
+    what a burndown IS, and anything finer is a live board's job."""
+
+    repo: str
+    days: list[str]
+    open_counts: list[int]
+    done_counts: list[int]
+
+
+class FleetMember(TypedDict):
+    """One live session, as the fleet view sees it."""
+
+    actor: str
+    session: str
+    task: str
+    branch: str
+    alive: bool
+    """False once the lease has gone quiet past its grace — the lease is still on
+    the books, so the board must be able to show a claim it no longer believes."""
+
+    last_seen: float
+    doing: str
+    """The most recent `activity` event's summary — what tool touched what file.
+    Empty when the agent has not reported any, which a session without the plugin
+    installed never will."""
+
+    git: BranchState
+    """Whether this agent's work is reachable by anybody else yet.
+
+    The question a standup actually asks. An agent can be busy, alive, and holding three unpushed
+    commits that exist on one laptop — which looks identical to progress on a board that only shows
+    activity."""
+
+
+class Fleet(TypedDict):
+    repo: str
+    members: list[FleetMember]

taskops/contracts/commit.py

@@ -0,0 +1,36 @@
+"""A commit, as the card knows it.
+
+`TaskView.commits` used to be `list[str]` — bare shas — while the `commit` event underneath already
+carried the subject and the files it touched. So the data was recorded, stored, replicated, and then
+thrown away one layer before anybody could read it: a finished card showed `4c13dbd45823` and nothing
+else, and the only substance on the page was whatever the agent happened to write in a comment.
+
+Nothing here is new information. It is the event body, given a shape so that a renderer and the studio
+can use what was always there.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+__all__ = ["CommitRef"]
+
+
+class CommitRef(TypedDict):
+    """One commit bound to a task."""
+
+    sha: str
+    subject: str
+    """The commit's first line. What makes a list of commits readable at a glance instead of a
+    column of hashes — and the reason this contract exists."""
+
+    files: list[str]
+    """Paths the commit touched, as `git diff-tree` reported them.
+
+    Empty for a repository's very first commit, which has no parent to diff against. Also the answer
+    to "did this task do what its `files` said it would", which is a question a review asks and a
+    board could not previously support.
+    """
+
+    actor: str
+    ts: float

taskops/contracts/day.py

@@ -0,0 +1,150 @@
+"""ONE calendar day, in full — what a person reads at the end of it.
+
+A projection like every other one here: nothing is stored for it, every fact comes from
+`events.jsonl` plus what git already knows about the commits those events name. That is what
+makes it safe to change and what makes it impossible to flatter anybody — a dossier nobody
+typed cannot claim a card was closed that the log does not show closed.
+
+The unit is a CALENDAR day and not a rolling window, because that is the question being asked.
+"What happened yesterday" and "what happened in the last 24 hours" are different reports, and
+the second one silently moves every time it is run.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from .board import ActorRoll
+from .commit import CommitRef
+from .event import Event
+from .task import Task
+
+__all__ = ["CommitStat", "ClosedCard", "OpenedCard", "PeriodReport", "DayReport", "ReportFile"]
+
+
+class CommitStat(CommitRef):
+    """A commit with its SIZE — the one thing the event log does not carry.
+
+    `additions`/`deletions` come from git at read time rather than from the `commit` event,
+    because the event is written by a hook that must never be slow and because a diff can be
+    recomputed forever while a bad number recorded once is permanent.
+
+    Zeros when git could not answer (no repository, the sha is on another machine, a shallow
+    clone). Honest and useless beats raising inside a report.
+    """
+
+    additions: int
+    deletions: int
+
+
+class ClosedCard(TypedDict):
+    """A card that reached `done` on this day, with everything it took to get there."""
+
+    task: Task
+    actor: str
+    """Who closed it. The task row keeps the state and never who moved it there — this is the
+    only place that fact lives, and it comes from the `done` event."""
+
+    claimed_ts: float
+    """When its last claim before the close was taken, or the close itself when the card was
+    never claimed (a human closing something by hand). The pair with `done_ts` is the only
+    honest duration available: an earlier claim that was released is not time spent."""
+
+    done_ts: float
+    commits: list[CommitStat]
+    """Every commit bound to the task, not only the ones written today. A card closed at 9am
+    after three days of work shipped all of it, and showing one commit would understate it."""
+
+
+class OpenedCard(TypedDict):
+    """A card CREATED in this window and not yet closed — planned work, with its edges.
+
+    The section that was missing entirely: a window whose whole content is planning reported
+    `0 closed · 0 in flight · 0 blocked` and printed nothing, because `backlog` and `ready`
+    belonged to no section. A day spent writing four specs is a day something happened on.
+
+    The edges travel with the card because they ARE the content of a planning day: which of
+    these can be started right now, and which is waiting on which. A list of titles without
+    the DAG is the same silence in a longer form.
+    """
+
+    task: Task
+    waiting_on: list[str]
+    """Ids of the OPEN cards this one waits for. Empty means it can be started now."""
+
+    blocking: list[str]
+    """Ids waiting on this one — the argument for doing it first."""
+
+
+class PeriodReport(TypedDict):
+    """A WINDOW of calendar days, as one object. One day is the case where both ends match.
+
+    ONE contract rather than a day report and a range report side by side: they carry exactly
+    the same facts over a wider window, and two shapes would drift the moment a field was
+    added to the one somebody happened to be reading.
+    """
+
+    repo: str
+    from_date: str
+    """`YYYY-MM-DD`, in the reader's LOCAL calendar. The window opens at its 00:00."""
+
+    to_date: str
+    """`YYYY-MM-DD`, INCLUSIVE — the window closes at the midnight AFTER it."""
+
+    label: str
+    """What a human calls this window, and what names its file: `2026-07-28` for one day,
+    `2026-07-22..2026-07-28` for a range, `all` for the whole project. Derived and never
+    typed, so the heading of a report and the name of the file on disk cannot disagree."""
+
+    closed: list[ClosedCard]
+    dropped: int
+    """Closed cards the window held and this report does NOT carry, because the cap cut them.
+
+    Reported rather than silent, exactly as the activity view reports truncation: a month
+    that closed 400 cards and shows 200 of them is a fine report and a terrible lie."""
+
+    opened: list[OpenedCard]
+    """Cards created in the window and still open. A card created AND closed inside it is not
+    here — `closed` already tells that story in full, and listing it twice would invite a
+    reader to count it twice."""
+
+    in_flight: list[Task]
+    blocked: list[Task]
+    waiting: list[Task]
+    """Open cards touched in the window that nobody has started — `ready` and `backlog`.
+
+    They belonged to no section at all until this field existed, which is how a freshly
+    planned project reported that nothing had happened. Cards created in this window are
+    excluded: those are in `opened`, where they carry their dependencies too.
+    """
+
+    conversations: list[Event]
+    actors: list[ActorRoll]
+    commits_total: int
+
+
+DayReport = PeriodReport
+"""The one-day case, under the name every caller already used. An alias and not a second
+TypedDict — a subclass would be a second shape to keep in step for no gain."""
+
+
+class ReportFile(TypedDict):
+    """A day's dossier as it exists ON DISK — or as it would be if it were written.
+
+    `exists` and `stale` are two different answers and both are needed: a day nobody wrote up
+    is not the same as one written before half of it happened, and a reader who cannot tell
+    them apart will either regenerate a report somebody narrated or cite one that is short.
+    """
+
+    date: str
+    path: str
+    dossier_md: str
+    """The written file when there is one, INCLUDING any narration; otherwise the dossier the
+    generator would produce right now. A caller always gets something to read."""
+
+    exists: bool
+    stale: bool
+    missing_events: int
+    """How many of the day's events landed after the file was generated. `stale` is this
+    being non-zero; the number is here so a UI can say how far behind rather than just that
+    it is."""

taskops/contracts/dep.py

@@ -0,0 +1,23 @@
+"""The dependency edge. Two ids and a direction — that is genuinely all of it.
+
+Direction is fixed and worth stating once, because every reader gets it backwards
+otherwise: `task` must finish BEFORE `blocks` can start. So `deps` rows are read
+one way to ask "what am I waiting for" (`WHERE blocks = me`) and the other way to
+ask "who is waiting on me" (`WHERE task = me`), and both are one indexed lookup.
+
+Kept as a separate edge table rather than a `blocked_by` list on the task because
+the graph is queried from both ends, and a JSON list can only be read from one.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+__all__ = ["Dep"]
+
+
+class Dep(TypedDict):
+    """`task` blocks `blocks`."""
+
+    task: str
+    blocks: str

taskops/contracts/event.py

@@ -0,0 +1,58 @@
+"""The event — the only thing taskops actually stores.
+
+The board, a standup, an inbox and a burndown are all PROJECTIONS of this table.
+That is what makes "who decided this and when" answerable months later, and it is
+why adding a fact about a task is a new `kind` rather than a column somewhere.
+
+The id is the content, hashed (`_ids.event_id`), so the same event arriving twice
+— once through `git pull`, once through the relay — is a primary-key no-op rather
+than a duplicate comment in somebody's inbox.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+from .._types import EventKind
+
+__all__ = ["Event", "Inbox"]
+
+
+class Event(TypedDict):
+    """One thing that happened, attributed and timestamped."""
+
+    id: str
+    task: str
+    """The task it is about. Never empty: an event with no task cannot be found
+    again by anyone looking at the work, and project-wide facts belong in `meta`."""
+
+    actor: str
+    kind: EventKind
+
+    body: dict[str, Any]
+    """The payload, shaped by `kind` — `{sha, message, files}` for a commit,
+    `{text, mentions}` for a comment, `{from, to}` for a status change.
+
+    Deliberately open rather than a tagged union of thirteen TypedDicts: a reader
+    that does not know a kind must be able to store and forward it untouched,
+    because a newer taskops on a teammate's machine WILL write kinds this one has
+    never heard of into the shared log. Renderers read the keys they know.
+    """
+
+    ts: float
+
+
+class Inbox(TypedDict):
+    """What an actor has not been shown yet.
+
+    Delivery is tracked per (actor, event) rather than by a timestamp cursor: an
+    agent's hooks fire in an order nobody controls, and a cursor would silently
+    skip anything that arrived out of order.
+    """
+
+    actor: str
+    messages: list[Event]
+    """Directed at this actor — mentions and handoffs, oldest first."""
+
+    tasks: list[str]
+    """The tasks those messages are about, deduplicated, for the render's header."""