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

ww/contracts.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Closed-set type contracts shared by plans, execution, and presentation."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+# One condition of a command's ``assert`` list.
+AssertionKind = Literal["empty", "equals"]
+RequestedActionKind = Literal["mcp", "prompt", "skill", "slash_command"]
+HookPhase = Literal[
+    "before_start_workflow",
+    "before_start",
+    "before_complete",
+    "after_complete",
+    "before_complete_workflow",
+]
+PlanItemPhase = Literal[
+    "before_start_workflow",
+    "before_start",
+    "step",
+    "before_complete",
+    "after_complete",
+    "before_complete_workflow",
+]
+HookScope = Literal["global", "workflow", "step"]
+# What a failed ``before_complete`` hook does: stop for the operator, as any
+# failed handler does, or send the step back to its worker to fix.
+HookFailure = Literal["fix", "operator"]
+# The outcome of one check ww ran when a step completed.
+CheckStatus = Literal["passed", "failed", "not_applicable"]
+# Where a check came from: a rule's own command, a ``fix`` hook, a command
+# the operator approved into the rule-automation store, or a verifier's
+# verdict on a rule without a command.
+CheckSource = Literal["rule", "hook", "derived", "judged"]
+# Why a failed run failed, when the reason is not the item's own error.
+FailureKind = Literal[
+    "fix_limit", "check_disputed", "value_unavailable", "work_failed", "pass_incomplete"
+]
+# A rule's standing in the rule-automation store, keyed by its text hash.
+RuleAutomationStatus = Literal[
+    "approach_proposed",
+    "approach_approved",
+    "interpreted",
+    "proposed",
+    "converted",
+    "rejected",
+    "not_convertible",
+    "ambiguous",
+]
+# A derived check's standing in the rule-automation store.
+CheckAutomationStatus = Literal["proposed", "converted", "rejected"]
+# How a step's rule without a command of its own is enforced, decided when
+# the step begins: by a converted derived check, or by a verifier's verdict.
+RuleResolutionStatus = Literal["converted", "judged"]
+Verdict = Literal["pass", "fail"]
+ItemOperation = Literal[
+    "collect", "process_item", "resolve_item", "report_item", "handle_item"
+]
+# ``handle_item`` is the built-in stage of a bare ``items`` step; it cannot be
+# declared on a configured step.
+# How the per-item stages of an ``items`` step are split into worker
+# assignments in the ``auto`` runtime.
+ItemAssignment = Literal["together", "per_item", "per_step"]
+# How the body steps of a ``loop`` are split into worker assignments in the
+# ``auto`` runtime: one assignment per body step, or one per loop round for
+# consecutive steps that resolve to the same worker settings.
+LoopAssignment = Literal["per_round", "per_step"]
+DEFAULT_LOOP_ASSIGNMENT: LoopAssignment = "per_round"
+ChildOperation = Literal["collect"]
+
+# Action identifiers are registry keys; third-party internal registrations may
+# extend the built-in set without changing generic plan consumers.
+PlanItemKind = str
+# Task IDs issued while an external identity is still being bound.
+BOOTSTRAP_REQUEST_PREFIX = "REQUEST-"
+PlanItemOwner = Literal["agent", "ww"]
+ExecutionKind = Literal[
+    "agent_instruction", "automatic", "loop_control", "workflow_transition"
+]
+LoopOperation = Literal["enter", "repeat"]
+
+CommandStatus = Literal["pending", "in_progress", "interrupted", "completed", "failed"]
+ItemStatus = Literal[
+    "pending",
+    "in_progress",
+    "interrupted",
+    "awaiting_input",
+    "completed",
+    "failed",
+]
+ExecutionStatus = Literal[
+    "pending",
+    "in_progress",
+    "awaiting_input",
+    "interrupted",
+    "failed",
+    "completed",
+    # Closed by a later start of the same workflow; kept as history.
+    "abandoned",
+]
+# A run that is neither finished nor abandoned is the task's open run: it
+# blocks another start and is the one every task command addresses.
+CLOSED_RUN_STATUSES: frozenset[str] = frozenset({"completed", "abandoned"})
+
+
+def run_is_open(status: str) -> bool:
+    return status not in CLOSED_RUN_STATUSES
+
+
+StepStatus = Literal["pending", "in_progress", "interrupted", "completed", "failed"]
+# ``skipped``: a ``break`` on a per-child parent stage ended the children
+# before this one started.
+ChildStatus = Literal[
+    "pending", "starting", "in_progress", "completed", "failed", "skipped"
+]
+RunStatus = Literal["pending", "in_progress", "completed", "failed"]
+InstructionStatus = Literal[
+    "pending",
+    "in_progress",
+    "awaiting_input",
+    "interrupted",
+    "failed",
+    "completed",
+    "abandoned",
+    "task_summary",
+]
+RecoveryAction = Literal["retry", "force"]
+CallerRole = Literal["manager", "worker"]
+# Who performs an agent step: the manager in its own session, or a worker it
+# delegates to. Both are also the caller roles.
+StepRole = Literal["manager", "worker"]
+# Who acts next. The operator is the human ww waits for; never a caller role.
+NextRole = Literal["manager", "worker", "operator"]
+Control = Literal["continue_worker", "handoff_manager", "blocked", "awaiting_operator"]
+# Why a task waits for the operator.
+OperatorReason = Literal[
+    "handler_failed",
+    "work_failed",
+    "child_failed",
+    "handler_interrupted",
+    "loop_limit",
+    "fix_limit",
+    "check_disputed",
+    "value_unavailable",
+    "pass_incomplete",
+    "plan_changed",
+]
+CALLER_ROLES: tuple[CallerRole, ...] = ("manager", "worker")
+CONTROL_VALUES: tuple[Control, ...] = (
+    "continue_worker",
+    "handoff_manager",
+    "blocked",
+    "awaiting_operator",
+)

ww/control.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Core-owned workflow-control inspection helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ww.actions import PlannedAction, actions
+from ww.operations import ChildWorkflowRun, LoopBoundary, WorkflowHandoff
+
+if TYPE_CHECKING:
+    from ww.plan import PlanItem
+
+
+def workflow_transition(item: PlanItem) -> WorkflowHandoff | None:
+    return item.operation if isinstance(item.operation, WorkflowHandoff) else None
+
+
+def child_workflow(item: PlanItem) -> ChildWorkflowRun | None:
+    return item.operation if isinstance(item.operation, ChildWorkflowRun) else None
+
+
+def loop_control(item: PlanItem) -> LoopBoundary | None:
+    return item.operation if isinstance(item.operation, LoopBoundary) else None
+
+
+def is_coordinator(item: PlanItem) -> bool:
+    return isinstance(item.operation, (WorkflowHandoff, ChildWorkflowRun, LoopBoundary))
+
+
+def replays_harmlessly(item: PlanItem) -> bool:
+    """Whether the item's handler declared that running it again does no damage.
+
+    ``idempotent: true`` is the author's statement, so an interrupted run of
+    such a handler is replayed without asking the operator.
+    """
+    if not isinstance(item.operation, PlannedAction) or not actions.contains(item.kind):
+        return False
+    implementation = actions.get(item.kind)
+    planned = item.payload_as(implementation.planned_type)
+    return implementation.traits(planned).idempotent

ww/defaults.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Built-in project defaults created by ``ww-agentic-workflows init``."""
+
+import json
+from copy import deepcopy
+from importlib.resources import files
+from typing import Any
+
+from ww.config_files import (
+    FILE_STEM,
+    LOCAL_SETTINGS_FILE,
+    SETTINGS_FILE,
+    USER_DIR_VARIABLE,
+)
+from ww.executable import DEFAULT_EXECUTABLE
+from ww.project_config import (
+    BUILTIN_DEFAULTS,
+    AgentHooks,
+    Limits,
+)
+from ww.runtimes import DEFAULT_RUNTIME
+
+DEFAULT_WORKFLOWS_YAML = """modes: []
+handlers: []
+hooks: {}
+workflows: []
+"""
+
+
+def default_settings() -> dict[str, Any]:
+    """Every root-level setting with its default, in the order init writes them.
+
+    The settings file init creates holds all of them, so each option can be
+    found and changed in place.
+    """
+    return {
+        "enabled": True,
+        "runtime": DEFAULT_RUNTIME,
+        "update_check": True,
+        "feedback_learning": True,
+        "executable": DEFAULT_EXECUTABLE,
+        "task_format": "TASK-{{uuid}}",
+        "limits": Limits().to_dict(),
+        "agent_hooks": AgentHooks().to_dict(),
+        "rules": {},
+        "builtins": deepcopy(BUILTIN_DEFAULTS),
+        "workflows": {},
+        "projects": [],
+        "extensions": {},
+    }
+
+
+DEFAULT_PROJECT_CONFIG_JSON = json.dumps(default_settings(), indent=2) + "\n"
+
+
+# ``./ww`` runs the binary the settings levels name in ``executable``, read on
+# every run so a project switches installs by editing one line; the local file
+# wins over the repo one, which wins over the user's. Without python3 or the
+# key it runs the standard name.
+PROJECT_LAUNCHER = f"""#!/bin/sh
+set -eu
+project_root=$(CDPATH= cd "$(dirname "$0")" && pwd)
+cd "$project_root"
+executable={DEFAULT_EXECUTABLE}
+if command -v python3 >/dev/null 2>&1; then
+  configured=$(python3 -c '
+import json, os
+user = os.environ.get("{USER_DIR_VARIABLE}") or os.path.join(
+    os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config"),
+    "{FILE_STEM}",
+)
+value = None
+for path in (
+    os.path.join(user, "{SETTINGS_FILE}"),
+    "{SETTINGS_FILE}",
+    "{LOCAL_SETTINGS_FILE}",
+):
+    try:
+        found = json.load(open(path)).get("executable")
+    except (OSError, ValueError, AttributeError):
+        continue
+    if isinstance(found, str) and found.strip():
+        value = found.strip()
+print(value or "")
+' 2>/dev/null || true)
+  if [ -n "$configured" ]; then
+    executable=$configured
+  fi
+fi
+exec "$executable" "$@"
+"""
+
+
+AGENT_INSTRUCTIONS = (
+    files("ww.assets").joinpath("agent_instructions.md").read_text(encoding="utf-8")
+)
+# The skills ``init`` offers to install into each agent directory, by name:
+# ``ww`` to work through ww, ``noww`` for the operator to opt out of it,
+# ``ww-rule`` to write rules for ww's steps from the operator's words, and
+# ``ww-setup`` with the skills it guides through, each starting one of ww's
+# learning and setup workflows (``ww-refresh`` reruns the project learning;
+# express setup is ``ww-suggest`` told to derive defaults, with no skill of
+# its own), ``ww-scriptize``, which starts ``ww-scriptize-rules``, and
+# ``ww-wizard``, which shapes workflows and rules with the operator through
+# ``setup apply``/``setup update`` and the rules skills.
+WW_SKILL_NAME = "ww"
+SKILLS = {
+    name: files("ww.assets").joinpath(f"{name}_skill.md").read_text(encoding="utf-8")
+    for name in (
+        WW_SKILL_NAME,
+        "noww",
+        "ww-rule",
+        "ww-setup",
+        "ww-learn-project",
+        "ww-suggest",
+        "ww-refresh",
+        "ww-solve",
+        "ww-rules-from-artifacts",
+        "ww-feedback-rules",
+        "ww-deduce-feedback",
+        "ww-automate",
+        "ww-scriptize",
+        "ww-wizard",
+    )
+}
+
+
+def skill_location(directory: str, name: str) -> str:
+    """Where a skill lives inside an agent directory."""
+    return f"{directory}/skills/{name}/SKILL.md"

ww/design_docs.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The three design documents, readable from a checkout or an installation.
+
+The canonical files live in ``documentation/``. A built distribution carries
+byte-for-byte copies under ``ww/assets/docs`` (added by the build, never
+committed), so ``ww docs`` shows the documents of the installed version.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+from .errors import StateError
+
+DESIGN_DOCUMENTS = ("specification", "features", "examples")
+PACKAGED_DIRECTORY = "docs"
+_CHECKOUT = Path(__file__).resolve().parents[2] / "documentation"
+
+
+def read_design_document(name: str) -> str:
+    """Return the same-version text of one design document."""
+    if name not in DESIGN_DOCUMENTS:
+        known = ", ".join(DESIGN_DOCUMENTS)
+        raise StateError(f"unknown document {name!r}; choose one of: {known}")
+    packaged = files("ww.assets").joinpath(PACKAGED_DIRECTORY).joinpath(f"{name}.md")
+    if packaged.is_file():
+        return packaged.read_text(encoding="utf-8")
+    checkout = _CHECKOUT / f"{name}.md"
+    if checkout.is_file():
+        return checkout.read_text(encoding="utf-8")
+    raise StateError(f"the {name} document is not available in this installation")

ww/discovery.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Local discovery of agent skills and commands."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ww.errors import ConfigurationError
+
+AGENT_DIRECTORIES = {
+    "codex": ".codex",
+    "claudecode": ".claude",
+    "gemini": ".gemini",
+    "antigravity": ".antigravity",
+    "deepseek": ".deepseek",
+    "kimi": ".kimi",
+    "cursor": ".cursor",
+    "grok": ".grok",
+}
+CUSTOM_AGENT_PREFIX = "custom:"
+# A custom agent name, e.g. "my-agent.v2"; "-agent" does not match.
+_AGENT_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
+
+
+@dataclass(frozen=True)
+class AvailableActions:
+    """Project-local action names available to one agent integration."""
+
+    skills: frozenset[str]
+    slash_commands: frozenset[str]
+
+
+class AgentDiscovery:
+    """Discover skills and commands in project-local agent directories."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def available(self, agent: str) -> AvailableActions:
+        """Return normalized skill and slash-command names for ``agent``."""
+        skills, commands = self._discover(self._roots(normalize_agent(agent)))
+        return AvailableActions(
+            frozenset(item.removeprefix("/") for item in skills), frozenset(commands)
+        )
+
+    def profile(self, agent: str, name: str) -> Path | None:
+        """Return a project-local profile from the selected agent's directory."""
+        normalized = normalize_agent(agent)
+        directory = AGENT_DIRECTORIES.get(normalized, f".{normalized}")
+        profiles = self.root / directory / "agents"
+        if not profiles.is_dir():
+            return None
+        return next(
+            (
+                path
+                for path in profiles.rglob("*")
+                if path.is_file() and path.stem == name
+            ),
+            None,
+        )
+
+    def _roots(self, agent: str) -> tuple[Path, ...]:
+        directory = AGENT_DIRECTORIES.get(agent)
+        if directory is None:
+            if not _AGENT_NAME.fullmatch(agent):
+                raise ConfigurationError(f"invalid custom agent name {agent!r}")
+            directory = f".{agent}"
+        agent_root = self.root / directory
+        return (self.root / ".agents", agent_root)
+
+    @staticmethod
+    def _discover(roots: tuple[Path, ...]) -> tuple[set[str], set[str]]:
+        skills: set[str] = set()
+        commands: set[str] = set()
+        for root in roots:
+            if not root.is_dir():
+                continue
+            for path in root.rglob("SKILL.md"):
+                if "skills" in path.parts:
+                    skills.add(f"/{path.parent.name}")
+            for path in root.rglob("*.md"):
+                if "commands" in path.parts:
+                    commands.add(path.stem)
+        return skills, commands
+
+
+def normalize_agent(agent: str) -> str:
+    """Validate a public agent argument and strip an explicit custom prefix."""
+    if agent in AGENT_DIRECTORIES:
+        return agent
+    if agent.startswith(CUSTOM_AGENT_PREFIX):
+        custom_name = agent.removeprefix(CUSTOM_AGENT_PREFIX)
+        if _AGENT_NAME.fullmatch(custom_name):
+            return custom_name
+        raise ConfigurationError(
+            "custom agent name must contain letters, digits, ., _, or -"
+        )
+    supported = ", ".join(AGENT_DIRECTORIES)
+    raise ConfigurationError(
+        f"unsupported agent {agent!r}; choose one of: {supported}, "
+        f"or use {CUSTOM_AGENT_PREFIX}<name>"
+    )

ww/documents.py

@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Durable documents: free-format files workflows read and update across runs.
+
+A document is declared once at the root of ``ww.yaml`` and lives in
+the task directory, under ``.ww`` for the project scope, or in the user
+configuration directory for the user scope, where every project of the user
+shares it.  Agents edit the file in place; ww only resolves its path, checks
+that a step which promised an update left the file behind, and journals who
+updated it last.  The journal of a user document is the project's: it records
+what this project's runs did to the shared file.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from ww.config_files import user_directory
+from ww.errors import StateError
+from ww.storage import Storage
+from ww.validation import expect_optional_string, expect_string
+from ww.workflow_config import TASK_ID_TOKEN, DocumentDefinition
+
+JOURNAL_FILE = "documents.json"
+DOCUMENTS_DIRECTORY = "documents"
+
+
+@dataclass(frozen=True)
+class DocumentUpdateRecord:
+    """Who last updated a document, and the content they left."""
+
+    updated_at: str
+    run_id: str | None
+    step: str
+    sha256: str
+
+    def to_dict(self) -> dict[str, str | None]:
+        return {
+            "updated_at": self.updated_at,
+            "run_id": self.run_id,
+            "step": self.step,
+            "sha256": self.sha256,
+        }
+
+    @classmethod
+    def from_dict(cls, data: object, label: str) -> DocumentUpdateRecord:
+        if not isinstance(data, dict):
+            raise ValueError(f"{label} must be a mapping")
+        return cls(
+            expect_string(data.get("updated_at"), f"{label}.updated_at"),
+            expect_optional_string(data.get("run_id"), f"{label}.run_id"),
+            expect_string(data.get("step"), f"{label}.step"),
+            expect_string(data.get("sha256"), f"{label}.sha256"),
+        )
+
+
+class DocumentStore:
+    """Paths and the update journal for declared documents."""
+
+    def __init__(self, storage: Storage) -> None:
+        self.storage = storage
+
+    def path(
+        self,
+        document: DocumentDefinition,
+        task_id: str | None,
+        workspace: Path | None = None,
+    ) -> Path:
+        """The document's absolute file for the filesystem ww runs in now.
+
+        A declared ``path`` is relative to the project root, or to the task's
+        working directory for a task document when the run has one, so a file
+        kept in the repository lands on the task's branch. A user document
+        lives in the user configuration directory, which is created for it.
+        """
+        if document.scope == "user":
+            return self._user_path(document)
+        if document.path is None:
+            directory = (
+                self.storage.runtime_path / DOCUMENTS_DIRECTORY
+                if document.scope == "project"
+                else self._task_directory(task_id) / DOCUMENTS_DIRECTORY
+            )
+            return (directory / f"{document.name}.md").resolve()
+        if document.scope == "task" and task_id is None:
+            raise StateError("a task-scoped document needs a task ID")
+        base = (
+            workspace
+            if document.scope == "task" and workspace is not None
+            else self.storage.root
+        )
+        relative = document.path.replace(TASK_ID_TOKEN, task_id or "")
+        return (base / relative).resolve()
+
+    @staticmethod
+    def _user_path(document: DocumentDefinition) -> Path:
+        directory = user_directory().resolve()
+        path = (directory / (document.path or f"{document.name}.md")).resolve()
+        if not path.is_relative_to(directory):
+            raise StateError(
+                f"document {document.name!r} resolves outside the user "
+                f"configuration directory: {path}"
+            )
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def exists(
+        self,
+        document: DocumentDefinition,
+        task_id: str | None,
+        workspace: Path | None = None,
+    ) -> bool:
+        return self.path(document, task_id, workspace).is_file()
+
+    def record_update(
+        self,
+        document: DocumentDefinition,
+        task_id: str | None,
+        *,
+        run_id: str | None,
+        step: str,
+        updated_at: str,
+        workspace: Path | None = None,
+    ) -> DocumentUpdateRecord:
+        """Journal that ``step`` updated the document, hashing its content."""
+        path = self.path(document, task_id, workspace)
+        if not path.is_file():
+            raise StateError(f"document {document.name!r} does not exist at {path}")
+        record = DocumentUpdateRecord(
+            updated_at, run_id, step, hashlib.sha256(path.read_bytes()).hexdigest()
+        )
+        journal_path = self._journal_path(document, task_id)
+        # A task journal is already serialized by the task lock; a project
+        # journal is shared by every task, so its read-modify-write needs a
+        # lock of its own, as project metadata has.
+        with self.storage.locks.lock(journal_path, purpose="document journal"):
+            journal = self._read_journal(journal_path)
+            journal[document.name] = record.to_dict()
+            self.storage.locks.atomic_write(
+                journal_path, json.dumps(journal, indent=2, sort_keys=True) + "\n"
+            )
+        return record
+
+    def last_update(
+        self, document: DocumentDefinition, task_id: str | None
+    ) -> DocumentUpdateRecord | None:
+        journal_path = self._journal_path(document, task_id)
+        entry = self._read_journal(journal_path).get(document.name)
+        if entry is None:
+            return None
+        try:
+            return DocumentUpdateRecord.from_dict(entry, document.name)
+        except ValueError as error:
+            raise StateError(
+                f"invalid document journal {journal_path}: {error}"
+            ) from error
+
+    def listing(
+        self,
+        documents: tuple[DocumentDefinition, ...],
+        task_id: str | None,
+        workspace: Path | None = None,
+    ) -> list[dict[str, object]]:
+        """Describe every declared document: where it is and who updated it."""
+        result: list[dict[str, object]] = []
+        for document in documents:
+            if document.scope == "task" and task_id is None:
+                continue
+            last = self.last_update(document, task_id)
+            result.append(
+                {
+                    "name": document.name,
+                    "description": document.description,
+                    "scope": document.scope,
+                    "path": str(self.path(document, task_id, workspace)),
+                    "exists": self.exists(document, task_id, workspace),
+                    "last_update": last.to_dict() if last else None,
+                }
+            )
+        return result
+
+    def remove_task(self, task_id: str) -> None:
+        """Forget a task's documents: its journal and the files kept under ``.ww``.
+
+        A document declared with an explicit ``path`` is the workflow's own
+        file and stays in place.
+        """
+        directory = self._task_directory(task_id)
+        (directory / JOURNAL_FILE).unlink(missing_ok=True)
+        documents = directory / DOCUMENTS_DIRECTORY
+        if documents.is_dir() and not documents.is_symlink():
+            shutil.rmtree(documents)
+
+    def _journal_path(self, document: DocumentDefinition, task_id: str | None) -> Path:
+        if document.scope != "task":
+            return self.storage.runtime_path / JOURNAL_FILE
+        return self._task_directory(task_id) / JOURNAL_FILE
+
+    def _task_directory(self, task_id: str | None) -> Path:
+        if task_id is None:
+            raise StateError("a task-scoped document needs a task ID")
+        return self.storage.runtime_path / "tasks" / task_id
+
+    @staticmethod
+    def _read_journal(path: Path) -> dict[str, object]:
+        if not path.is_file():
+            return {}
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise StateError(f"invalid document journal {path}: {error}") from error
+        if not isinstance(data, dict):
+            raise StateError(f"invalid document journal {path}: not a mapping")
+        return data