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

ww/errors.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Domain errors exposed as clear CLI failures."""
+
+
+class WwError(Exception):
+    """Base error for expected workflow failures."""
+
+
+class ConfigurationError(WwError):
+    """A workflow definition is missing or invalid."""
+
+
+class StateError(WwError):
+    """A task state is missing, invalid, or cannot transition."""
+
+
+class LockError(WwError):
+    """A file lock could not be acquired within the configured wait bound."""

ww/executable.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""How the commands ww prints invoke ww.
+
+A project names its ww binary in ``ww.json`` (``executable``),
+so two installs, such as one for developing ww and one pinned to ``dev``, can
+live side by side under different global names. Every command ww prints
+starts with that binary, or with the project launcher, ``./ww``, when the
+project names none. The CLI sets it once per invocation.
+
+This module imports nothing from ww, so any module may use it.
+"""
+
+from __future__ import annotations
+
+import shlex
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+PROJECT_LAUNCHER_COMMAND = "./ww"
+# The binary a project uses when it names none, and the one the launcher
+# falls back to.
+DEFAULT_EXECUTABLE = "ww-agentic-workflows"
+_EXECUTABLE: ContextVar[str] = ContextVar(
+    "ww_executable", default=PROJECT_LAUNCHER_COMMAND
+)
+
+
+@contextmanager
+def printed_executable(executable: str | None) -> Iterator[None]:
+    """Print commands with ``executable``; ``None`` keeps the project launcher."""
+    token = _EXECUTABLE.set(
+        shlex.quote(executable) if executable else PROJECT_LAUNCHER_COMMAND
+    )
+    try:
+        yield
+    finally:
+        _EXECUTABLE.reset(token)
+
+
+def ww_command() -> str:
+    """How a printed command invokes ww, as the command's first word."""
+    return _EXECUTABLE.get()

ww/execution_models/__init__.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Persisted, plan-driven workflow execution models.
+
+This facade preserves the public import surface while the persistence records,
+run aggregates, plan codec, and state construction live in focused modules.
+"""
+
+from .construction import (
+    build_step_projection,
+    initial_state,
+    new_item_execution,
+    operation_scope_for,
+)
+from .records import (
+    EXECUTION_SCHEMA_VERSION,
+    CheckReport,
+    CheckResult,
+    CommandExecution,
+    Dispute,
+    ExecutionState,
+    HeldCompletion,
+    InputRequest,
+    PlanItemExecution,
+    ProjectMetadataPublication,
+    RuleResolution,
+    RuleVerdict,
+    StepProgress,
+    VerificationRule,
+)
+from .runs import (
+    PLAN_COMPILER_VERSION,
+    PLAN_SCHEMA_VERSION,
+    PlanSnapshot,
+    TaskRunAggregate,
+    WorkflowRunSummary,
+    validate_task_runs,
+)
+
+__all__ = [
+    "CheckReport",
+    "CheckResult",
+    "EXECUTION_SCHEMA_VERSION",
+    "PLAN_COMPILER_VERSION",
+    "PLAN_SCHEMA_VERSION",
+    "CommandExecution",
+    "Dispute",
+    "ExecutionState",
+    "HeldCompletion",
+    "InputRequest",
+    "PlanItemExecution",
+    "PlanSnapshot",
+    "ProjectMetadataPublication",
+    "RuleResolution",
+    "RuleVerdict",
+    "StepProgress",
+    "VerificationRule",
+    "TaskRunAggregate",
+    "WorkflowRunSummary",
+    "build_step_projection",
+    "initial_state",
+    "new_item_execution",
+    "operation_scope_for",
+    "validate_task_runs",
+]

ww/execution_models/construction.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Persisted, plan-driven workflow execution models.
+
+These models deliberately contain no YAML or handler-resolution concepts.  A
+task starts with a compiled :class:`WorkflowPlan` snapshot and progresses only
+through the normalized plan items in that snapshot.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ww.actions import CommandDefinition, PlannedAction, actions
+from ww.plan import PlanItem, WorkflowPlan
+
+from .records import CommandExecution, ExecutionState, PlanItemExecution, StepProgress
+from .runs import PlanSnapshot
+
+
+def initial_state(
+    snapshot: PlanSnapshot,
+    modes: tuple[str, ...],
+    now: str,
+    run_id: str,
+    execution_instance_id: str | None = None,
+    parent_task_id: str | None = None,
+    start_operation_id: str | None = None,
+    workflow_runtime: str = "single",
+    model: str = "auto",
+    reasoning: str = "auto",
+) -> ExecutionState:
+    plan = snapshot.plan
+    operation_scope = _operation_scope(run_id, execution_instance_id)
+    records = tuple(
+        new_item_execution(plan.task_id or "", operation_scope, item)
+        for item in plan.items
+    )
+    return ExecutionState(
+        task_id=plan.task_id or "",
+        workflow=plan.workflow,
+        agent=plan.agent,
+        modes=modes,
+        status="pending",
+        created_at=now,
+        updated_at=now,
+        snapshot_digest=snapshot.configuration_digest,
+        cursor=0,
+        active_item_id=None,
+        item_executions=records,
+        steps=build_step_projection(plan),
+        run_id=run_id,
+        execution_instance_id=execution_instance_id,
+        plan_revision=snapshot.plan_revision,
+        plan_digest=snapshot.plan_digest,
+        parent_task_id=parent_task_id,
+        start_operation_id=start_operation_id,
+        workflow_runtime=workflow_runtime,
+        model=model,
+        reasoning=reasoning,
+    )
+
+
+def new_item_execution(
+    task_id: str, operation_scope: str, item: PlanItem
+) -> PlanItemExecution:
+    """Create the complete execution ledger for one concrete plan item."""
+    operation_id = f"{task_id}:{operation_scope}:{item.id}"
+    return PlanItemExecution(
+        plan_item_id=item.id,
+        position=item.position,
+        operation_id=operation_id,
+        commands=tuple(
+            CommandExecution(
+                index=index,
+                operation_id=f"{operation_id}:command:{index}",
+            )
+            for index, _ in enumerate(_commands_for(item), 1)
+        ),
+    )
+
+
+def _commands_for(item: PlanItem) -> tuple[CommandDefinition, ...]:
+    """Return tracked command segments when the registered action supports them."""
+    if not isinstance(item.operation, PlannedAction):
+        return ()
+    implementation = actions.get(item.kind)
+    traits = implementation.traits(item.payload_as(implementation.planned_type))
+    return traits.command_segments or ()
+
+
+def operation_scope_for(state: ExecutionState) -> str:
+    """Return the durable idempotency namespace for an execution instance."""
+    return _operation_scope(state.run_id or state.workflow, state.execution_instance_id)
+
+
+def _operation_scope(run_id: str, execution_instance_id: str | None) -> str:
+    return (
+        f"{run_id}:{execution_instance_id}"
+        if execution_instance_id is not None
+        else run_id
+    )
+
+
+def _persisted_step_chain(item: PlanItem) -> tuple[str, ...]:
+    """Return the hierarchy encoded by a plan item."""
+    chain = (*item.ancestors, item.step)
+    if item.parent and item.parent not in chain[:-1]:
+        return item.parent, item.step
+    return chain
+
+
+def build_step_projection(
+    plan: WorkflowPlan, previous: tuple[StepProgress, ...] = ()
+) -> tuple[StepProgress, ...]:
+    """Build the recursive tree, retaining progress for paths that still exist."""
+    prior: dict[str, StepProgress] = {}
+
+    def remember(entries: tuple[StepProgress, ...]) -> None:
+        for entry in entries:
+            prior[entry.path] = entry
+            remember(entry.children)
+
+    remember(previous)
+    nodes: dict[str, dict[str, Any]] = {}
+    order: list[str] = []
+    for item in plan.items:
+        chain = _persisted_step_chain(item)
+        for index, path in enumerate(chain):
+            parent = chain[index - 1] if index else None
+            if path not in nodes:
+                nodes[path] = {"parent": parent, "children": []}
+                order.append(path)
+            if parent and path not in nodes[parent]["children"]:
+                nodes[parent]["children"].append(path)
+
+    def node(path: str) -> StepProgress:
+        info = nodes[path]
+        existing = prior.get(path)
+        return StepProgress(
+            path.rsplit("/", 1)[-1],
+            path,
+            status=existing.status if existing is not None else "pending",
+            started_at=existing.started_at if existing is not None else None,
+            completed_at=existing.completed_at if existing is not None else None,
+            children=tuple(node(child) for child in info["children"]),
+        )
+
+    return tuple(node(path) for path in order if nodes[path]["parent"] is None)

ww/execution_models/decoding.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Decoding helpers specific to persisted execution records.
+
+Primitive checks live in :mod:`ww.validation`; this module keeps only the
+shapes that exist solely in saved task state.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from ww.validation import is_positive_int
+
+_T = TypeVar("_T")
+
+
+def _from_path(function: Callable[[Any], _T], value: Any, path: str) -> _T:
+    try:
+        return function(value)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"{path}: {error}") from error
+
+
+def _variables(value: Any, context: str) -> tuple[tuple[str, str], ...]:
+    if not isinstance(value, dict) or not all(
+        isinstance(name, str) and isinstance(item, str) for name, item in value.items()
+    ):
+        raise ValueError(f"{context} must be a mapping of strings")
+    return tuple(value.items())
+
+
+def _positive_int_mapping(value: Any, context: str) -> tuple[tuple[str, int], ...]:
+    if not isinstance(value, dict) or not all(
+        isinstance(name, str) and is_positive_int(item) for name, item in value.items()
+    ):
+        raise ValueError(f"{context} must be a mapping of positive integers")
+    return tuple(value.items())