shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/results.py

@@ -0,0 +1,217 @@
+"""Pure derivation of a task's Results from recorded data: no git call, nothing guessed."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, cast
+
+from shikiru.config.settings import SQUASH_INTEGRATION
+from shikiru.domain.briefing import ProducedNumbers, facts_commit_lines, parse_produced
+from shikiru.domain.tasks import Status
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from shikiru.domain.briefing import PullRequestLine, ReportedTests
+    from shikiru.domain.reports import Commit
+
+SHORT_SHA_LENGTH = 7
+DONE_COMMITS_KEY = "commits"
+DONE_RISKS_KEY = "residual_risks"
+DONE_INTEGRATION_KEY = "integration"
+DONE_CHANGES_KEY = "changes"
+CHANGES_FILES_KEY = "files"
+CHANGES_INSERTIONS_KEY = "insertions"
+CHANGES_DELETIONS_KEY = "deletions"
+SCOPE_CHANGES_KEY = "scope_changes"
+NEW_TASK_IDS_KEY = "new_task_ids"
+
+
+class ResultOutcome(StrEnum):
+    """Whether the task's work reached its base branch."""
+
+    MERGED = "merged"
+    NOT_MERGED = "not merged"
+    SO_FAR = "so far"
+
+
+@dataclass(frozen=True)
+class ResultCommit:
+    """A commit as a short hash and its subject."""
+
+    sha: str
+    subject: str
+
+
+@dataclass(frozen=True)
+class LiveWork:
+    """A task's work as its worktree holds it now: commits past its base and the changes."""
+
+    commits: tuple[ResultCommit, ...]
+    produced: ProducedNumbers
+
+    @classmethod
+    def from_oneline(
+        cls, commit_lines: Sequence[str], *, files: int, insertions: int, deletions: int
+    ) -> LiveWork:
+        """Build the observation from `git log --oneline` lines and the change totals."""
+        commits = tuple(_from_oneline(line) for line in commit_lines)
+        return cls(commits, ProducedNumbers(len(commits), files, insertions, deletions))
+
+
+@dataclass(frozen=True)
+class PlanChange:
+    """One recorded scope change: what changed and the tasks it created as (id, title or None)."""
+
+    scope_changes: tuple[str, ...]
+    new_tasks: tuple[tuple[str, str | None], ...]
+
+
+@dataclass(frozen=True)
+class TaskResults:
+    """What a task produced; `more_commits` counts the commits beyond the capped list.
+
+    `live_error` is set when the task's current Git state could not be read, so the commits and
+    numbers shown are the recorded ones and must be labelled as such.
+    """
+
+    outcome: ResultOutcome
+    branch: str | None
+    base: str | None
+    commits: tuple[ResultCommit, ...]
+    more_commits: int
+    produced: ProducedNumbers | None
+    tests: ReportedTests | None
+    pull_request: PullRequestLine | None
+    plan_changes: tuple[PlanChange, ...]
+    plan_summary: str | None
+    residual_risks: tuple[str, ...]
+    live_error: str | None
+    squashed: bool = False
+
+
+def _strings(value: object) -> tuple[str, ...]:
+    items = cast("list[object]", value) if isinstance(value, list) else []
+    return tuple(item for item in items if isinstance(item, str))
+
+
+def _from_oneline(line: str) -> ResultCommit:
+    sha, _, subject = line.partition(" ")
+    return ResultCommit(sha[:SHORT_SHA_LENGTH], subject.strip())
+
+
+def _outcome(status: Status) -> ResultOutcome:
+    if status is Status.DONE:
+        return ResultOutcome.MERGED
+    return ResultOutcome.NOT_MERGED if status is Status.CANCELLED else ResultOutcome.SO_FAR
+
+
+def tracks_live_work(status: Status) -> bool:
+    """Whether a task still shows live work; a finished one keeps its recorded Results."""
+    return status not in (Status.DONE, Status.CANCELLED)
+
+
+def new_task_ids(scope_events: Sequence[Mapping[str, object]]) -> tuple[str, ...]:
+    """Return the distinct ids of the tasks the recorded scope changes created, sorted."""
+    return tuple(
+        sorted(
+            {task_id for data in scope_events for task_id in _strings(data.get(NEW_TASK_IDS_KEY))}
+        )
+    )
+
+
+def landed_changes(done: Mapping[str, object]) -> tuple[int, int, int] | None:
+    """Return the recorded (files, insertions, deletions) of `done`, or `None` when absent."""
+    changes = done.get(DONE_CHANGES_KEY)
+    if not isinstance(changes, dict):
+        return None
+    found = cast("dict[str, object]", changes)
+    counts = tuple(
+        found.get(key) for key in (CHANGES_FILES_KEY, CHANGES_INSERTIONS_KEY, CHANGES_DELETIONS_KEY)
+    )
+    if not all(isinstance(count, int) for count in counts):
+        return None
+    files, insertions, deletions = cast("tuple[int, int, int]", counts)
+    return files, insertions, deletions
+
+
+def _residual_risks(done: Mapping[str, object], verdict_risks: Sequence[str]) -> tuple[str, ...]:
+    if DONE_RISKS_KEY in done:
+        return _strings(done[DONE_RISKS_KEY])
+    return tuple(verdict_risks)
+
+
+def derive_task_results(
+    status: Status,
+    *,
+    branch: str | None,
+    base: str | None,
+    done: Mapping[str, object] | None,
+    report_commits: Sequence[Commit],
+    facts: str | None,
+    tests: ReportedTests | None,
+    pull_request: PullRequestLine | None,
+    scope_events: Sequence[Mapping[str, object]],
+    titles: Mapping[str, str],
+    verdict_risks: Sequence[str],
+    plan_summary: str | None,
+    commit_cap: int,
+    live: LiveWork | None = None,
+    live_error: str | None = None,
+) -> TaskResults:
+    """Derive the Results of a task from its recorded events, reports and facts snapshot.
+
+    A live observation of the task's worktree (`live`) is authoritative for its commits and
+    produced numbers, even when it finds none, so a report or facts snapshot that predates a
+    commit or revert never shows. Without one, a `TASK_DONE` that recorded the landed changes of
+    its integration is authoritative for the commits (even none) and the numbers, so neither report
+    commits nor the facts of the pre-integration branch show. Otherwise commits come from
+    `TASK_DONE` for a Done task,
+    else the latest report, else the facts; the first source with commits wins, and the numbers
+    come from the facts. Residual risks come from `TASK_DONE` when it recorded a risk list, even
+    an empty one, else from `verdict_risks`: the verdict of the task's current iteration. A new
+    task missing from `titles` keeps its id with no title.
+    """
+    done_data = done or {}
+    landed = landed_changes(done_data) if live is None else None
+    if live is not None:
+        commits, produced = live.commits, live.produced
+    elif landed is not None:
+        commits = tuple(_from_oneline(line) for line in _strings(done_data.get(DONE_COMMITS_KEY)))
+        produced = ProducedNumbers(len(commits), *landed)
+    else:
+        candidates = (
+            tuple(_from_oneline(line) for line in _strings(done_data.get(DONE_COMMITS_KEY))),
+            tuple(
+                ResultCommit(commit.sha[:SHORT_SHA_LENGTH], commit.subject)
+                for commit in report_commits
+            ),
+            tuple(_from_oneline(line) for line in facts_commit_lines(facts)),
+        )
+        commits = next((found for found in candidates if found), ())
+        produced = parse_produced(facts)
+    return TaskResults(
+        outcome=_outcome(status),
+        branch=branch,
+        base=base,
+        commits=commits[:commit_cap],
+        more_commits=max(len(commits) - commit_cap, 0),
+        produced=produced,
+        tests=tests,
+        pull_request=pull_request,
+        plan_changes=tuple(
+            PlanChange(
+                _strings(data.get(SCOPE_CHANGES_KEY)),
+                tuple(
+                    (task_id, titles.get(task_id))
+                    for task_id in _strings(data.get(NEW_TASK_IDS_KEY))
+                ),
+            )
+            for data in scope_events
+        ),
+        plan_summary=plan_summary,
+        residual_risks=_residual_risks(done_data, verdict_risks),
+        live_error=live_error,
+        squashed=landed is not None and done_data.get(DONE_INTEGRATION_KEY) == SQUASH_INTEGRATION,
+    )

shikiru/domain/runs.py

@@ -0,0 +1,85 @@
+"""Agent run model: one row per task role's session lineage."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum, auto
+
+from shikiru.agents.contracts import (
+    BILLING_MODE_UNKNOWN,
+    BILLING_SOURCE_UNKNOWN,
+    BillingMode,
+    BillingSource,
+    Usage,
+)
+from shikiru.domain.levels import displayed_pct
+from shikiru.domain.tasks import DomainModel, Role
+
+NO_USAGE = Usage(
+    input_tokens=0,
+    output_tokens=0,
+    cache_read_tokens=0,
+    cache_write_tokens=0,
+    cost_usd=None,
+    cost_basis="unknown",
+    context_used_pct=None,
+)
+
+
+class RunStatus(StrEnum):
+    """A run's lifecycle."""
+
+    LIVE = auto()
+    TAKEN_OVER = auto()
+    CLOSED = auto()
+
+
+class Run(DomainModel):
+    """One agent session for a task role (mirrors the `runs` table)."""
+
+    id: int
+    task_id: str
+    role: Role
+    agent: str
+    model: str
+    effort: str | None = None
+    session_id: str | None = None
+    resume_command: str | None = None
+    last_message: str | None = None
+    status: RunStatus
+    usage: Usage = NO_USAGE
+    usage_reported: bool | None = None
+    billing_mode: BillingMode = BILLING_MODE_UNKNOWN
+    billing_source: BillingSource = BILLING_SOURCE_UNKNOWN
+    started_at: datetime
+    ended_at: datetime | None = None
+
+
+def has_positive_token_evidence(run: Run) -> bool:
+    """Return whether `run` records a positive token count in any usage field."""
+    return any(
+        token > 0
+        for token in (
+            run.usage.input_tokens,
+            run.usage.output_tokens,
+            run.usage.cache_read_tokens,
+            run.usage.cache_write_tokens,
+        )
+    )
+
+
+MISSING_TITLE_VALUE = "\N{EN DASH}"
+
+
+def context_title(usage: Usage) -> str:
+    """Format `usage`'s context share for a title (`42%`), or a dash if unreported."""
+    if usage.context_used_pct is None:
+        return MISSING_TITLE_VALUE
+    return f"{displayed_pct(usage.context_used_pct)}%"
+
+
+def cost_title(usage: Usage) -> str:
+    """Format `usage`'s cost for a title (`$1.84`), or a dash if unreported."""
+    if usage.cost_usd is None:
+        return MISSING_TITLE_VALUE
+    return f"${usage.cost_usd:.2f}"

shikiru/domain/scheduling.py

@@ -0,0 +1,231 @@
+"""Ready-set computation and dispatch gating."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum, auto
+from graphlib import CycleError, TopologicalSorter
+from typing import TYPE_CHECKING
+
+from shikiru.domain.ladder import move_up, pick_rung
+from shikiru.domain.steps import task_acting_role
+from shikiru.domain.tasks import Role, Status
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping, Sequence
+    from datetime import datetime
+
+    from shikiru.config.settings import Settings
+    from shikiru.domain.tasks import Task
+
+
+class WaitReason(StrEnum):
+    """Why a task is waiting instead of running."""
+
+    PAUSED = auto()
+    DEPENDENCY = auto()
+    SLOT = auto()
+    RESOURCES = auto()
+    QUOTA = auto()
+    PR_OPEN = "PR open"
+
+
+@dataclass(frozen=True)
+class TaskAgents:
+    """The agent names a task would use for the Leader and the Implementer roles."""
+
+    leader: str
+    implementer: str
+
+
+@dataclass(frozen=True)
+class SchedulingGates:
+    """Pure data the scheduler gathers before a dispatch pass."""
+
+    free_slots: frozenset[int]
+    resources_ok: bool
+    blocked_agents: frozenset[str]
+    agents: Mapping[str, TaskAgents]
+
+
+@dataclass(frozen=True)
+class Dispatch:
+    """A task to dispatch into `slot`."""
+
+    task_id: str
+    slot: int
+
+
+@dataclass(frozen=True)
+class ReadySchedule:
+    """The result of one scheduling pass."""
+
+    dispatches: tuple[Dispatch, ...]
+    wait_reasons: Mapping[str, WaitReason]
+    dependency_cancelled: tuple[str, ...]
+
+
+def find_dependency_cycle(dependencies: Mapping[str, Iterable[str]]) -> tuple[str, ...]:
+    """Return the task ids on one dependency cycle (a self-edge included), or none."""
+    try:
+        TopologicalSorter(dependencies).prepare()
+    except CycleError as error:
+        return tuple(dict.fromkeys(error.args[1]))
+    return ()
+
+
+def dispatch_sort_key(task: Task) -> tuple[bool, int, int]:
+    """Order `task` the way dispatch does: requeued first, then priority, then submit order."""
+    return (task.requeued_at is None, -task.priority, task.seq)
+
+
+def occupied_slot_ids(tasks: Sequence[Task]) -> frozenset[int]:
+    """Return distinct slots held by running or integrating tasks."""
+    return frozenset(
+        task.slot
+        for task in tasks
+        if task.status in (Status.RUNNING, Status.INTEGRATING) and task.slot is not None
+    )
+
+
+def task_agents(task: Task, settings: Settings) -> TaskAgents:
+    """Resolve the Leader and Implementer agents `task` would use for its next turns."""
+    return TaskAgents(
+        leader=pick_rung(task, Role.LEADER, settings).agent,
+        implementer=pick_rung(task, Role.IMPLEMENTER, settings).agent,
+    )
+
+
+def quota_blocked_agents(agents: TaskAgents, blocked_until: Mapping[str, datetime]) -> list[str]:
+    """Return each agent of `agents` that is blocked, once each, Leader first."""
+    return [
+        agent
+        for agent in dict.fromkeys((agents.leader, agents.implementer))
+        if agent in blocked_until
+    ]
+
+
+def quota_blocking_agent(agents: TaskAgents, blocked_until: Mapping[str, datetime]) -> str | None:
+    """Return the blocked agent of `agents` with the latest deadline; Leader wins ties."""
+    blocked = quota_blocked_agents(agents, blocked_until)
+    return max(blocked, key=blocked_until.__getitem__, default=None)
+
+
+def quota_wait_reroutes(
+    task: Task,
+    settings: Settings,
+    blocked_until: Mapping[str, datetime],
+    wait_limit: datetime,
+) -> bool:
+    """Return whether the scheduler moves `task` to another agent: its block outlasts `wait_limit`.
+
+    A role moves when its resolved agent is blocked beyond `wait_limit` and a rung on a different,
+    unblocked agent exists, a higher one first, else one below; this is the rule the scheduler
+    applies to queued tasks.
+    """
+    blocked_agents = frozenset(blocked_until)
+    for role in (Role.LEADER, Role.IMPLEMENTER):
+        until = blocked_until.get(pick_rung(task, role, settings).agent)
+        if until is None or until <= wait_limit:
+            continue
+        moved = move_up(task, role, settings, different_agent=True, blocked_agents=blocked_agents)
+        if moved is not None:
+            return True
+    return False
+
+
+def running_quota_wait_moves(
+    task: Task,
+    settings: Settings,
+    block_until: datetime,
+    budget_ends: datetime,
+    blocked_agents: frozenset[str],
+) -> bool:
+    """Return whether a running turn's quota wait moves `task` to another agent when it gives up.
+
+    The engine fixes the wait's deadline at `budget_ends` when the wait starts. It gives up only
+    if the block still outlasts that deadline, and then moves the acting role to a different agent
+    when one exists that is not in `blocked_agents`, the rule the engine's recovery applies.
+    """
+    if block_until <= budget_ends:
+        return False
+    moved = move_up(
+        task,
+        task_acting_role(task),
+        settings,
+        different_agent=True,
+        blocked_agents=blocked_agents,
+    )
+    return moved is not None
+
+
+def _group_queued_tasks(
+    tasks: Sequence[Task], by_id: Mapping[str, Task]
+) -> tuple[list[Task], dict[str, WaitReason], list[str]]:
+    ready: list[Task] = []
+    wait_reasons: dict[str, WaitReason] = {}
+    dependency_cancelled: list[str] = []
+    for task in tasks:
+        if task.status != Status.QUEUED:
+            continue
+        if task.held:
+            wait_reasons[task.id] = WaitReason.PAUSED
+            continue
+        deps = [by_id[dep_id] for dep_id in task.depends_on]
+        if any(dep.status == Status.CANCELLED for dep in deps):
+            dependency_cancelled.append(task.id)
+            continue
+        if all(dep.status == Status.DONE for dep in deps):
+            ready.append(task)
+        else:
+            wait_reasons[task.id] = WaitReason.DEPENDENCY
+    return ready, wait_reasons, dependency_cancelled
+
+
+def pick_ready(tasks: Sequence[Task], gates: SchedulingGates) -> ReadySchedule:
+    """Return the ready set in dispatch order, gated by slots, resources and quota.
+
+    `tasks` is every task the caller tracks, so dependency statuses can be looked up by id; an
+    id that isn't in `tasks` is a caller bug and raises `KeyError`, as does a ready task missing
+    from `gates.agents`.
+
+    Ready tasks are ordered with `requeued_at` set first, then `priority` descending, then `seq`.
+    Slot and resources are gates shared by the whole pass: the first one that fails stops
+    dispatch there, and every task from that point on shares its `wait_reason`, since a
+    lower-priority task never dispatches ahead of a blocked one. Quota is scoped to one task at a
+    time (a quota block is the only cross-task effect, but it is still per-agent, not
+    per-pass): a quota-blocked task is skipped and dispatch continues with the next one.
+    """
+    by_id = {task.id: task for task in tasks}
+    ready, wait_reasons, dependency_cancelled = _group_queued_tasks(tasks, by_id)
+
+    ordered = sorted(ready, key=dispatch_sort_key)
+    remaining_slots = set(gates.free_slots)
+    dispatches: list[Dispatch] = []
+    stopped_reason: WaitReason | None = None
+
+    for task in ordered:
+        if stopped_reason is not None:
+            wait_reasons[task.id] = stopped_reason
+            continue
+        if not remaining_slots:
+            stopped_reason = WaitReason.SLOT
+            wait_reasons[task.id] = stopped_reason
+            continue
+        if not gates.resources_ok:
+            stopped_reason = WaitReason.RESOURCES
+            wait_reasons[task.id] = stopped_reason
+            continue
+        agents = gates.agents[task.id]
+        if agents.leader in gates.blocked_agents or agents.implementer in gates.blocked_agents:
+            wait_reasons[task.id] = WaitReason.QUOTA
+            continue
+        slot = task.slot if task.slot in remaining_slots else min(remaining_slots)
+        remaining_slots.discard(slot)
+        dispatches.append(Dispatch(task_id=task.id, slot=slot))
+
+    return ReadySchedule(
+        dispatches=tuple(dispatches),
+        wait_reasons=wait_reasons,
+        dependency_cancelled=tuple(dependency_cancelled),
+    )

shikiru/domain/status_tasks.py

@@ -0,0 +1,40 @@
+"""Human project status task selection."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.domain.scheduling import dispatch_sort_key
+from shikiru.domain.tasks import Status
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from shikiru.domain.tasks import Task
+
+HUMAN_STATUS_TASK_LIMIT = 10
+_OTHER_ACTIVE_STATUSES = (Status.RUNNING, Status.INTEGRATING)
+
+
+def select_human_status_tasks(tasks: Sequence[Task]) -> tuple[Task, ...]:
+    """Select at most ten tasks, reserving the final row for a latest recorded completion."""
+    escalated = sorted(
+        (task for task in tasks if task.status is Status.ESCALATED), key=lambda task: task.seq
+    )
+    active = sorted(
+        (task for task in tasks if task.status in _OTHER_ACTIVE_STATUSES),
+        key=lambda task: task.seq,
+    )
+    queued = sorted((task for task in tasks if task.status is Status.QUEUED), key=dispatch_sort_key)
+    completed = [task for task in tasks if task.status is Status.DONE]
+    with_finish_time = [task for task in completed if task.finished_at is not None]
+    done = (
+        max(with_finish_time, key=lambda task: (task.finished_at, task.seq))
+        if with_finish_time
+        else max(completed, key=lambda task: task.seq, default=None)
+    )
+    available_rows = HUMAN_STATUS_TASK_LIMIT - (done is not None)
+    selected = (escalated + active + queued)[:available_rows]
+    if done is not None:
+        selected.append(done)
+    return tuple(selected)