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

ww/instructions/policy.py

@@ -0,0 +1,219 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Pure execution-state interpretation for instructions."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from ww.actions import actions
+from ww.assignments import active_assignment, input_only
+from ww.contracts import (
+    Control,
+    InstructionStatus,
+    ItemStatus,
+    NextRole,
+    OperatorReason,
+    PlanItemKind,
+)
+from ww.control import child_workflow, loop_control, replays_harmlessly
+from ww.errors import StateError
+from ww.execution_models import ExecutionState
+from ww.handler_repairs import needs_repair
+from ww.plan import WorkflowPlan
+from ww.transitions import loop_limit_reached
+from ww.validation import expect_literal
+
+from .models import Instruction
+
+
+class Audience(Enum):
+    """Who reads an instruction and what they are expected to do with it."""
+
+    SINGLE_SESSION = "single"
+    """One session plays both roles and does the work itself."""
+    MANAGER_DELEGATING = "manager_delegating"
+    """The manager hands the next assignment to a worker."""
+    WORKER_RETURNING = "worker_returning"
+    """A worker has finished its assignment and returns control."""
+    WORKER = "worker"
+    """A worker performs the active assignment."""
+    MANAGER = "manager"
+    """The manager runs the next command itself."""
+
+
+def audience(instruction: Instruction) -> Audience:
+    if instruction.workflow_runtime == "single":
+        return Audience.SINGLE_SESSION
+    if instruction.caller_role == "manager" and instruction.next_role == "worker":
+        return Audience.MANAGER_DELEGATING
+    if instruction.caller_role == "worker" and instruction.next_role in {
+        "manager",
+        "operator",
+    }:
+        return Audience.WORKER_RETURNING
+    return Audience.WORKER if instruction.next_role == "worker" else Audience.MANAGER
+
+
+def manager_continues_itself(instruction: Instruction) -> bool:
+    """Whether the step a manager's completion hands back is the manager's own.
+
+    Then ``next`` has nothing to decide for the manager: no worker is selected,
+    nothing waits for the operator, no assessment outcome is to be chosen, and
+    no loop, child, repair, or plan change needs a deliberate command.
+    """
+    return (
+        instruction.workflow_runtime == "auto"
+        and instruction.caller_role == "manager"
+        and instruction.next_role == "manager"
+        and instruction.role == "manager"
+        and instruction.control == "handoff_manager"
+        and instruction.status == "pending"
+        and instruction.item_status == "pending"
+        and instruction.operator_reason is None
+        and instruction.choosing_outcome_of is None
+        and instruction.plan_change is None
+        and instruction.fix_required is None
+        and instruction.handler_repair is None
+        and instruction.error is None
+        and not instruction.is_loop_control
+        and not instruction.is_child_workflow_control
+        and not instruction.manager_only
+    )
+
+
+def _instruction_status(value: str) -> InstructionStatus:
+    status: InstructionStatus = expect_literal(
+        value, InstructionStatus, "bootstrap request status", error=StateError
+    )
+    return status
+
+
+def _item_status(value: str) -> ItemStatus:
+    status: ItemStatus = expect_literal(
+        value, ItemStatus, "bootstrap request item status", error=StateError
+    )
+    return status
+
+
+def _plan_item_kind(value: str) -> PlanItemKind:
+    if not actions.contains(value):
+        raise StateError(f"bootstrap request has invalid action kind: {value!r}")
+    return value
+
+
+def _has_previous_artifacts(state: ExecutionState, plan: WorkflowPlan) -> bool:
+    return any(
+        record.artifact is not None
+        for index, (item, record) in enumerate(
+            zip(plan.items, state.item_executions, strict=True)
+        )
+        if index < state.cursor and record.status == "completed"
+    )
+
+
+def _next_steps(state: ExecutionState, plan: WorkflowPlan) -> tuple[str, ...]:
+    current = plan.items[state.cursor]
+    if current.phase != "step":
+        return ()
+    return tuple(
+        dict.fromkeys(
+            item.step
+            for item in plan.items[state.cursor + 1 :]
+            if item.phase == "step"
+            and item.parent == current.parent
+            and item.step != current.step
+        )
+    )
+
+
+def _index_for_id(plan: WorkflowPlan, item_id: str) -> int:
+    for index, item in enumerate(plan.items):
+        if item.id == item_id:
+            return index
+    raise StateError(f"plan item {item_id!r} is not in the task snapshot")
+
+
+def operator_reason(state: ExecutionState, plan: WorkflowPlan) -> OperatorReason | None:
+    """Why the task waits for the operator, or ``None`` when it does not."""
+    item = plan.items[state.cursor] if state.cursor < len(plan.items) else None
+    if state.status == "interrupted":
+        # ``next`` replays a harmless handler without asking anyone.
+        if item is not None and replays_harmlessly(item):
+            return None
+        return "handler_interrupted"
+    if state.status == "failed":
+        if state.failure_kind is not None:
+            return state.failure_kind
+        if item is not None and child_workflow(item) is not None:
+            return "child_failed"
+        if item is not None and item.owner == "agent":
+            return "work_failed"
+        return "handler_failed"
+    if (
+        state.status != "awaiting_input"
+        and item is not None
+        and loop_limit_reached(state, item)
+    ):
+        return "loop_limit"
+    return None
+
+
+def _control(state: ExecutionState, plan: WorkflowPlan) -> tuple[Control, NextRole]:
+    if operator_reason(state, plan) is not None:
+        return "awaiting_operator", "operator"
+    if state.status in {"failed", "interrupted"}:
+        return "blocked", "manager"
+    if state.status in {"completed", "abandoned"}:
+        return "handoff_manager", "manager"
+    if needs_repair(state):
+        return (
+            ("continue_worker", "worker")
+            if state.active_item_id
+            else ("handoff_manager", "manager")
+        )
+    if state.status == "awaiting_input":
+        assignment = active_assignment(
+            plan, state.assignment_item_id, runtime=state.workflow_runtime
+        )
+        if (
+            state.workflow_runtime == "auto"
+            and assignment is not None
+            and input_only(plan, assignment)
+        ):
+            return "handoff_manager", "manager"
+        return "continue_worker", "worker"
+    if state.cursor < len(plan.items):
+        item = plan.items[state.cursor]
+        record = state.item_executions[state.cursor]
+        if (
+            item.owner == "ww"
+            and item.execution == "automatic"
+            and record.status == "in_progress"
+        ):
+            return "blocked", "manager"
+    if state.cursor < len(plan.items) and (
+        child_workflow(plan.items[state.cursor]) is not None
+        or loop_control(plan.items[state.cursor]) is not None
+    ):
+        return "blocked", "manager"
+    assignment = active_assignment(
+        plan, state.assignment_item_id, runtime=state.workflow_runtime
+    )
+    if assignment is not None and state.cursor < assignment.stop:
+        return "continue_worker", "worker"
+    if state.active_item_id and state.cursor < len(plan.items):
+        return "continue_worker", "worker"
+    return "handoff_manager", "manager"
+
+
+def _result_saved(state: ExecutionState, plan: WorkflowPlan) -> bool:
+    assignment = active_assignment(
+        plan, state.assignment_item_id, runtime=state.workflow_runtime
+    )
+    start = assignment.start if assignment is not None else 0
+    stop = min(state.cursor + 1, len(plan.items))
+    return any(
+        plan.items[index].owner == "agent"
+        and state.item_executions[index].status == "completed"
+        for index in range(start, stop)
+    )

ww/instructions/text.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Instruction wording and continuation command construction."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ww.actions import InstructionContext, PlannedAction, actions
+from ww.plan import PlanItem
+from ww.variables import PROJECTS
+
+from .commands import (
+    TASK_PLACEHOLDER,
+    add_child_command,
+    add_item_command,
+    item_command,
+    items_command,
+    update_item_command,
+)
+
+NO_SUBAGENTS = (
+    "This step allows no subagents (`subagents: false`): whoever performs it "
+    "does all of its work alone and spawns no subagent for anything, not for "
+    "research, tests, or review."
+)
+
+
+@dataclass(frozen=True)
+class ContainerArtifact:
+    """The artifact ``artifact_from`` naming a group or an assessment found.
+
+    ``step`` and ``artifact`` (an absolute path) name the latest step inside
+    the container that saved one in its current round, or the assessment
+    itself when its outcome saved none; both are ``None`` when none has.
+    """
+
+    step: str | None = None
+    artifact: str | None = None
+
+
+def _stage(item: PlanItem | None) -> str | None:
+    if item is None:
+        return None
+    if item.phase == "step":
+        return "Nested workflow step" if item.parent else "Workflow step"
+    if item.phase == "before_start_workflow":
+        return "Before Workflow Start hook"
+    if item.phase == "before_complete_workflow":
+        return "Before Workflow Completion hook"
+    return item.phase.replace("_", " ").title() + " hook"
+
+
+def action_text(
+    item: PlanItem,
+    task_values: dict[str, str] | None = None,
+    task_id: str | None = None,
+    container_artifact: ContainerArtifact | None = None,
+    later_pass: bool = False,
+) -> str:
+    """Render the work text for an ordinary action, plus item or child guidance.
+
+    ``later_pass``: the step collects for an ``items`` pass after the
+    workflow's first, which reuses the items already collected.
+
+    ``container_artifact`` is what the step's ``artifact_from`` resolved to
+    when it names a group or an assessment; ``None`` for a single step.
+    """
+    if not isinstance(item.operation, PlannedAction):
+        raise ValueError(f"core operation {item.kind!r} has no ordinary action text")
+    content = actions.get(item.operation.identifier).instruction(
+        item.operation.payload,
+        InstructionContext(item.description, item.name, task_values or {}),
+    )
+    task_reference = task_id or TASK_PLACEHOLDER
+    if item.item_operation == "collect" and later_pass:
+        result = (
+            content.text
+            + "\n\nThis step starts a later pass over the items this run already "
+            "collected: do not split the source again or recreate items, and keep "
+            "what is recorded on them. Inspect them with "
+            f"`{items_command(task_reference)}`. Add an item with "
+            f"`{add_item_command(task_reference)}` only when this step asks you "
+            "to reconcile the items with their source. When this step completes, "
+            "the pass runs for the items recorded by then; an item added later "
+            "joins the next pass."
+        )
+        return _with_artifact_dependency(result, item, container_artifact)
+    if item.item_operation == "collect":
+        result = (
+            content.text
+            + "\n\nSplit the source into complete, reportable items. Preserve every "
+            "source comment; use a stable source ID when one exists, otherwise choose "
+            f"a unique ID. Use `{add_item_command()}` for "
+            "each item. Combine related work under one canonical item only when that "
+            "avoids duplicate analysis or fixes; retain each related source item and "
+            "link it with `--refers-to <canonical-id>` so it can still be "
+            "reported."
+        )
+        if item.split_instruction:
+            result += f"\n\nHow to split: {item.split_instruction}"
+        return _with_artifact_dependency(result, item, container_artifact)
+    if item.child_operation == "collect":
+        projects = [
+            name for name in (task_values or {}).get(PROJECTS, "").split(",") if name
+        ]
+        result = (
+            content.text
+            + "\n\nRecord each child task with:\n\n```console\n"
+            + add_child_command(
+                task_reference, project=bool(projects), identity=item.child_identity
+            )
+            + "\n```\n\nRun this command once for every independent child task."
+        )
+        if item.split_instruction:
+            result += f"\n\nHow to split: {item.split_instruction}"
+        if item.child_identity:
+            result += (
+                "\n\nDo not pass `--id`: each child receives its ID from the first "
+                "step of its own workflow, which runs when the child starts."
+            )
+        if projects:
+            result += (
+                "\n\nConfigured projects: "
+                + ", ".join(f"`{name}`" for name in projects)
+                + ". Pass `--project` with the project a child works in; omit it "
+                "for a child that works in the root."
+            )
+        return _with_artifact_dependency(result, item, container_artifact)
+    text = content.text
+    if content.include_item_context and item.item_id:
+        text += (
+            f"\n\nActive item: `{item.item_id}`. Inspect it with "
+            f"`{item_command(task_reference, item.item_id)}`."
+            " Save progress with:\n\n```console\n"
+            + update_item_command(task_reference, item.item_id, item.item_operation)
+            + "\n```\n\nThis command confirms the update and returns the worker "
+            "completion command."
+        )
+    return _with_artifact_dependency(text, item, container_artifact)
+
+
+def _with_artifact_dependency(
+    text: str, item: PlanItem, container: ContainerArtifact | None
+) -> str:
+    if item.artifact_dependency is None:
+        return text
+    if container is not None and container.artifact is None:
+        return (
+            text + f"\n\nNo artifact is available from `{item.artifact_dependency}`: "
+            "no step inside it that saves one completed in this run. Continue "
+            "without it."
+        )
+    if container is not None and container.step == item.artifact_dependency:
+        return (
+            text + f"\n\nUse the artifact produced by the `{container.step}` step as "
+            f"input to this work: `{container.artifact}`."
+        )
+    if container is not None:
+        return (
+            text + f"\n\nUse the artifact produced by the `{container.step}` step, "
+            f"the latest saved inside `{item.artifact_dependency}`, as input to "
+            f"this work: `{container.artifact}`."
+        )
+    return (
+        text
+        + f"\n\nUse the artifact produced by the `{item.artifact_dependency}` step "
+        "as input to this work."
+    )

ww/interactions.py

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The per-task record of conversations held with the operator.
+
+An interactive step is a conversation the agent holds with the operator in
+its own session; ww cannot hear it.  When the conversation ends, the agent
+records both sides at once with ``interact --transcript``, and ww appends
+each entry to one file per task, ``interactions.md``, never rewriting it.
+The ``interrupt`` hook appends what it recovers from the agent's own
+transcript the same way, under a speaker marked ``(recovered)``.  Every entry names the
+run and step it belongs to, and the work item when the step is a per-item
+stage, so the file reads as the task's whole history of operator involvement
+and the conversation of one stage can be read back out of it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from ww.errors import StateError
+from ww.storage import Storage
+
+INTERACTIONS_FILE = "interactions.md"
+_SEPARATOR = " · "
+# A heading has time, run, step, and speaker; a per-item stage adds its item.
+_FIELDS = 4
+# Appended to the speaker of an entry the interrupt hook recovered.
+RECOVERED = " (recovered)"
+# A transcript line that starts an entry: a speaker marker in any case, plain
+# or bold with the colon inside or outside the bold, then the entry's first
+# line, e.g. "**Operator:** Use a queue." or "agent: I propose a queue.".
+_MARKER = re.compile(
+    r"^\s*(?:\*\*)?(Agent|Operator)(?:\*\*)?:(?:\*\*)?\s*(.*)$", re.IGNORECASE
+)
+_TRANSCRIPT_FORMAT = (
+    "a transcript is lines starting with `Agent:` or `Operator:`, each "
+    "followed by that side's words; the lines until the next marker belong "
+    "to the same entry"
+)
+
+
+@dataclass(frozen=True)
+class InteractionEntry:
+    """One recorded entry: who said what, in which run, step, and item."""
+
+    at: str
+    run_id: str | None
+    step: str
+    item_id: str | None
+    speaker: str
+    text: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "at": self.at,
+            "run_id": self.run_id,
+            "step": self.step,
+            "item_id": self.item_id,
+            "speaker": self.speaker,
+            "text": self.text,
+        }
+
+
+class InteractionLog:
+    def __init__(self, storage: Storage) -> None:
+        self.storage = storage
+
+    def path(self, task_id: str) -> Path:
+        return self.storage.runtime_path / "tasks" / task_id / INTERACTIONS_FILE
+
+    def append(
+        self,
+        task_id: str,
+        *,
+        run_id: str | None,
+        step: str,
+        speaker: str,
+        text: str,
+        at: str,
+        item_id: str | None = None,
+    ) -> None:
+        """Append one entry; the file is created with a title on first use."""
+        self.append_entries(
+            task_id,
+            ((speaker, text),),
+            run_id=run_id,
+            step=step,
+            at=at,
+            item_id=item_id,
+        )
+
+    def append_entries(
+        self,
+        task_id: str,
+        spoken: Sequence[tuple[str, str]],
+        *,
+        run_id: str | None,
+        step: str,
+        at: str,
+        item_id: str | None = None,
+    ) -> None:
+        """Append ``(speaker, text)`` entries in order, in one write."""
+        if not spoken:
+            return
+        path = self.path(task_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fields = [at, run_id or "-", step]
+        if item_id is not None:
+            fields.append(item_id)
+        chunks = []
+        for speaker, text in spoken:
+            chunks.append(f"## {_SEPARATOR.join([*fields, speaker])}\n\n")
+            if text.strip():
+                chunks.append(text.strip() + "\n\n")
+        with path.open("a", encoding="utf-8") as handle:
+            if handle.tell() == 0:
+                handle.write(f"# {task_id} — interactions with the operator\n\n")
+            handle.write("".join(chunks))
+
+    def read(self, task_id: str) -> str:
+        path = self.path(task_id)
+        return path.read_text(encoding="utf-8") if path.is_file() else ""
+
+    def entries(self, task_id: str) -> tuple[InteractionEntry, ...]:
+        """Read the record back as entries, in the order they were appended."""
+        result: list[InteractionEntry] = []
+        heading: InteractionEntry | None = None
+        body: list[str] = []
+        for line in self.read(task_id).splitlines():
+            parsed = _parse_heading(line)
+            if parsed is None:
+                body.append(line)
+                continue
+            if heading is not None:
+                result.append(replace(heading, text="\n".join(body).strip()))
+            heading, body = parsed, []
+        if heading is not None:
+            result.append(replace(heading, text="\n".join(body).strip()))
+        return tuple(result)
+
+    def remove(self, task_id: str) -> None:
+        """Forget a task's record, as part of resetting the task."""
+        self.path(task_id).unlink(missing_ok=True)
+
+
+def parse_transcript(text: str) -> tuple[tuple[str, str], ...]:
+    """A plain transcript as ordered ``(speaker, text)`` entries.
+
+    Speakers are ``operator`` and ``agent``; an entry with no words is
+    dropped.  Text before the first marker, or no entry at all, is refused.
+    """
+    entries: list[tuple[str, list[str]]] = []
+    for line in text.splitlines():
+        match = _MARKER.match(line)
+        if match is not None:
+            entries.append((match.group(1).lower(), [match.group(2)]))
+        elif entries:
+            entries[-1][1].append(line)
+        elif line.strip():
+            raise StateError(
+                f"the transcript starts with {line.strip()[:40]!r}; "
+                + _TRANSCRIPT_FORMAT
+            )
+    result = tuple(
+        (speaker, "\n".join(lines).strip())
+        for speaker, lines in entries
+        if "\n".join(lines).strip()
+    )
+    if not result:
+        raise StateError("the transcript has no entries; " + _TRANSCRIPT_FORMAT)
+    return result
+
+
+def _parse_heading(line: str) -> InteractionEntry | None:
+    """An entry heading: time, run, step, an optional item, and the speaker."""
+    if not line.startswith("## "):
+        return None
+    fields = line[3:].split(_SEPARATOR)
+    if len(fields) not in (_FIELDS, _FIELDS + 1):
+        return None
+    at, run_id, step = fields[:3]
+    item_id = fields[3] if len(fields) > _FIELDS else None
+    return InteractionEntry(
+        at, None if run_id == "-" else run_id, step, item_id, fields[-1], ""
+    )

ww/interpolation.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Interpolation analysis for normalized workflow definitions."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+from ww.errors import ConfigurationError
+
+# One {{name}} template token, spaces inside the braces allowed:
+# "{{ ww.task.id }}" and "{{metadata.owner}}" both match.
+_TOKEN = re.compile(
+    r"\{\{\s*([A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*)\s*\}\}"
+)
+# Double-braced text that is not a valid token, e.g. "{{ not a name }}".
+_BRACES = re.compile(r"\{\{.*?\}\}")
+
+
+def dependencies(value: str) -> tuple[str, ...]:
+    """Return ordered interpolation names and reject malformed tokens."""
+    names = tuple(match.group(1) for match in _TOKEN.finditer(value))
+    normalized = _TOKEN.sub("", value)
+    if "{{" in normalized or "}}" in normalized or _BRACES.search(normalized):
+        raise ConfigurationError(f"invalid interpolation in {value!r}")
+    return names
+
+
+def interpolate(value: str, variables: Mapping[str, str]) -> str:
+    """Bind values that are available, preserving declared unresolved tokens."""
+    dependencies(value)
+
+    def replace(match: re.Match[str]) -> str:
+        name = match.group(1)
+        return variables.get(name, match.group(0))
+
+    return _TOKEN.sub(replace, value)