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

ww/actions/extension.py

@@ -0,0 +1,197 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Extension action planning, identity, and execution effects."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+from ww.errors import ConfigurationError
+from ww.extensions import (
+    ExtensionCheckResult,
+    ExtensionResult,
+    parse_reference,
+)
+from ww.validation import (
+    expect_keys,
+    expect_optional_int,
+    expect_optional_mapping,
+    expect_optional_string,
+    expect_string,
+)
+
+from .contracts import (
+    ActionResult,
+    ActionTraits,
+    AutomaticAction,
+    ExecutionContext,
+    Extension,
+    ExtensionBinding,
+    InputValidationContext,
+    InstructionContent,
+    InstructionContext,
+    PreflightContext,
+    RecoveryCheckResult,
+    RecoveryContext,
+    ResolutionContext,
+)
+
+
+class ExtensionAction(AutomaticAction[Extension, Extension]):
+    identifier = "extension"
+    planned_type = Extension
+
+    def preflight(self, planned: Extension, context: PreflightContext) -> None:
+        context.extensions.validate_identity(planned)
+
+    def validate_inputs(
+        self,
+        planned: Extension,
+        values: Mapping[str, str],
+        context: InputValidationContext,
+    ) -> str | None:
+        """Let the handler's own ``validate`` judge its declared inputs."""
+        handler = context.extensions.handler(planned.reference)
+        if handler.validate is None:
+            return None
+        own = {
+            value.name: values[value.name]
+            for value in handler.provide
+            if value.name in values
+        }
+        try:
+            verdict = handler.validate(MappingProxyType(own))
+        except Exception as error:  # noqa: BLE001 - extension exceptions are refusals
+            return f"{type(error).__name__}: {error}"
+        if verdict is None:
+            return None
+        if not isinstance(verdict, str) or not verdict.strip():
+            return "extension validator returned an invalid result"
+        return verdict.strip()
+
+    def execute(self, planned: Extension, context: ExecutionContext) -> ActionResult:
+        handler = context.extensions.handler(planned.reference)
+        try:
+            result = handler.run(context.extensions.context(planned))
+        except Exception as error:  # noqa: BLE001 - extension exceptions are action failures
+            return ActionResult.failed(f"{type(error).__name__}: {error}")
+        if not isinstance(result, ExtensionResult):
+            return ActionResult.failed(
+                "extension returned an invalid result: expected ExtensionResult"
+            )
+        if not result.ok:
+            return ActionResult.failed(result.error.strip() or "no error reported")
+        return ActionResult.succeeded(
+            result.output,
+            values=result.values,
+            working_directory=result.working_directory,
+        )
+
+    def check_recovery(
+        self, planned: Extension, context: RecoveryContext
+    ) -> RecoveryCheckResult:
+        context.extensions.validate_identity(planned)
+        try:
+            result = context.extensions.check(planned)
+            if not isinstance(result, ExtensionCheckResult):
+                return RecoveryCheckResult.unknown(
+                    "extension checker returned an invalid result"
+                )
+            if result.status == "succeeded":
+                assert result.result is not None  # validated by ExtensionCheckResult
+                return RecoveryCheckResult.succeeded(
+                    ActionResult.succeeded(
+                        result.result.output,
+                        values=result.result.values,
+                        working_directory=result.result.working_directory,
+                    )
+                )
+            if result.status == "not_succeeded":
+                return RecoveryCheckResult.not_succeeded()
+            return RecoveryCheckResult.unknown(result.error)
+        except Exception as error:  # noqa: BLE001 - checker errors remain unknown
+            return RecoveryCheckResult.unknown(f"{type(error).__name__}: {error}")
+
+    def traits(self, planned: Extension) -> ActionTraits:
+        return ActionTraits(
+            manual_attestation=frozenset({"values", "workspace"}),
+            extension_binding=ExtensionBinding(planned.reference, planned.settings),
+        )
+
+    def parse(
+        self, source: dict[str, Any], name: str, description: str, path: str
+    ) -> Extension:
+        return Extension(name)
+
+    def validate(self, definition: Extension, path: str) -> None:
+        parse_reference(definition.reference)
+
+    def templates(self, definition: Extension) -> tuple[str, ...]:
+        return definition.arguments
+
+    def plan(self, definition: Extension, context: ResolutionContext) -> Extension:
+        if context.extensions is None:
+            raise ConfigurationError("no extensions are loaded")
+        reference = parse_reference(definition.reference)
+        identity = context.extensions.identity(reference.identifier)
+        return Extension(
+            definition.reference,
+            identity.version,
+            identity.api_version,
+            identity.source,
+            identity.fingerprint,
+            context.extensions.settings(reference.identifier, context.project),
+            tuple(context.interpolate(argument) for argument in definition.arguments),
+        )
+
+    def instruction(
+        self, planned: Extension, context: InstructionContext
+    ) -> InstructionContent:
+        return InstructionContent(context.description or context.name, ())
+
+    def encode(self, planned: Extension) -> dict[str, object]:
+        encoded: dict[str, object] = {
+            "reference": planned.reference,
+            "version": planned.version,
+            "api_version": planned.api_version,
+            "source": planned.source,
+            "fingerprint": planned.fingerprint,
+            "settings": planned.settings,
+        }
+        # Absent without ``args``, so plans saved before arguments existed
+        # read and compare unchanged.
+        if planned.arguments:
+            encoded["arguments"] = list(planned.arguments)
+        return encoded
+
+    def decode(self, data: dict[str, Any]) -> Extension:
+        expect_keys(
+            data,
+            {
+                "reference",
+                "version",
+                "api_version",
+                "source",
+                "fingerprint",
+                "settings",
+            },
+            f"action {self.identifier!r} payload",
+        )
+        return Extension(
+            expect_string(data["reference"], "extension reference"),
+            expect_optional_string(data["version"], "extension version"),
+            expect_optional_int(data["api_version"], "extension API version"),
+            expect_optional_string(data["source"], "extension source"),
+            expect_optional_string(data["fingerprint"], "extension fingerprint"),
+            expect_optional_mapping(data["settings"], "extension settings"),
+            _arguments(data.get("arguments", [])),
+        )
+
+
+def _arguments(value: object) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(
+        isinstance(argument, str) for argument in value
+    ):
+        raise ValueError("extension arguments must be a list of strings")
+    return tuple(value)

ww/actions/mcp.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""MCP action."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ww.errors import ConfigurationError
+from ww.interpolation import interpolate
+from ww.validation import expect_keys, expect_string
+
+from .contracts import (
+    Action,
+    InstructionContent,
+    InstructionContext,
+    Mcp,
+    ResolutionContext,
+)
+
+
+class McpAction(Action[Mcp, Mcp]):
+    identifier = "mcp"
+    planned_type = Mcp
+
+    def parse(
+        self, source: dict[str, Any], name: str, description: str, path: str
+    ) -> Mcp:
+        connection = source.get("mcp")
+        if not isinstance(connection, str) or not connection.strip():
+            raise ConfigurationError(f"{path} mcp must be non-empty")
+        return Mcp(connection, description or name)
+
+    def validate(self, definition: Mcp, path: str) -> None:
+        if not definition.connection or not definition.prompt:
+            raise ConfigurationError(f"{path} MCP requires a connection and prompt")
+
+    def templates(self, definition: Mcp) -> tuple[str, ...]:
+        return (definition.connection, definition.prompt)
+
+    def plan(self, definition: Mcp, context: ResolutionContext) -> Mcp:
+        return Mcp(
+            context.interpolate(definition.connection),
+            context.interpolate(definition.prompt),
+        )
+
+    def instruction(
+        self, planned: Mcp, context: InstructionContext
+    ) -> InstructionContent:
+        prompt = (
+            interpolate(planned.prompt, context.task_values)
+            if context.task_values
+            else planned.prompt
+        )
+        text = (
+            f"For the following work use `{planned.connection}` mcp connection:\n"
+            f"{prompt or context.description or context.name}\n\n"
+            "If your result from the MCP call is erroneous, do not proceed to "
+            "the next step. Use the `fail` command to register that and notify "
+            "the caller of this task."
+        )
+        return InstructionContent(
+            text,
+            (
+                "**Prompt**",
+                "",
+                f"For the following work use `{planned.connection}` mcp connection:",
+                "",
+                prompt,
+                "",
+            ),
+            include_item_context=True,
+        )
+
+    def encode(self, planned: Mcp) -> dict[str, object]:
+        return {"connection": planned.connection, "prompt": planned.prompt}
+
+    def decode(self, data: dict[str, Any]) -> Mcp:
+        expect_keys(
+            data, {"connection", "prompt"}, f"action {self.identifier!r} payload"
+        )
+        return Mcp(
+            expect_string(data["connection"], "MCP connection"),
+            expect_string(data["prompt"], "MCP prompt"),
+        )

ww/actions/prompt.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Prompt action."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ww.errors import ConfigurationError
+from ww.interpolation import interpolate
+from ww.validation import expect_keys, expect_string
+
+from .contracts import (
+    Action,
+    DefinitionOverrideContext,
+    InstructionContent,
+    InstructionContext,
+    Prompt,
+    ResolutionContext,
+)
+
+
+class PromptAction(Action[Prompt, Prompt]):
+    identifier = "prompt"
+    planned_type = Prompt
+
+    def parse(
+        self, source: dict[str, Any], name: str, description: str, path: str
+    ) -> Prompt:
+        return Prompt(description or name)
+
+    def validate(self, definition: Prompt, path: str) -> None:
+        if not definition.text:
+            raise ConfigurationError(f"{path} prompt requires text")
+
+    def override_definition(
+        self,
+        local: Prompt,
+        inherited: Prompt,
+        context: DefinitionOverrideContext,
+    ) -> Prompt:
+        """A prompt step inherits catalog text until it supplies a description."""
+        return Prompt(
+            context.local_description or context.local_name
+            if context.description_is_explicit
+            else inherited.text
+        )
+
+    def templates(self, definition: Prompt) -> tuple[str, ...]:
+        return (definition.text,)
+
+    def plan(self, definition: Prompt, context: ResolutionContext) -> Prompt:
+        return Prompt(context.interpolate(definition.text))
+
+    def instruction(
+        self, planned: Prompt, context: InstructionContext
+    ) -> InstructionContent:
+        text = (
+            interpolate(planned.text, context.task_values)
+            if context.task_values
+            else planned.text
+        )
+        return InstructionContent(
+            text or context.description or context.name,
+            ("**Prompt**", "", text, ""),
+            show_context=text != context.description,
+            include_item_context=True,
+        )
+
+    def encode(self, planned: Prompt) -> dict[str, object]:
+        return {"text": planned.text}
+
+    def decode(self, data: dict[str, Any]) -> Prompt:
+        expect_keys(data, {"text"}, f"action {self.identifier!r} payload")
+        return Prompt(expect_string(data["text"], "prompt text"))

ww/actions/skill.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Skill action."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ww.errors import ConfigurationError
+from ww.validation import expect_keys, expect_string
+
+from .contracts import (
+    Action,
+    ActionTraits,
+    InstructionContent,
+    InstructionContext,
+    ResolutionContext,
+    Skill,
+)
+
+
+class SkillAction(Action[Skill, Skill]):
+    identifier = "skill"
+    planned_type = Skill
+
+    def parse(
+        self, source: dict[str, Any], name: str, description: str, path: str
+    ) -> Skill:
+        # ``kind: skill`` (or ``action: {type: skill}``) already chose this
+        # action; the skill is the handler's name.
+        return Skill(name)
+
+    def validate(self, definition: Skill, path: str) -> None:
+        if not definition.name:
+            raise ConfigurationError(f"{path} skill requires a name")
+
+    def templates(self, definition: Skill) -> tuple[str, ...]:
+        return ()
+
+    def plan(self, definition: Skill, context: ResolutionContext) -> Skill:
+        if definition.name not in context.available.skills:
+            raise ConfigurationError(
+                f"configured skill not found for {context.agent}: {definition.name}"
+            )
+        return Skill(context.interpolate(definition.name))
+
+    def instruction(
+        self, planned: Skill, context: InstructionContext
+    ) -> InstructionContent:
+        text = f"Use the `{planned.name}` skill." + (
+            f" {context.description}" if context.description else ""
+        )
+        return InstructionContent(text, ("**Use skill**", "", f"`{planned.name}`", ""))
+
+    def traits(self, planned: Skill) -> ActionTraits:
+        return ActionTraits(artifact_attribution=planned.name)
+
+    def encode(self, planned: Skill) -> dict[str, object]:
+        return {"name": planned.name}
+
+    def decode(self, data: dict[str, Any]) -> Skill:
+        expect_keys(data, {"name"}, f"action {self.identifier!r} payload")
+        return Skill(expect_string(data["name"], "skill name"))

ww/actions/slash_command.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Slash-command action."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ww.errors import ConfigurationError
+from ww.validation import expect_keys, expect_string
+
+from .contracts import (
+    Action,
+    InstructionContent,
+    InstructionContext,
+    ResolutionContext,
+    SlashCommand,
+)
+
+
+class SlashCommandAction(Action[SlashCommand, SlashCommand]):
+    identifier = "slash_command"
+    planned_type = SlashCommand
+
+    def parse(
+        self, source: dict[str, Any], name: str, description: str, path: str
+    ) -> SlashCommand:
+        # ``kind: slash_command`` already chose this action; the command is
+        # the handler's name.
+        return SlashCommand(name)
+
+    def validate(self, definition: SlashCommand, path: str) -> None:
+        if not definition.name:
+            raise ConfigurationError(f"{path} slash command requires a name")
+
+    def templates(self, definition: SlashCommand) -> tuple[str, ...]:
+        return ()
+
+    def plan(
+        self, definition: SlashCommand, context: ResolutionContext
+    ) -> SlashCommand:
+        if definition.name not in context.available.slash_commands:
+            raise ConfigurationError(
+                f"configured slash command not found for {context.agent}: "
+                f"{definition.name}"
+            )
+        return SlashCommand(context.interpolate(definition.name))
+
+    def instruction(
+        self, planned: SlashCommand, context: InstructionContext
+    ) -> InstructionContent:
+        text = f"Run the `/{planned.name}` slash command." + (
+            f" {context.description}" if context.description else ""
+        )
+        return InstructionContent(
+            text, ("**Run slash command**", "", f"`/{planned.name}`", "")
+        )
+
+    def encode(self, planned: SlashCommand) -> dict[str, object]:
+        return {"name": planned.name}
+
+    def decode(self, data: dict[str, Any]) -> SlashCommand:
+        expect_keys(data, {"name"}, f"action {self.identifier!r} payload")
+        return SlashCommand(expect_string(data["name"], "slash command name"))

ww/agents.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""What each agent integration can do for the operator, beyond plain text.
+
+A workflow declares operator ``choices`` abstractly; how the agent presents
+them so the operator can pick with the keyboard depends on the agent.  This
+table is core knowledge, not an extension point: an unknown agent gets the
+plain-text fallback, which every agent can honour.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ww.discovery import normalize_agent
+from ww.errors import ConfigurationError
+
+
+@dataclass(frozen=True)
+class ChoiceMechanism:
+    """How one agent presents a set of choices to the operator."""
+
+    name: str
+    instruction: str
+
+
+PLAIN_TEXT = ChoiceMechanism(
+    "plain text",
+    "Present the choices as a numbered list in your reply, exactly in this "
+    "order, and ask the operator to answer with the number or the label.",
+)
+
+# Question-tool availability varies by host and session, so each instruction
+# ends in the fallback every agent can honour.
+_FALLBACK = (
+    " If the tool is not available in this session, present the choices as a "
+    "numbered list instead and ask the operator to answer with the number or "
+    "the label."
+)
+
+
+def _tool(tool: str, picks: str) -> ChoiceMechanism:
+    return ChoiceMechanism(
+        tool,
+        f"Present the matter in your reply first, then ask with the `{tool}` "
+        "tool: one short question of a line or two, never the matter itself, "
+        "these options in this order with their descriptions, single select. "
+        f"{picks}" + _FALLBACK,
+    )
+
+
+# Tool names for Cursor, Antigravity, and Grok CLI, and the mode caveats, are
+# taken from the askmux question-tool matrix (https://github.com/iShaldam/askmux,
+# MIT, Copyright (c) 2026 iShaldam); Gemini CLI's from its documentation
+# (https://geminicli.com/docs/tools/ask-user/). Kimi and DeepSeek document no
+# such tool and use the plain-text list.
+CHOICE_MECHANISMS: dict[str, ChoiceMechanism] = {
+    "claudecode": _tool(
+        "AskUserQuestion",
+        "The operator picks with the keyboard; a free-form answer through "
+        '"Other" is a comment, not a choice.',
+    ),
+    "codex": ChoiceMechanism(
+        "host question tool",
+        "Present the matter in your reply first. Inspect the host's available "
+        "question-tool schema and follow its supported fields, using structured "
+        "options when offered and a text-only question only when required. "
+        "Keep the choice pending until the operator explicitly answers; a "
+        "timeout, dismissal, or preselected value is not an answer. If no "
+        "suitable question tool is available, present the choices as a numbered "
+        "list and ask for the number or label.",
+    ),
+    "gemini": _tool(
+        "ask_user",
+        "Use a question of type `choice`. A free-form answer is a comment, not "
+        "a choice.",
+    ),
+    "cursor": _tool(
+        "AskQuestion",
+        "A free-form answer is a comment, not a choice.",
+    ),
+    "antigravity": _tool(
+        "ask_question",
+        "A free-form answer is a comment, not a choice.",
+    ),
+    "grok": _tool(
+        "ask_user_question",
+        "A free-form answer is a comment, not a choice.",
+    ),
+}
+
+
+@dataclass(frozen=True)
+class WaitMechanism:
+    """How one agent runs a command that waits for the operator.
+
+    An agent with a background shell keeps its session free while the wait
+    runs and hears the result when the command returns; such a wait may be
+    long.  Any other agent blocks on the command, so the wait stays under
+    its shell timeout.
+    """
+
+    background: bool
+    wait_seconds: int | None
+    instruction: str
+
+
+FOREGROUND = WaitMechanism(
+    False,
+    None,
+    "The command blocks until it returns; run nothing else while it waits, "
+    "and run it again while items remain.",
+)
+
+# The environment variable that bounds one wait, and the bound a background
+# wait gets: half an hour, long enough for a real session of manual testing,
+# short enough that a forgotten wait ends on its own.
+WAIT_VARIABLE = "WW_OPERATOR_WAIT"
+BACKGROUND_WAIT_SECONDS = 1800
+
+WAIT_MECHANISMS: dict[str, WaitMechanism] = {
+    "claudecode": WaitMechanism(
+        True,
+        BACKGROUND_WAIT_SECONDS,
+        "Run the command in the background with your shell tool's "
+        "`run_in_background` option and go on with the conversation; its "
+        "output reaches you when it returns. While it runs, do not run "
+        "commands that change this task, because the wait applies the answers "
+        "the moment it ends; `status` and `instruction` are fine. Run it again "
+        "while items remain.",
+    ),
+}
+
+
+def wait_mechanism(agent: str) -> WaitMechanism:
+    """The mechanism for ``agent``; a blocking wait when it has no background."""
+    try:
+        name = normalize_agent(agent)
+    except ConfigurationError:
+        # An unknown spelling still gets the fallback every agent can honour.
+        return FOREGROUND
+    return WAIT_MECHANISMS.get(name, FOREGROUND)
+
+
+def choice_mechanism(agent: str) -> ChoiceMechanism:
+    """The mechanism for ``agent``; plain text when it has no structured one."""
+    try:
+        name = normalize_agent(agent)
+    except ConfigurationError:
+        # An unknown spelling still gets the fallback every agent can honour.
+        return PLAIN_TEXT
+    return CHOICE_MECHANISMS.get(name, PLAIN_TEXT)

ww/amendments.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Amendments to a task's recorded requirements.
+
+The requirements ``init`` saved are never rewritten; a later clarification is
+appended as an amendment with its time and who recorded it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ww.validation import expect_nonempty_string, expect_string
+
+
+@dataclass(frozen=True)
+class Amendment:
+    """One short addition to a task's requirements."""
+
+    at: str
+    role: str
+    text: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"at": self.at, "role": self.role, "text": self.text}
+
+    @classmethod
+    def from_dict(cls, data: object) -> Amendment:
+        if not isinstance(data, dict):
+            raise ValueError("amendment must be a mapping")
+        return cls(
+            at=expect_nonempty_string(data.get("at"), "amendment time"),
+            role=expect_string(data.get("role"), "amendment role"),
+            text=expect_nonempty_string(data.get("text"), "amendment text"),
+        )
+
+
+# Amendments are clarifications, not a second requirements document.
+MAX_AMENDMENT_LENGTH = 1000
+
+
+@dataclass(frozen=True)
+class TaskRequirements:
+    """A task's recorded requirements and the amendments appended to them."""
+
+    task_id: str
+    text: str | None
+    amendments: tuple[Amendment, ...]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "task_id": self.task_id,
+            "requirements": self.text,
+            "amendments": [entry.to_dict() for entry in self.amendments],
+        }