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

ww/plan/actions.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Handler references and registry-based action planning."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from ww.actions import (
+    ActionPayload,
+    AutomaticAction,
+    DefinedAction,
+    Extension,
+    Prompt,
+    ResolutionContext,
+    Skill,
+    SlashCommand,
+    actions,
+)
+from ww.contracts import PlanItemKind, PlanItemOwner
+from ww.discovery import AvailableActions
+from ww.errors import ConfigurationError
+from ww.extensions import ExtensionRegistry, is_extension_reference
+from ww.workflow_config import (
+    HandlerDefinition,
+    StepDefinition,
+    WorkflowConfiguration,
+)
+from ww.workspace import Workdir
+
+
+class ActionResolver:
+    """Resolve handlers without taking part in plan ordering or item allocation."""
+
+    def __init__(
+        self,
+        configuration: WorkflowConfiguration,
+        agent: str,
+        extensions: ExtensionRegistry | None,
+        available: AvailableActions,
+        builtins: dict[str, str],
+        project: str | None = None,
+    ) -> None:
+        self.configuration = configuration
+        self.agent = agent
+        self.extensions = extensions
+        self.available = available
+        self.builtins = builtins
+        self.project = project
+
+    def _handler(
+        self, value: HandlerDefinition, *, resolve_reference: bool = False
+    ) -> tuple[HandlerDefinition, str | None, HandlerDefinition | None]:
+        if not resolve_reference or not value.is_reference:
+            return value, None, None
+        if is_extension_reference(value.name):
+            definition = self._extension_handler(value.name, value.extension_arguments)
+            return replace(definition), value.name, definition
+        registered = self.configuration.handlers_by_name.get(value.name)
+        if registered is not None:
+            return (
+                replace(
+                    registered,
+                    on_failure=value.on_failure
+                    if value.on_failure is not None
+                    else registered.on_failure,
+                    on_failure_instruction=value.on_failure_instruction
+                    or registered.on_failure_instruction,
+                    workdir=value.workdir or registered.workdir,
+                    agent=value.agent or registered.agent,
+                    model=value.model or registered.model,
+                    reasoning=value.reasoning or registered.reasoning,
+                ),
+                registered.name,
+                registered,
+            )
+        return value, None, None
+
+    def automatic_members(
+        self,
+        value: HandlerDefinition,
+        stack: tuple[str, ...] = (),
+    ) -> tuple[HandlerDefinition, ...]:
+        """Flatten an automated group, resolving references and inheriting defaults."""
+        handler, _, _ = self._handler(value, resolve_reference=True)
+        if handler.handlers:
+            if handler.name != "inline-handlers" and handler.name in stack:
+                raise ConfigurationError(
+                    "handler group cycle: " + " -> ".join((*stack, handler.name))
+                )
+            result: list[HandlerDefinition] = []
+            for member in handler.handlers:
+                resolved, _, _ = self._handler(member, resolve_reference=True)
+                inherited = replace(
+                    resolved,
+                    on_failure=resolved.on_failure
+                    if resolved.on_failure is not None
+                    else handler.on_failure,
+                    on_failure_instruction=resolved.on_failure_instruction
+                    or handler.on_failure_instruction,
+                    workdir=resolved.workdir or handler.workdir,
+                    agent=resolved.agent or handler.agent,
+                    model=resolved.model or handler.model,
+                    reasoning=resolved.reasoning or handler.reasoning,
+                )
+                result.extend(self.automatic_members(inherited, (*stack, handler.name)))
+            return tuple(result)
+        if (
+            handler.operation is not None
+            or isinstance(handler, StepDefinition)
+            and (
+                handler.child_steps
+                or handler.loop_steps
+                or handler.items
+                or handler.children
+                or handler.assessment_outcomes
+                or handler.interactive
+                or handler.hooks
+                or handler.rules
+            )
+        ):
+            raise ConfigurationError(
+                f"handler group member {handler.name!r} must be an automated action"
+            )
+        kind, owner, _ = self._resolve(handler)
+        if (
+            owner != "ww"
+            or not isinstance(actions.get(kind), AutomaticAction)
+            or handler.provide
+        ):
+            raise ConfigurationError(
+                f"handler group member {handler.name!r} must be fully automated "
+                "and require no agent input"
+            )
+        return (handler,)
+
+    def _extension_handler(
+        self, value: str, arguments: tuple[str, ...] = ()
+    ) -> HandlerDefinition:
+        if self.extensions is None:
+            raise ConfigurationError(
+                f"{value!r} references an extension, but no extensions are loaded"
+            )
+        handler = self.extensions.handler(value)
+        if len(arguments) != len(handler.arguments):
+            expected = (
+                f"takes {len(handler.arguments)} args ("
+                + ", ".join(handler.arguments)
+                + ")"
+                if handler.arguments
+                else "takes no args"
+            )
+            raise ConfigurationError(f"{value!r} {expected}; {len(arguments)} given")
+        return HandlerDefinition(
+            handler.name,
+            description=handler.description,
+            provide=handler.provide,
+            outputs=handler.outputs,
+            action=DefinedAction("extension", Extension(value, arguments=arguments)),
+        )
+
+    def _resolve(
+        self, handler: HandlerDefinition
+    ) -> tuple[PlanItemKind, PlanItemOwner, DefinedAction]:
+        """Normalize implicit discovery once, then dispatch through the registry."""
+        if isinstance(handler.action, DefinedAction):
+            kind = handler.action.identifier
+            return kind, actions.get(kind).owner, handler.action
+        if handler.name in self.available.skills:
+            payload: ActionPayload = Skill(handler.name)
+            kind = "skill"
+        elif handler.name in self.available.slash_commands:
+            payload = SlashCommand(handler.name)
+            kind = "slash_command"
+        else:
+            payload = Prompt(handler.description or handler.name)
+            kind = "prompt"
+        return kind, actions.get(kind).owner, DefinedAction(kind, payload)
+
+    def plan_action(
+        self, action: DefinedAction, allowed: set[str], workdir: Workdir = "task"
+    ) -> object:
+        """Plan one action as the item working in ``workdir`` will run it.
+
+        An item working in the root follows the root's extension settings;
+        one working in the task workspace or the project directory follows
+        the run's project, when it has one.
+        """
+        context = ResolutionContext(
+            self.agent,
+            self.available,
+            self.extensions,
+            self.builtins,
+            frozenset(allowed),
+            project=self.project if workdir != "root" else None,
+        )
+        return actions.get(action.identifier).plan(action.payload, context)
+
+    def _interpolate(self, value: object, allowed: set[str]) -> str:
+        if not isinstance(value, str):
+            raise AssertionError("plan actions must be strings")
+        return ResolutionContext(
+            self.agent,
+            self.available,
+            self.extensions,
+            self.builtins,
+            frozenset(allowed),
+        ).interpolate(value)