ww-agentic-workflows 1.0.0.dev3__py3-none-any.whl

ww/hooks/notices.py

@@ -0,0 +1,206 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The few lines agent hooks and task commands show about open work.
+
+Whatever a session-start hook prints stays in the agent's context for the
+rest of the session, so every text here is short and plain: no headings,
+one line per task, and a cap on how many tasks are listed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ww.executable import ww_command
+from ww.open_work import OpenTask, UnreadableTask
+
+from .records import Interruption
+
+SESSION_TASK_LIMIT = 5
+STOP_TASK_LIMIT = 3
+
+_OPERATOR_REASONS = {
+    "handler_failed": "an automatic handler failed",
+    "work_failed": "the work failed",
+    "child_failed": "a child task failed",
+    "handler_interrupted": "a command was interrupted",
+    "loop_limit": "a loop reached its limit",
+    "fix_limit": "a step's checks kept failing",
+    "check_disputed": "a worker disputed a check",
+    "value_unavailable": "a step's template value is not available yet",
+    "pass_incomplete": "an items pass left items without their recorded outcome",
+}
+
+
+def session_context(
+    open_tasks: tuple[OpenTask, ...],
+    interruptions: dict[str, Interruption],
+    root: Path,
+    *,
+    compacted: bool,
+    unreadable: tuple[UnreadableTask, ...] = (),
+    on_request: bool = False,
+    skipped: int = 0,
+) -> str:
+    """What a session learns about ww when it starts, resumes, or compacts.
+
+    ``open_tasks`` are the recent unfinished tasks; ``skipped`` counts the
+    tasks the scan left unread as older, which ``discover`` still covers.
+    A step in progress without an interruption marker ended with no hook
+    run, so it gets a notice of its own, except after a compaction: the
+    session that holds it is the one carrying on.
+    """
+    ww = ww_command()
+    lines = []
+    if compacted:
+        lines.append("Context was compacted; ww's task state is authoritative.")
+    lines.append(
+        "This project has ww available on request only: use it only when the "
+        "user explicitly asks for ww; otherwise work without it and do not "
+        f"ask. `{ww} discover` lists its workflows."
+        if on_request
+        else f"This project coordinates work through ww: `{ww} discover` lists "
+        "its workflows."
+    )
+    if open_tasks:
+        lines.append("Unfinished ww tasks, newest first:")
+        for task in open_tasks[:SESSION_TASK_LIMIT]:
+            lines.append(task_line(task, root, ww))
+            interruption = interruptions.get(task.task_id)
+            if interruption is not None:
+                lines.append("  " + interruption_notice(interruption, task.task_id))
+            elif task.agent_step_in_progress and not compacted:
+                lines.append("  " + abrupt_end_notice(task))
+        if len(open_tasks) > SESSION_TASK_LIMIT:
+            lines.append(
+                f"… and {len(open_tasks) - SESSION_TASK_LIMIT} more; "
+                f"`{ww} status <task-id>` shows one."
+            )
+    if open_tasks or skipped:
+        lines.append(f"`{ww} discover` lists every unfinished task.")
+    if unreadable:
+        lines.append(unreadable_notice(unreadable))
+    return "\n".join(lines) + "\n"
+
+
+def unreadable_notice(unreadable: tuple[UnreadableTask, ...]) -> str:
+    """One line naming the tasks ww cannot read, without their errors."""
+    names = ", ".join(task.task_id for task in unreadable)
+    return (
+        f"ww cannot read the state of {names}; other tasks and new work are "
+        f"unaffected. `{ww_command()} discover` shows why; ask the operator "
+        "before touching them."
+    )
+
+
+def task_line(task: OpenTask, root: Path, ww: str) -> str:
+    """One unfinished task with its step, state, workspace and resume commands."""
+    step = task.label
+    if task.operator_reason is not None:
+        state = "awaiting the operator: " + _OPERATOR_REASONS.get(
+            task.operator_reason, task.operator_reason
+        )
+    else:
+        state = (task.item_status or task.run_status).replace("_", " ")
+    parts = [f"- {task.task_id} ({task.workflow}, {task.agent}) {step}: {state}"]
+    parts.append(f"in {display_workspace(task.workspace, root)}")
+    parts.append(f"resume: `{ww} instruction {task.task_id} --role manager`")
+    if task.agent_step_in_progress and task.run_id:
+        parts.append(
+            f"worker: `{ww} instruction {task.task_id} --run {task.run_id} "
+            "--role worker`"
+        )
+    return " · ".join(parts)
+
+
+def stop_reminder(tasks: tuple[OpenTask, ...]) -> str:
+    """Ask, once, that the open step be closed before the agent stops."""
+    ww = ww_command()
+    listed = tasks[:STOP_TASK_LIMIT]
+    names = "; ".join(f"{task.task_id} step `{task.label}`" for task in listed)
+    example = listed[0].task_id
+    return (
+        f"ww: {names} is still in progress. If the work is done, record it with "
+        f"`{ww} complete {example} --role worker ...` as its instruction shows; if "
+        f"it cannot finish, run `{ww} fail {example} --role worker "
+        f'--error "<reason>"`. '
+        "A manager waiting on a worker, or a deliberate pause, may simply stop "
+        "again: ww reminds only once."
+    )
+
+
+def interruption_notice(interruption: Interruption, task_id: str) -> str:
+    """Tell whoever picks the task up that its last session stopped short."""
+    ww = ww_command()
+    who = interruption.agent + (
+        f", {interruption.reason}" if interruption.reason else ""
+    )
+    step = interruption.step or interruption.item_name or "its step"
+    if interruption.in_conversation:
+        lead = (
+            f"Interrupted: the previous session ({who}) stopped at {interruption.at} "
+            f"while `{step}` (attempt {interruption.attempt}) was talking with the "
+            "operator. "
+        )
+        if interruption.recovered_entries:
+            return lead + (
+                f"{interruption.recovered_entries} entries of the conversation "
+                "were recovered from the session transcript; read them on the "
+                "step's page and continue from the last unanswered point."
+            )
+        return lead + (
+            "The conversation was not recorded; ask the operator where you were."
+        )
+    return (
+        f"Interrupted: the previous session ({who}) stopped at {interruption.at} "
+        f"during `{step}` (attempt {interruption.attempt}). Before continuing, check "
+        "`git status` in the task workspace, review the diff and ww's recorded "
+        f"commits (`{ww} extension ww/git commits {task_id}`), and compare them "
+        "with the step's requirements; then complete, continue, or fail the step."
+    )
+
+
+def abrupt_end_notice(task: OpenTask) -> str:
+    """Tell whoever picks the task up that its last session left no trace.
+
+    The ``interrupt`` hook never runs when a tab is closed, the agent crashes
+    or is killed, so the step is still in progress with no marker.
+    """
+    lead = (
+        f"Left in progress at {task.updated_at} by {task.agent} with no recorded "
+        "end, probably a closed session: "
+    )
+    if task.in_conversation:
+        return (
+            lead + "the step's page shows the conversation so far; pick it up at "
+            "the last unanswered question."
+        )
+    return (
+        lead + f"check its page (`{ww_command()} instruction {task.task_id} "
+        "--role manager`) before continuing."
+    )
+
+
+def display_workspace(path: Path, root: Path) -> str:
+    """A workspace relative to the root, or "the root" itself."""
+    try:
+        relative = path.relative_to(root.resolve())
+    except ValueError:
+        return str(path)
+    return str(relative) if relative.parts else "the root"
+
+
+def recent_interruptions_pointer(count: int, days: int) -> str | None:
+    """One line for ``discover`` and ``lookup``, only when there is news.
+
+    Those entry commands are what an agent without hooks runs first, so the
+    line is the whole of their "first start" check; the details live in
+    ``ww interrupted`` and on each task's own commands.
+    """
+    if not count:
+        return None
+    tasks = "task was" if count == 1 else "tasks were"
+    window = "day" if days == 1 else f"{days} days"
+    return (
+        f"{count} {tasks} interrupted in the last {window}; "
+        f"run `{ww_command()} interrupted` before starting new work."
+    )

ww/hooks/records.py

@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The two small per-task records agent hooks keep beside the interaction log.
+
+``interrupted.json`` marks a task whose agent session ended, or was
+interrupted, while one of its agent-owned steps was in progress.  It holds
+one record, overwritten by the next interruption, and is cleared once that
+step's attempt completes or fails, never merely because a notice showed it:
+a compaction or a new session between showing and acting must not lose it.
+
+``stop-reminders.json`` lists the step attempts ww already reminded an agent
+about when it stopped, so the reminder is given once and the next stop is
+always allowed.
+
+Both belong to the task and are forgotten when the task is reset.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from ww.errors import StateError
+from ww.storage import Storage
+from ww.storage_adapters import TaskStorageAdapter
+
+INTERRUPTED_FILE = "interrupted.json"
+REMINDERS_FILE = "stop-reminders.json"
+
+
+@dataclass(frozen=True)
+class Interruption:
+    """What a session was doing when it stopped short."""
+
+    at: str
+    run_id: str | None
+    step: str | None
+    item_id: str
+    # ``step`` is how messages name the work, a hook as "<name> (a hook of
+    # <step>)"; ``item_name`` is the plan item's own name.
+    item_name: str | None
+    attempt: int
+    agent: str
+    # The agent's own word for why the session ended, when it gives one.
+    reason: str | None = None
+    # The step was talking with the operator when the session ended.
+    in_conversation: bool = False
+    # How many entries of that conversation the hook recovered from the
+    # session's transcript into the interaction record.
+    recovered_entries: int = 0
+
+    @property
+    def moment(self) -> datetime | None:
+        try:
+            return datetime.fromisoformat(self.at.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+class HookRecords:
+    """Read and write the hook records of the tasks in one project root."""
+
+    def __init__(self, storage: Storage, tasks: TaskStorageAdapter) -> None:
+        self.storage = storage
+        self.tasks = tasks
+
+    def _directory(self, task_id: str) -> Path:
+        return self.storage.runtime_path / "tasks" / task_id
+
+    # Interruptions
+
+    def mark_interrupted(self, task_id: str, record: Interruption) -> None:
+        path = self._directory(task_id) / INTERRUPTED_FILE
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.storage.locks.atomic_write(
+            path, json.dumps(record.to_dict(), indent=2) + "\n"
+        )
+
+    def interruption(self, task_id: str) -> Interruption | None:
+        """The task's interruption, or ``None`` once its attempt has ended.
+
+        A record whose attempt completed or failed, or was superseded by a
+        later attempt, is removed here: this is the one place that decides
+        whether the notice still applies.
+        """
+        path = self._directory(task_id) / INTERRUPTED_FILE
+        record = _read_interruption(path)
+        if record is None:
+            return None
+        if self._attempt_ended(task_id, record):
+            path.unlink(missing_ok=True)
+            return None
+        return record
+
+    def interruptions(self) -> tuple[tuple[str, Interruption], ...]:
+        """Every task still marked as interrupted, newest first."""
+        root = self.storage.runtime_path / "tasks"
+        if not root.is_dir():
+            return ()
+        found = []
+        for path in root.rglob(INTERRUPTED_FILE):
+            task_id = path.parent.relative_to(root).as_posix()
+            try:
+                record = self.interruption(task_id)
+            except StateError:
+                # open_work() reports the unreadable task; skip it here.
+                continue
+            if record is not None:
+                found.append((task_id, record))
+        return tuple(sorted(found, key=lambda entry: entry[1].at, reverse=True))
+
+    def recent(self, days: int) -> tuple[tuple[str, Interruption], ...]:
+        """The interruptions of the last ``days`` days, newest first."""
+        horizon = datetime.now(timezone.utc) - timedelta(days=days)
+        return tuple(
+            (task_id, record)
+            for task_id, record in self.interruptions()
+            if record.moment is not None and record.moment >= horizon
+        )
+
+    def _attempt_ended(self, task_id: str, record: Interruption) -> bool:
+        runs, _, _ = self.tasks.read_task_record(task_id)
+        run = next((run for run in runs if run.run_id == record.run_id), None)
+        if run is None:
+            return False
+        execution = next(
+            (
+                entry
+                for entry in run.state.item_executions
+                if entry.plan_item_id == record.item_id
+            ),
+            None,
+        )
+        if execution is None:
+            return False
+        return execution.status in {"completed", "failed"} or (
+            execution.attempts > record.attempt
+        )
+
+    # Stop reminders
+
+    def claim_reminder(self, task_id: str, key: str) -> bool:
+        """Record the reminder for ``key``; ``False`` when it was already given.
+
+        Agents may run the same hook twice at once (Claude Code runs matching
+        hooks in parallel), so checking and recording happen under one lock of
+        their own: exactly one call reminds. It is not the task lock, which a
+        long-running command may hold for minutes.
+        """
+        path = self._directory(task_id) / REMINDERS_FILE
+        with self.storage.locks.lock(path, purpose="stop reminders"):
+            keys = self._reminders(task_id)
+            if key in keys:
+                return False
+            path.parent.mkdir(parents=True, exist_ok=True)
+            self.storage.locks.atomic_write(
+                path, json.dumps([*keys, key], indent=2) + "\n"
+            )
+        return True
+
+    def _reminders(self, task_id: str) -> list[str]:
+        path = self._directory(task_id) / REMINDERS_FILE
+        try:
+            value = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return []
+        return (
+            [entry for entry in value if isinstance(entry, str)]
+            if isinstance(value, list)
+            else []
+        )
+
+    def remove(self, task_id: str) -> None:
+        """Forget both records, as part of resetting the task."""
+        for name in (INTERRUPTED_FILE, REMINDERS_FILE):
+            (self._directory(task_id) / name).unlink(missing_ok=True)
+
+
+def reminder_key(run_id: str | None, item_id: str, attempt: int) -> str:
+    """One step attempt, which ww reminds an agent about at most once."""
+    return f"{run_id or '-'}:{item_id}:{attempt}"
+
+
+def _read_interruption(path: Path) -> Interruption | None:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(value, dict):
+        return None
+    try:
+        return Interruption(
+            at=str(value["at"]),
+            run_id=value.get("run_id"),
+            step=value.get("step"),
+            item_id=str(value["item_id"]),
+            item_name=value.get("item_name"),
+            attempt=int(value.get("attempt", 0)),
+            agent=str(value.get("agent", "")),
+            reason=value.get("reason"),
+            in_conversation=bool(value.get("in_conversation", False)),
+            recovered_entries=int(value.get("recovered_entries", 0)),
+        )
+    except (KeyError, TypeError, ValueError):
+        return None

ww/hooks/runtime.py

@@ -0,0 +1,266 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""What ww answers when an agent calls one of its hooks.
+
+The hooks are gentle by design: they add a few lines of context or remind
+once, and nothing is ever blocked.
+
+- ``session-start`` prints a reminder that ww coordinates work here, and the
+  recently updated unfinished tasks with the commands that resume them,
+  unless ``agent_hooks.check_unfinished`` switches that scan off.
+- ``stop`` asks the agent, once per step attempt, to record an agent-owned
+  step that is still in progress; the next stop is always allowed.
+- ``interrupt`` records, without answering, that a session ended while such
+  a step was in progress, so the next session is told to check the work.
+  When the step was talking with the operator, it first recovers what the
+  two sides said from the session's transcript into the interaction record.
+
+An adapter reads the agent's payload and renders the answer; everything else
+is decided here, from persisted state alone.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, replace
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from ww.config_files import WORKFLOWS_FILE
+from ww.interactions import RECOVERED, InteractionLog
+from ww.open_work import OpenTask, open_work, tasks_for_session
+from ww.project_config import AgentHooks
+from ww.storage import Storage
+
+from .agents import HookAgent, HookEvent, HookPayload
+from .notices import session_context, stop_reminder
+from .records import HookRecords, Interruption, reminder_key
+from .transcripts import recover_conversation
+
+
+@dataclass(frozen=True)
+class HookAnswer:
+    """What the hook prints, and a word for the audit log about why."""
+
+    text: str
+    decision: str
+
+
+ALLOW = HookAnswer("", "allowed")
+
+
+def answer_hook(
+    storage: Storage,
+    agent: HookAgent,
+    event: HookEvent,
+    raw_payload: str,
+    *,
+    settings: AgentHooks,
+    on_request: bool = False,
+) -> HookAnswer:
+    """ww's answer to one hook call; the caller contains every error.
+
+    ``on_request`` is the project's ``"enabled": "on_request"``: the session
+    is told that ww is used only when the user asks for it. Stop reminders
+    are unchanged, since they concern tasks already open. ``settings`` is
+    the project's ``agent_hooks``, which only ``session-start`` reads.
+    """
+    payload = agent.parse(event, _payload(raw_payload))
+    records = HookRecords(storage, storage.task_persistence)
+    if event == "session-start":
+        return _session_start(
+            storage, agent, payload, records, settings, on_request=on_request
+        )
+    # An unreadable task has no step anyone can close, so stop and interrupt
+    # consider only the tasks that could be read.
+    tasks = open_work(storage.task_persistence, storage.root).tasks
+    if event == "stop" and not payload.interrupted:
+        return _stop(agent, payload, records, tasks)
+    return _interrupt(agent, payload, records, tasks)
+
+
+def _session_start(
+    storage: Storage,
+    agent: HookAgent,
+    payload: HookPayload,
+    records: HookRecords,
+    settings: AgentHooks,
+    *,
+    on_request: bool,
+) -> HookAnswer:
+    if not payload.wants_context:
+        return HookAnswer("", "no context needed")
+    compacted = payload.source == "compact"
+    if not settings.check_unfinished:
+        text = session_context(
+            (), {}, storage.root, compacted=compacted, on_request=on_request
+        )
+        return HookAnswer(
+            agent.context_reply(text.rstrip("\n")) + "\n",
+            "context without the unfinished-task scan",
+        )
+    horizon = datetime.now(timezone.utc) - timedelta(days=settings.recent_days)
+    work = open_work(storage.task_persistence, storage.root, since=horizon)
+    interruptions = {
+        task.task_id: record
+        for task in work.tasks
+        if (record := records.interruption(task.task_id)) is not None
+    }
+    text = session_context(
+        work.tasks,
+        interruptions,
+        storage.root,
+        compacted=compacted,
+        unreadable=work.unreadable,
+        on_request=on_request,
+        skipped=work.skipped,
+    )
+    return HookAnswer(
+        agent.context_reply(text.rstrip("\n")) + "\n",
+        f"context with {len(work.tasks)} unfinished task(s)",
+    )
+
+
+def _stop(
+    agent: HookAgent,
+    payload: HookPayload,
+    records: HookRecords,
+    tasks: tuple[OpenTask, ...],
+) -> HookAnswer:
+    if payload.continued:
+        return replace(ALLOW, decision="allowed: the agent already continued once")
+    # A manager waiting on a worker is not the one to close the step: its own
+    # stop skips delegated steps, and the worker's stop reminds instead. A
+    # step in conversation with the operator stops to hear them.
+    if not payload.from_worker and any(
+        task.waiting_on_another(tasks)
+        for task in tasks_for_session(
+            tasks, records.storage.root, payload.directory, agent.name
+        )
+    ):
+        return replace(
+            ALLOW, decision="allowed: the manager is waiting on a child or worker"
+        )
+    working = tasks_for_session(
+        tuple(
+            task
+            for task in tasks
+            if task.agent_step_in_progress
+            and not task.in_conversation
+            and (payload.from_worker or not task.delegated)
+        ),
+        records.storage.root,
+        payload.directory,
+        agent.name,
+    )
+    pending = tuple(
+        task
+        for task in working
+        if task.item_id is not None and records.claim_reminder(task.task_id, _key(task))
+    )
+    if not pending:
+        return ALLOW
+    return HookAnswer(
+        agent.continue_reply(stop_reminder(pending)) + "\n",
+        "reminded: " + ", ".join(task.task_id for task in pending),
+    )
+
+
+def _interrupt(
+    agent: HookAgent,
+    payload: HookPayload,
+    records: HookRecords,
+    tasks: tuple[OpenTask, ...],
+) -> HookAnswer:
+    working = tasks_for_session(
+        tuple(task for task in tasks if task.agent_step_in_progress),
+        records.storage.root,
+        payload.directory,
+        agent.name,
+    )
+    if not working:
+        return HookAnswer("", "no step in progress to mark")
+    at = (
+        datetime.now(timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+    for task in working:
+        assert task.item_id is not None
+        recovered = (
+            _recover(agent, payload, records.storage, task, at)
+            if task.in_conversation
+            else 0
+        )
+        records.mark_interrupted(
+            task.task_id,
+            Interruption(
+                at=at,
+                run_id=task.run_id,
+                step=task.label,
+                item_id=task.item_id,
+                item_name=task.item_name,
+                attempt=task.attempt,
+                agent=agent.name,
+                reason=payload.reason,
+                in_conversation=task.in_conversation,
+                recovered_entries=recovered,
+            ),
+        )
+    return HookAnswer(
+        "", "marked interrupted: " + ", ".join(task.task_id for task in working)
+    )
+
+
+def _recover(
+    agent: HookAgent,
+    payload: HookPayload,
+    storage: Storage,
+    task: OpenTask,
+    at: str,
+) -> int:
+    """Append the conversation the session's transcript holds; its size.
+
+    Only what was said since the step's attempt started is taken.  The
+    task lock is not taken: the session that held the conversation is the
+    one ending, and the hook has seconds, not minutes.  Any failure
+    recovers nothing, so the hook never fails over it.
+    """
+    if payload.transcript_path is None:
+        return 0
+    try:
+        since = datetime.fromisoformat(
+            (task.started_at or task.updated_at).replace("Z", "+00:00")
+        )
+        entries = list(recover_conversation(agent.name, payload.transcript_path, since))
+        if entries and entries[-1][0] != "agent" and payload.last_agent_message:
+            entries.append(("agent", payload.last_agent_message.strip()))
+        InteractionLog(storage).append_entries(
+            task.task_id,
+            [(speaker + RECOVERED, text) for speaker, text in entries],
+            run_id=task.run_id,
+            step=task.item_name or task.label,
+            item_id=task.work_item_id,
+            at=at,
+        )
+    except Exception:  # noqa: BLE001 - a hook must never fail over recovery
+        return 0
+    return len(entries)
+
+
+def _key(task: OpenTask) -> str:
+    assert task.item_id is not None
+    return reminder_key(task.run_id, task.item_id, task.attempt)
+
+
+def _payload(raw: str) -> dict[str, object]:
+    try:
+        value = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def is_project_root(root: Path) -> bool:
+    """Only a directory holding the repo workflow file is a ww root."""
+    return (root / WORKFLOWS_FILE).is_file()