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

ww/run_coordination.py

@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Atomic run loading and publication across storage adapters."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ww.children import ChildTask
+from ww.contracts import run_is_open
+from ww.errors import StateError
+from ww.execution_models import ExecutionState, PlanSnapshot, TaskRunAggregate
+from ww.instructions import Instruction
+from ww.items import WorkItem
+from ww.storage_adapters import TaskStorageAdapter
+
+
+class RunLifecycle(Protocol):
+    """The run operations the workflow service lends to its coordinators.
+
+    Coordinators (recovery, children) decide *what* a transition means; the
+    service keeps ownership of locks, commits, draining, and rendering.
+    """
+
+    def load(
+        self, task_id: str, run_id: str | None = None
+    ) -> tuple[ExecutionState, PlanSnapshot]: ...
+
+    def commit(
+        self,
+        state: ExecutionState,
+        snapshot: PlanSnapshot,
+        *,
+        items: tuple[WorkItem, ...] | None = None,
+        children: tuple[ChildTask, ...] | None = None,
+        handoff: str | None = None,
+        bootstrap_request_id: str | None = None,
+    ) -> None: ...
+
+    def drain(
+        self, state: ExecutionState, snapshot: PlanSnapshot
+    ) -> tuple[ExecutionState, PlanSnapshot]: ...
+
+    def resume(self, state: ExecutionState, snapshot: PlanSnapshot) -> Instruction:
+        """Commit, continue the active assignment or drain, then instruct."""
+        ...
+
+    def render(self, state: ExecutionState, snapshot: PlanSnapshot) -> Instruction:
+        """Build the instruction for a loaded run without changing it."""
+        ...
+
+    def instruction_status(self, task_id: str, run_id: str | None) -> Instruction: ...
+
+    def mark_interrupted(
+        self, state: ExecutionState, snapshot: PlanSnapshot
+    ) -> ExecutionState: ...
+
+
+class RunCoordinator:
+    """Coordinate complete run records without owning lifecycle decisions."""
+
+    def __init__(self, tasks: TaskStorageAdapter) -> None:
+        self.tasks = tasks
+
+    def commit_run(
+        self,
+        state: ExecutionState,
+        snapshot: PlanSnapshot,
+        *,
+        items: tuple[WorkItem, ...] | None = None,
+        children: tuple[ChildTask, ...] | None = None,
+        handoff: str | None = None,
+        bootstrap_request_id: str | None = None,
+    ) -> None:
+        """Atomically publish the complete record for one run transition."""
+        runs, existing_handoff, revision = self.tasks.read_task_record(state.task_id)
+        current = next((run for run in runs if run.run_id == state.run_id), None)
+        aggregate = TaskRunAggregate(
+            run_id=state.run_id,
+            workflow=state.workflow,
+            snapshot=snapshot,
+            state=state,
+            items=items if items is not None else (current.items if current else ()),
+            children=(
+                children
+                if children is not None
+                else (current.children if current else ())
+            ),
+            bootstrap_request_id=(
+                bootstrap_request_id
+                if bootstrap_request_id is not None
+                else (current.bootstrap_request_id if current else None)
+            ),
+        )
+        replaced = tuple(
+            aggregate if run.run_id == aggregate.run_id else run for run in runs
+        )
+        if current is None:
+            replaced += (aggregate,)
+        self.tasks.commit_task_aggregate(
+            state.task_id,
+            replaced,
+            handoff if handoff is not None else existing_handoff,
+            expected_revision=revision,
+        )
+
+    def commit_runs(
+        self,
+        task_id: str,
+        aggregates: tuple[TaskRunAggregate, ...],
+        *,
+        handoff: str | None = None,
+    ) -> None:
+        """Atomically publish a coordinated multi-run transition."""
+        _, existing_handoff, revision = self.tasks.read_task_record(task_id)
+        self.tasks.commit_task_aggregate(
+            task_id,
+            aggregates,
+            handoff if handoff is not None else existing_handoff,
+            expected_revision=revision,
+        )
+
+    @staticmethod
+    def select_run(
+        runs: tuple[TaskRunAggregate, ...], run_id: str | None = None
+    ) -> TaskRunAggregate | None:
+        """Return the named run, else the active run, else the latest run."""
+        resolved = run_id or next(
+            (run.run_id for run in reversed(runs) if run_is_open(run.state.status)),
+            runs[-1].run_id if runs else None,
+        )
+        return next((run for run in runs if run.run_id == resolved), None)
+
+    def load(
+        self, task_id: str, run_id: str | None = None
+    ) -> tuple[ExecutionState, PlanSnapshot]:
+        """Load one complete run and verify plan/state identity."""
+        runs, _, _ = self.tasks.read_task_record(task_id)
+        return self.resolve(task_id, runs, run_id)
+
+    def resolve(
+        self,
+        task_id: str,
+        runs: tuple[TaskRunAggregate, ...],
+        run_id: str | None = None,
+    ) -> tuple[ExecutionState, PlanSnapshot]:
+        """Select and verify one run from an already-read record."""
+        aggregate = self.select_run(runs, run_id)
+        if aggregate is None:
+            raise StateError(f"task {task_id!r} has not been started; use start")
+        state = aggregate.state
+        snapshot = aggregate.snapshot
+        if state.plan_revision != snapshot.plan_revision:
+            raise StateError(
+                "task state does not match its authoritative plan revision"
+            )
+        if state.plan_digest and state.plan_digest != snapshot.plan_digest:
+            raise StateError("task state does not match its authoritative plan digest")
+        return state, snapshot

ww/runtimes.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Workflow-runtime definitions for agent orchestration."""
+
+from ww.contracts import NextRole
+from ww.errors import ConfigurationError
+from ww.executable import ww_command
+
+RUNTIME_INSTRUCTIONS = {
+    "single": (
+        "Use this session for both manager and worker responsibilities. The "
+        "manager dispatches an assignment; the worker completes its action and "
+        "associated hooks until ww hands control back.",
+        "Do not spawn subagents.",
+        "Configured agent, model, reasoning, profile, skill, and built-in hints "
+        "are ignored. The user-controlled session settings are authoritative.",
+    ),
+    "auto": (
+        "The manager dispatches each assignment to a worker and handles recovery.",
+        "You may use one worker for every step, choose a fresh worker per "
+        "step or assignment, or perform the assignment yourself.",
+        "Launch each worker with the model and reasoning the assignment "
+        "requests; they take precedence over profile or skill preferences. "
+        "Where none are shown, launch it with its default settings and do not "
+        "choose them yourself.",
+        "If the exact request is unavailable, select the closest worker and "
+        "report the difference. Agent hints are advisory and currently unenforced.",
+        "The worker submits its own results and associated hook results with "
+        "--role worker until ww explicitly hands control back. It then "
+        'returns ww\'s "Handoff to manager" block verbatim as its final '
+        "message; the manager reads the outcome there.",
+        "A worker may delegate one bounded hook when its runtime permits, but "
+        "that worker remains responsible for submitting the result. Nested "
+        "workers must not complete the same item or run manager commands.",
+        "Use this runtime when the work needs execution settings this session "
+        "cannot change, because a worker can be launched with them.",
+    ),
+}
+
+# One-line summaries for choosing a runtime; ``RUNTIME_INSTRUCTIONS`` holds the
+# guidance repeated in every instruction.
+RUNTIME_DESCRIPTIONS = {
+    "single": (
+        "One session plays both manager and worker and does every assignment "
+        "itself, without subagents."
+    ),
+    "auto": (
+        "The manager delegates each assignment to a worker agent it selects, "
+        "using the requested agent, model, and reasoning."
+    ),
+}
+DEFAULT_RUNTIME = "single"
+
+
+def requested_setting(value: object) -> str | None:
+    """A requested model or reasoning, or ``None`` when the workflow asks for none.
+
+    ``auto`` is not shown to agents: an open choice invites them to make one,
+    so an unrequested setting is omitted and the worker keeps its default.
+    """
+    return value if isinstance(value, str) and value != "auto" else None
+
+
+def cli_ownership_warning() -> str:
+    """The strict reminder every runtime instruction ends with."""
+    ww = ww_command()
+    return (
+        f"Strict: only {ww} start, next, and complete operate this flow. Do not "
+        "mimic or bypass it with direct commands, or read "
+        "ww.yaml; follow only the ww execution plan."
+    )
+
+
+def runtime_instruction(
+    name: str, next_role: NextRole | None = None
+) -> tuple[str, ...]:
+    """Return a validated instruction for a persisted workflow runtime."""
+    try:
+        instructions = RUNTIME_INSTRUCTIONS[name]
+        role_instruction: tuple[str, ...]
+        if next_role == "worker":
+            role_instruction = (
+                "Worker responsibility: perform the active assignment and use "
+                "the displayed --role worker completion command. Continue its "
+                "associated hooks until ww reports a manager handoff.",
+            )
+        elif next_role == "manager":
+            role_instruction = (
+                "Manager responsibility: dispatch the next assignment or handle "
+                "the displayed recovery action. Do not ask a worker to run a "
+                "manager command.",
+            )
+        elif next_role == "operator":
+            role_instruction = (
+                "Operator decision: ww waits for the operator, the user. Stop "
+                "and report the situation to them; run a displayed recovery "
+                "command only after they choose it.",
+            )
+        else:
+            role_instruction = ()
+        return (*instructions, *role_instruction, cli_ownership_warning())
+    except KeyError as error:
+        supported = ", ".join(sorted(RUNTIME_INSTRUCTIONS))
+        raise ConfigurationError(
+            f"unsupported workflow runtime {name!r}; choose one of: {supported}"
+        ) from error