shikiru-cli 0.2.0__py3-none-any.whl

shikiru/engine/titles.py

@@ -0,0 +1,297 @@
+"""`TaskTitles`: pane and window titles, and window state decorations.
+
+Refreshed at every task state boundary (dispatch, step, iteration, status, hold, rung and usage
+change). The window's `@shk_state_color`/`@shk_state_glyph` mirror the task's own state — its
+acting role and step, or a hold/escalation override — distinct from `engine.decorations`, which
+mirrors a *session's* live activity on its own pane.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from shikiru.agents.contracts import COST_BASIS_API_EQUIVALENT, COST_BASIS_BILLED, Rung, Usage
+from shikiru.domain.ladder import pick_rung
+from shikiru.domain.levels import usage_level
+from shikiru.domain.runs import NO_USAGE, RunStatus, context_title, cost_title
+from shikiru.domain.steps import ACTING_ROLE
+from shikiru.domain.tasks import Hold, Role, Status, Step
+from shikiru.paths import run_dir
+from shikiru.ui.glyphs import (
+    GLYPH_CONSULT,
+    GLYPH_ENGINE,
+    GLYPH_ESCALATED,
+    GLYPH_OPERATOR,
+    GLYPH_PAUSED,
+    GLYPH_QUOTA,
+    QUOTA_MARKER,
+    ROLE_GLYPHS,
+    STAGE_IMPLEMENT,
+    STAGE_MERGE,
+    STAGE_PLAN,
+    STAGE_TRIAGE,
+    STAGE_VERIFY,
+)
+from shikiru.ui.tokens import (
+    ALERT_COLOR,
+    AMBER,
+    ENGINE_COLOR,
+    HOLD_COLOR,
+    OPERATOR_COLOR,
+    PRIMARY_TEXT_COLOR,
+    ROLE_COLORS,
+    SAGE,
+    SECONDARY_TEXT_COLOR,
+    USAGE_LEVEL_COLORS,
+)
+from shikiru.view_log import (
+    clear_quota_status,
+    quota_status_path,
+    write_quota_status,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from shikiru.config.settings import Settings
+    from shikiru.domain.runs import Run
+    from shikiru.domain.tasks import Task
+    from shikiru.engine.quota_waits import QuotaWaits, TaskQuotaWait
+    from shikiru.store.runs import RunStore
+    from shikiru.store.tasks import TaskStore
+    from shikiru.tmux.decorator import PaneDecorator
+
+_STEP_GLYPHS: dict[Step, str] = {
+    Step.TRIAGE: STAGE_TRIAGE,
+    Step.PLAN: STAGE_PLAN,
+    Step.IMPLEMENT: STAGE_IMPLEMENT,
+    Step.CONSULT: GLYPH_CONSULT,
+    Step.VERIFY: STAGE_VERIFY,
+    Step.INTEGRATE: STAGE_MERGE,
+}
+
+_TITLED_ROLES = (Role.LEADER, Role.IMPLEMENTER)
+
+
+def _quota_shown(task: Task) -> bool:
+    return (
+        Hold.PAUSED not in task.holds
+        and Hold.INTERVENTION not in task.holds
+        and task.status is not Status.ESCALATED
+    )
+
+
+def _window_state(task: Task, quota: TaskQuotaWait | None) -> tuple[str, str]:
+    if Hold.PAUSED in task.holds:
+        return HOLD_COLOR, GLYPH_PAUSED
+    if Hold.INTERVENTION in task.holds:
+        return OPERATOR_COLOR, GLYPH_OPERATOR
+    if task.status is Status.ESCALATED:
+        return ALERT_COLOR, GLYPH_ESCALATED
+    if quota is not None:
+        return AMBER, QUOTA_MARKER
+    if task.step is None:
+        return ENGINE_COLOR, GLYPH_ENGINE
+    return ROLE_COLORS[ACTING_ROLE[task.step]], _STEP_GLYPHS[task.step]
+
+
+def _pane_state(
+    task: Task, role: Role, *, taken_over: bool, quota_blocked: bool
+) -> tuple[str, str]:
+    if taken_over:
+        return OPERATOR_COLOR, GLYPH_OPERATOR
+    if Hold.PAUSED in task.holds:
+        return HOLD_COLOR, GLYPH_PAUSED
+    if quota_blocked:
+        return AMBER, GLYPH_QUOTA
+    return ROLE_COLORS[role], ROLE_GLYPHS[role]
+
+
+def _flag_parts(task: Task, *, taken_over: bool) -> list[tuple[str, str, str]]:
+    flags: list[tuple[str, str, str]] = []
+    if Hold.PAUSED in task.holds:
+        flags.append((GLYPH_PAUSED, "paused", HOLD_COLOR))
+    if taken_over or Hold.INTERVENTION in task.holds:
+        flags.append((GLYPH_OPERATOR, "operator", OPERATOR_COLOR))
+    if task.status is Status.ESCALATED:
+        flags.append((GLYPH_ESCALATED, "escalated", ALERT_COLOR))
+    return flags
+
+
+def _flags(task: Task, *, taken_over: bool = False, include_glyphs: bool = True) -> str:
+    flags = _flag_parts(task, taken_over=taken_over)
+    if include_glyphs:
+        return " ".join(f"{glyph} {word}" for glyph, word, _ in flags)
+    return " ".join(word for _, word, _ in flags)
+
+
+def _flag_segments(task: Task, *, taken_over: bool) -> tuple[tuple[str, str], ...]:
+    parts = _flag_parts(task, taken_over=taken_over)
+    segments: list[tuple[str, str]] = []
+    for index, (_, word, color) in enumerate(parts):
+        if index:
+            segments.append((" ", PRIMARY_TEXT_COLOR))
+        segments.append((word, color))
+    return tuple(segments)
+
+
+def _rung_label(rung: Rung) -> str:
+    effort = f"/{rung.effort}" if rung.effort is not None else ""
+    return f"{rung.agent}:{rung.model}{effort}"
+
+
+class TaskTitles:
+    """Sets `task`'s window/pane titles and window state from `dashboard.titles`.
+
+    A role's pane taken over by the Operator  is titled and coloured as the Operator's;
+    otherwise it shows the pause hold or the role's own colour and glyph.
+    """
+
+    def __init__(
+        self,
+        decorator: PaneDecorator,
+        runs: RunStore,
+        tasks: TaskStore,
+        settings: Settings,
+        *,
+        waits: QuotaWaits,
+        project_root: Path,
+    ) -> None:
+        """Decorate via `decorator` using current task rows, live run usage and quota `waits`.
+
+        Each role pane's quota status is published under `project_root`'s run directories for
+        the pane's view process.
+        """
+        self._decorator = decorator
+        self._runs = runs
+        self._tasks = tasks
+        self._settings = settings
+        self._waits = waits
+        self._project_root = project_root
+        self._refresh_lock = asyncio.Lock()
+        self._published: dict[str, TaskQuotaWait | None] = {}
+
+    async def sync_quota(self, task: Task) -> None:
+        """Refresh `task`'s decorations when its quota wait differs from the one last published."""
+        current = self._tasks.require(task.id)
+        if (
+            current.id not in self._published
+            or self._waits.resolve(current) != self._published[current.id]
+        ):
+            await self.refresh(current)
+
+    async def refresh(self, task: Task) -> None:
+        """Set titles from the latest task row, serializing title publications."""
+        async with self._refresh_lock:
+            current = self._tasks.require(task.id)
+            quota = self._waits.resolve(current)
+            self._published[current.id] = quota
+            if current.window_id is not None:
+                await self._refresh_window(current, current.window_id, quota)
+            for role in _TITLED_ROLES:
+                pane_id = current.panes.get(role)
+                if pane_id is not None:
+                    await self._refresh_pane(current, role, pane_id, quota)
+
+    async def _refresh_window(
+        self, task: Task, window_target: str, quota: TaskQuotaWait | None
+    ) -> None:
+        color, glyph = _window_state(task, quota)
+        fields = {"task_id": task.id, "title": task.title}
+        await self._decorator.refresh_window(
+            window_target,
+            self._settings.dashboard.titles.window,
+            fields,
+            color=color,
+            glyph=glyph,
+        )
+
+    async def _refresh_pane(
+        self, task: Task, role: Role, pane_id: str, quota: TaskQuotaWait | None
+    ) -> None:
+        configured_rung = pick_rung(task, role, self._settings)
+        run = self._active_run(task.id, role)
+        taken_over = run is not None and run.status is RunStatus.TAKEN_OVER
+        effective_rung = (
+            Rung(agent=run.agent, model=run.model, effort=run.effort)
+            if run is not None
+            else configured_rung
+        )
+        pending_rung = (
+            f" · next {_rung_label(configured_rung)}" if effective_rung != configured_rung else ""
+        )
+        usage = run.usage if run is not None else NO_USAGE
+        usage_reported = run.usage_reported if run is not None else None
+        template = getattr(self._settings.dashboard.titles, role.value)
+        fields = {
+            "task_id": task.id,
+            "title": task.title,
+            "project": self._settings.project.name,
+            "role": role.value,
+            "role_label": role.value.capitalize(),
+            "glyph": GLYPH_OPERATOR if taken_over else ROLE_GLYPHS[role],
+            "agent": effective_rung.agent,
+            "model": effective_rung.model,
+            "effort": effective_rung.effort if effective_rung.effort is not None else "",
+            "pending_rung": pending_rung,
+            "iteration": task.iteration,
+            "step": task.step.value if task.step is not None else "",
+            "status": task.status.value,
+            "context": context_title(usage),
+            "cost": cost_title(usage),
+            "flags": _flags(task),
+            "flags_text": _flags(task, taken_over=taken_over, include_glyphs=False),
+        }
+        cost_color = SECONDARY_TEXT_COLOR
+        if usage.cost_usd is not None and usage_reported is not False:
+            if usage.cost_basis == COST_BASIS_BILLED:
+                cost_color = SAGE
+            elif usage.cost_basis == COST_BASIS_API_EQUIVALENT:
+                cost_color = AMBER
+        await self._decorator.set_pane_title_styling(
+            pane_id,
+            template,
+            fields,
+            field_colors={
+                "role": ROLE_COLORS[role],
+                "role_label": ROLE_COLORS[role],
+                "agent": PRIMARY_TEXT_COLOR,
+                "model": PRIMARY_TEXT_COLOR,
+                "effort": SECONDARY_TEXT_COLOR,
+                "pending_rung": SECONDARY_TEXT_COLOR,
+                "iteration": SECONDARY_TEXT_COLOR,
+                "context": self._context_color(usage, usage_reported),
+                "cost": cost_color,
+            },
+            field_segments={"flags_text": _flag_segments(task, taken_over=taken_over)},
+        )
+        role_wait = (
+            quota.roles.get(role)
+            if quota is not None and not taken_over and _quota_shown(task)
+            else None
+        )
+        color, glyph = _pane_state(
+            task, role, taken_over=taken_over, quota_blocked=role_wait is not None
+        )
+        await self._decorator.set_pane_state(pane_id, color=color, glyph=glyph)
+        status_path = quota_status_path(run_dir(self._project_root, task.id), role.value)
+        if role_wait is None:
+            clear_quota_status(status_path)
+        else:
+            write_quota_status(status_path, role_wait.action, role_wait.at)
+
+    def _context_color(self, usage: Usage, usage_reported: bool | None) -> str:
+        if usage.context_used_pct is None or usage_reported is False:
+            return SECONDARY_TEXT_COLOR
+        titles = self._settings.dashboard.titles
+        level = usage_level(
+            usage.context_used_pct,
+            warn_pct=titles.context_warn_pct,
+            alert_pct=titles.context_alert_pct,
+        )
+        return USAGE_LEVEL_COLORS[level]
+
+    def _active_run(self, task_id: str, role: Role) -> Run | None:
+        live = self._runs.get_live(task_id, role)
+        return live if live is not None else self._runs.get_taken_over(task_id, role)

shikiru/engine/transitions.py

@@ -0,0 +1,79 @@
+"""Persists domain transitions of a task and projects them into events."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.domain.events import EventKind
+from shikiru.domain.reports import PlanReport, Verdict
+from shikiru.domain.tasks import Status, TaskOrigin
+from shikiru.engine.events import emit_step_started
+from shikiru.errors import InvariantError
+
+if TYPE_CHECKING:
+    from shikiru.config.settings import Settings
+    from shikiru.domain.steps import Outcome, Transition
+    from shikiru.domain.tasks import Task
+    from shikiru.engine.titles import TaskTitles
+    from shikiru.store.events import EventLog
+    from shikiru.store.tasks import TaskStore
+
+
+class TransitionWriter:
+    """The single place a `Transition` becomes stored task state, events and a refreshed title."""
+
+    def __init__(
+        self, *, tasks: TaskStore, events: EventLog, titles: TaskTitles, settings: Settings
+    ) -> None:
+        """Write transitions to `tasks`, record their events and refresh titles."""
+        self._tasks = tasks
+        self._events = events
+        self._titles = titles
+        self._settings = settings
+
+    async def apply(self, task: Task, transition: Transition, outcome: Outcome | None) -> Task:
+        """Apply a task transition and refresh its visible title."""
+        updated = self.persist(task, transition, outcome)
+        await self._titles.refresh(updated)
+        return updated
+
+    def persist(self, task: Task, transition: Transition, outcome: Outcome | None) -> Task:
+        """Write a task transition, emitting its step event, and return the stored task."""
+        if transition.enqueue_new_tasks:
+            if outcome is None:
+                message = f"{task.id}'s transition enqueues new tasks but has no outcome"
+                raise InvariantError(message)
+            self._apply_new_tasks(task, transition, outcome)
+        else:
+            self._tasks.apply_transition(task.id, transition)
+            if transition.status in (Status.DONE, Status.CANCELLED):
+                self._tasks.set_slot(task.id, None)
+            if transition.status is Status.ESCALATED:
+                self._tasks.set_wait_reason(task.id, None)
+        updated = self._tasks.require(task.id)
+        if (
+            task.step != updated.step
+            and updated.step is not None
+            and updated.status in (Status.RUNNING, Status.INTEGRATING)
+        ):
+            emit_step_started(self._events, updated, self._settings)
+        return updated
+
+    def _apply_new_tasks(self, task: Task, transition: Transition, outcome: Outcome) -> None:
+        if not isinstance(outcome, PlanReport | Verdict):
+            message = f"{task.id}'s transition enqueues new tasks from a {type(outcome).__name__}"
+            raise InvariantError(message)
+        children = self._tasks.apply_scope_change(
+            task.id, transition, outcome.new_tasks, origin=TaskOrigin.LEADER
+        )
+        if not outcome.new_tasks and not outcome.scope_changes:
+            return
+        self._events.append(
+            EventKind.SCOPE_CHANGE,
+            task_id=task.id,
+            message=f"{task.id} scope changed: {len(children)} new task(s)",
+            data={
+                "new_task_ids": [child.id for child in children],
+                "scope_changes": list(outcome.scope_changes),
+            },
+        )

shikiru/engine/turn_context.py

@@ -0,0 +1,206 @@
+"""Prompt-context preparation for a task's next turn."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from shikiru.domain.reports import FeedbackAction, ReportKind
+from shikiru.domain.tasks import Step
+from shikiru.engine.task_facts import require_repo
+from shikiru.engine.turns import TurnRequest
+from shikiru.errors import InvariantError
+from shikiru.paths import task_root
+from shikiru.prompts.renderer import PromptName
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from shikiru.config.settings import Settings
+    from shikiru.domain.feedback import FeedbackInput
+    from shikiru.domain.tasks import Task
+    from shikiru.engine.history import ReportHistory
+    from shikiru.engine.task_facts import TaskFacts
+    from shikiru.store.escalations import EscalationStore
+
+
+@dataclass(frozen=True)
+class NextTurn:
+    """How recovery wants the next turn started: as a handoff or as a continuation."""
+
+    handoff: bool = False
+    continue_turn: bool = False
+
+
+ORDINARY_TURN = NextTurn()
+
+_JSON_INDENT = 2
+
+FEEDBACK_TEMPLATES = frozenset(
+    {PromptName.FEEDBACK_ANALYSIS, PromptName.FEEDBACK_REWORK, PromptName.FEEDBACK_VERIFY}
+)
+
+
+class ContextKey(StrEnum):
+    """The variables the prompt templates read from a turn's context."""
+
+    REQUEST = "request"
+    TASK_ID = "task_id"
+    WORKSPACE = "workspace"
+    TRACKERS = "trackers"
+    REPORTS = "reports"
+    QUESTION = "question"
+    OPERATOR_DECISION = "operator_decision"
+    FACTS = "facts"
+    BASE = "base"
+    FINAL_ROUND = "final_round"
+    CONFLICT = "conflict"
+    MODE = "mode"
+    FEEDBACK_SNAPSHOT = "feedback_snapshot"
+    FEEDBACK_ANALYSIS = "feedback_analysis"
+    FEEDBACK_WORK = "feedback_work"
+
+
+def template_for_step(step: Step, iteration: int) -> tuple[PromptName, ReportKind]:
+    """Return the prompt template and report kind of `step`'s ordinary turn."""
+    if step is Step.TRIAGE:
+        return PromptName.TRIAGE, ReportKind.TRIAGE
+    if step is Step.PLAN:
+        return PromptName.PLAN, ReportKind.PLAN
+    if step is Step.IMPLEMENT:
+        template = PromptName.IMPLEMENT if iteration <= 1 else PromptName.REWORK
+        return template, ReportKind.IMPLEMENTATION
+    if step is Step.CONSULT:
+        return PromptName.CONSULT, ReportKind.CONSULT
+    if step is Step.VERIFY:
+        return PromptName.VERIFY, ReportKind.VERDICT
+    if step is Step.INTEGRATE:
+        return PromptName.CONFLICTS, ReportKind.IMPLEMENTATION
+    message = f"No turn template exists for step {step!r}"
+    raise InvariantError(message)
+
+
+class TurnContextPreparer:
+    """Builds each turn's `TurnRequest`."""
+
+    def __init__(
+        self,
+        *,
+        history: ReportHistory,
+        escalation_store: EscalationStore,
+        facts: TaskFacts,
+        settings: Settings,
+        project_root: Path,
+    ) -> None:
+        """Prepare contexts from report history, operator answers and workspace facts."""
+        self._history = history
+        self._escalation_store = escalation_store
+        self._facts = facts
+        self._settings = settings
+        self._project_root = project_root
+
+    async def prepare(
+        self,
+        task: Task,
+        step: Step,
+        *,
+        session_handoff: bool,
+        next_turn: NextTurn = ORDINARY_TURN,
+        template_override: PromptName | None = None,
+        kind_override: ReportKind | None = None,
+        conflict_context: str | None = None,
+        feedback: FeedbackInput | None = None,
+    ) -> TurnRequest:
+        """Build the request of `task`'s next `step` turn."""
+        history = self._history.load(task.id)
+        continue_turn = next_turn.continue_turn
+        if continue_turn:
+            template_override = PromptName.CONTINUE
+        template, kind = template_for_step(step, task.iteration)
+        if template_override is not None:
+            template = template_override
+        if kind_override is not None:
+            kind = kind_override
+        context: dict[str, object] = {
+            ContextKey.REQUEST: task.request,
+            ContextKey.TASK_ID: task.id,
+            ContextKey.WORKSPACE: str(task_root(self._project_root, task.id)),
+            ContextKey.TRACKERS: list(self._settings.project.trackers),
+            ContextKey.REPORTS: self._history.context(history),
+        }
+        if template is PromptName.CONSULT:
+            context[ContextKey.QUESTION] = self._history.latest_question(history)
+            context[ContextKey.OPERATOR_DECISION] = (
+                self._escalation_store.latest_answer(task.id)
+                if task.counters.consults == 0
+                else None
+            )
+        fresh = session_handoff and not continue_turn
+        handoff = (fresh and bool(history)) or next_turn.handoff
+        needs_facts = (
+            template in (PromptName.VERIFY, PromptName.CONFLICTS, *FEEDBACK_TEMPLATES) or handoff
+        )
+        facts_text = await self._facts.text(task) if needs_facts else ""
+        if handoff and template not in FEEDBACK_TEMPLATES:
+            template = PromptName.HANDOFF
+        if needs_facts:
+            context[ContextKey.FACTS] = facts_text
+        if template in FEEDBACK_TEMPLATES:
+            context.update(self._feedback_context(task, template, feedback))
+        if template is PromptName.VERIFY:
+            context[ContextKey.BASE] = require_repo(task).base_ref
+            context[ContextKey.FINAL_ROUND] = (
+                task.iteration >= self._settings.orchestration.max_iterations
+            )
+        if template is PromptName.CONFLICTS:
+            context[ContextKey.CONFLICT] = conflict_context or ""
+        return TurnRequest(
+            step=step,
+            iteration=task.iteration,
+            kind=kind,
+            template=template,
+            context=context,
+            facts=facts_text,
+            feedback=feedback,
+        )
+
+    @staticmethod
+    def _feedback_context(
+        task: Task, template: PromptName, feedback: FeedbackInput | None
+    ) -> dict[str, object]:
+        if feedback is None:
+            message = f"{task.id} {template.value} turn has no feedback to work from"
+            raise InvariantError(message)
+        context: dict[str, object] = {
+            ContextKey.MODE: task.mode.value if task.mode is not None else ""
+        }
+        if template is PromptName.FEEDBACK_ANALYSIS:
+            context[ContextKey.FEEDBACK_SNAPSHOT] = feedback.snapshot.model_dump_json(
+                indent=_JSON_INDENT
+            )
+            return context
+        analysis = feedback.analysis
+        if analysis is None:
+            message = f"{task.id} {template.value} turn has no analysis to work from"
+            raise InvariantError(message)
+        if template is PromptName.FEEDBACK_REWORK:
+            addressed = {
+                decision.source_id
+                for decision in analysis.decisions
+                if decision.action is FeedbackAction.ADDRESS
+            }
+            context[ContextKey.FEEDBACK_SNAPSHOT] = feedback.snapshot.only(
+                addressed
+            ).model_dump_json(indent=_JSON_INDENT)
+            context[ContextKey.FEEDBACK_WORK] = [
+                work.model_dump_json(indent=_JSON_INDENT) for work in analysis.work
+            ]
+            return context
+        context[ContextKey.BASE] = require_repo(task).base_ref
+        context[ContextKey.FINAL_ROUND] = feedback.final_round
+        context[ContextKey.FEEDBACK_SNAPSHOT] = feedback.snapshot.model_dump_json(
+            indent=_JSON_INDENT
+        )
+        context[ContextKey.FEEDBACK_ANALYSIS] = analysis.model_dump_json(indent=_JSON_INDENT)
+        return context

shikiru/engine/turn_execution.py

@@ -0,0 +1,30 @@
+"""The outcome of one executed agent turn, as the flow and its collaborators pass it around."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from shikiru.agents.contracts import Rung, Usage
+    from shikiru.domain.recovery import TurnResult
+    from shikiru.domain.reports import ReportKind
+    from shikiru.domain.tasks import Role
+
+
+@dataclass
+class TurnExecution:
+    """A turn's result with the role, rung, directory and usage it ran with."""
+
+    result: TurnResult
+    task_id: str
+    role: Role
+    turn_dir: Path
+    rung: Rung
+    run_id: int
+    usage_before: Usage
+    usage_after: Usage
+    kind: ReportKind
+    quota_wait_exhausted: bool = False