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

ww/cli/prompts.py

@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Operator confirmations read from the terminal."""
+
+from __future__ import annotations
+
+import os
+import sys
+import termios
+import tty
+
+
+def _ask_choice(prompt: str, choices: tuple[str, ...], default: str) -> str:
+    while True:
+        value = input(prompt).strip().lower() or default
+        if value in choices:
+            return value
+        print("Choose one of: " + ", ".join(choices) + ".")
+
+
+def _interactive_terminal() -> bool:
+    """Whether the operator can drive a redrawing prompt."""
+    return (
+        sys.stdin.isatty()
+        and sys.stdout.isatty()
+        and os.environ.get("TERM") not in {None, "", "dumb"}
+    )
+
+
+def _ask_checklist(
+    heading: str, options: tuple[tuple[str, str, bool], ...]
+) -> tuple[str, ...]:
+    """Toggle a list of ``(name, note, checked)`` rows and return the checked.
+
+    One screen replaces one question per row. A terminal that cannot be driven
+    this way -- a pipe, a dumb terminal, a captured test stdin -- never reaches
+    here; the caller asks in plain text instead.
+    """
+    checked = [state for _, _, state in options]
+    cursor = 0
+    sys.stdout.write(f"{heading}\n")
+    sys.stdout.write("  ↑↓ move · space toggles · a all · enter confirms\n\n")
+    _draw(options, checked, cursor, first=True)
+    settings = termios.tcgetattr(sys.stdin.fileno())
+    try:
+        tty.setraw(sys.stdin.fileno())
+        while True:
+            key = sys.stdin.read(1)
+            # An arrow key arrives as an escape sequence; read its tail.
+            if key == "\x1b" and sys.stdin.read(1) == "[":
+                key = _ARROWS.get(sys.stdin.read(1), "")
+            cursor, checked, done = _apply_key(key, cursor, checked)
+            if done:
+                break
+            _draw(options, checked, cursor)
+    finally:
+        termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, settings)
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    return tuple(
+        name for (name, _, _), state in zip(options, checked, strict=True) if state
+    )
+
+
+_ARROWS = {"A": "k", "B": "j"}
+
+
+def _apply_key(
+    key: str, cursor: int, checked: list[bool]
+) -> tuple[int, list[bool], bool]:
+    """Fold one keypress into the checklist's state.
+
+    Kept apart from the terminal so the behaviour can be tested without one.
+    Returns the new cursor, the new marks, and whether the operator is done.
+    """
+    if key == "\x03":
+        raise KeyboardInterrupt
+    if key in {"\r", "\n"}:
+        return cursor, checked, True
+    count = len(checked)
+    if key in {"j", "\t"}:
+        return (cursor + 1) % count, checked, False
+    if key == "k":
+        return (cursor - 1) % count, checked, False
+    if key == " ":
+        toggled = list(checked)
+        toggled[cursor] = not toggled[cursor]
+        return cursor, toggled, False
+    if key == "a":
+        return cursor, [not all(checked)] * count, False
+    return cursor, checked, False
+
+
+def _draw(
+    options: tuple[tuple[str, str, bool], ...],
+    checked: list[bool],
+    cursor: int,
+    *,
+    first: bool = False,
+) -> None:
+    """Repaint the rows in place, so the screen never scrolls away."""
+    if not first:
+        sys.stdout.write(f"\x1b[{len(options)}A")
+    width = max(len(name) for name, _, _ in options)
+    for index, (name, note, _) in enumerate(options):
+        mark = "x" if checked[index] else " "
+        pointer = ">" if index == cursor else " "
+        label = f"{name.ljust(width)}  {note}" if note else name
+        row = f" {pointer} [{mark}] {label}"
+        sys.stdout.write(f"\r\x1b[K{row}\n")
+    sys.stdout.flush()
+
+
+def _ask_names(prompt: str, names: tuple[str, ...]) -> tuple[str, ...]:
+    """Read zero or more of ``names``, comma-separated; empty means none.
+
+    One question for a list beats one question per entry when the answer is
+    almost always "none of them".
+    """
+    allowed = {name.lstrip(".").lower(): name for name in names}
+    while True:
+        value = input(prompt).strip().lower()
+        # Someone answering a list of options with "n" plainly means none.
+        if not value or value in {"none", "n", "no"}:
+            return ()
+        chosen = [part.strip().lstrip(".") for part in value.split(",")]
+        if all(part in allowed for part in chosen if part):
+            return tuple(dict.fromkeys(allowed[part] for part in chosen if part))
+        print("Choose from: " + ", ".join(names) + ", or none.")
+
+
+def _ask_yes_no(prompt: str, default: bool) -> bool:
+    while True:
+        value = input(prompt).strip().lower()
+        if not value:
+            return default
+        if value in {"y", "yes"}:
+            return True
+        if value in {"n", "no"}:
+            return False
+        print("Answer yes or no.")
+
+
+def _ask_operator(prompt: str, cancelled: str) -> bool:
+    """Ask the operator at a terminal; without one, refuse at once.
+
+    An agent's shell has no terminal, and an answer piped into the prompt is
+    not the operator's: the confirmation it needs is ``--yes``, given once
+    the operator has agreed. ww never reads a confirmation from a pipe.
+    """
+    if not sys.stdin.isatty():
+        print(
+            f"ww error: {cancelled.lower()} needs the operator's confirmation, "
+            "and there is no terminal to ask at. If you are an agent, ask the "
+            "operator; rerun with --yes only once they have agreed.",
+            file=sys.stderr,
+        )
+        return False
+    try:
+        confirmed = _ask_yes_no(prompt, default=False)
+    except EOFError:
+        confirmed = False
+    if not confirmed:
+        print(
+            f"{cancelled} cancelled: explicit confirmation is required.",
+            file=sys.stderr,
+        )
+    return confirmed
+
+
+def confirm_operator(
+    command: str,
+    effect: str,
+    question: str,
+    cancelled: str,
+    *,
+    assume_yes: bool = False,
+) -> bool:
+    """Require the operator's acknowledgement before an irreversible choice.
+
+    ``effect`` is ww's own description of what ``command`` will do, obtained
+    after the state was checked, so the operator approves a real action.
+    ``assume_yes`` is ``--yes``: an agent carrying out the operator's stated
+    decision; the effect is still printed, so the decision is on record.
+    """
+    if assume_yes:
+        print(f"`{command}` will {effect}. Confirmed with --yes.", file=sys.stderr)
+        return True
+    print(f"`{command}` will {effect}.", file=sys.stderr)
+    return _ask_operator(f"{question} [y/N] ", cancelled)
+
+
+def _confirm_force_next(
+    effect: str = "skip the current item without running it",
+    *,
+    assume_yes: bool = False,
+) -> bool:
+    """Require an operator acknowledgement before forcing past work."""
+    return confirm_operator(
+        "ww next --force",
+        effect,
+        "Proceed with force?",
+        "Force",
+        assume_yes=assume_yes,
+    )
+
+
+def confirm_interrupted_retry(*, assume_yes: bool = False) -> bool:
+    """Require an operator to acknowledge duplicate-effect risk."""
+    if assume_yes:
+        print("The retry is confirmed with --yes.", file=sys.stderr)
+        return True
+    print(
+        "This operation was interrupted and may already have taken effect. "
+        "Retrying can duplicate its external effect.",
+        file=sys.stderr,
+    )
+    return _ask_operator("Proceed with retry? [y/N] ", "Retry")

ww/cli/updates.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Announcing a newer ww before running the command the caller asked for."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from ww.errors import WwError
+from ww.executable import DEFAULT_EXECUTABLE, printed_executable
+from ww.package_updates import (
+    PackageUpdateNotice,
+    last_package_notice,
+    mark_package_announced,
+    pending_package_notice,
+)
+from ww.project_config import load_project_config
+from ww.storage import Storage
+from ww.updates import (
+    UpdateNotice,
+    check_enabled,
+    installation_checkout,
+    last_notice,
+    mark_announced,
+    pending_notice,
+)
+
+
+def announce(storage: Storage, *, to_stderr: bool = False) -> None:
+    """Write a pending update notice ahead of the command's own output.
+
+    A notice is a convenience and may never disturb the command: unreadable
+    state, a remote that will not answer, or a read-only home leaves the
+    invocation exactly as it would otherwise have been. ``to_stderr`` keeps it
+    out of stdout that something else is going to parse.
+    """
+    try:
+        if not update_check_wanted(storage):
+            return
+        checkout = installation_checkout()
+        notice = (
+            pending_notice(checkout)
+            if checkout is not None
+            else pending_package_notice()
+        )
+        if notice is None:
+            return
+        stream = sys.stderr if to_stderr else sys.stdout
+        configured = load_project_config(storage.project_config_path).executable
+        executable = configured or (
+            "./ww" if (storage.root / "ww").is_file() else DEFAULT_EXECUTABLE
+        )
+        with printed_executable(executable):
+            stream.write(notice.render())
+        stream.flush()
+        _mark(notice)
+    except Exception:  # noqa: BLE001 - contain every failure of a convenience
+        return
+
+
+def render_updates(storage: Storage, args: argparse.Namespace) -> str:
+    """Render ``ww updates``: what the last check found, or a fresh look."""
+    if not update_check_wanted(storage):
+        return _rendered(None, args, "The ww update check is turned off.\n")
+    checkout = installation_checkout()
+    notice: UpdateNotice | PackageUpdateNotice | None
+    if checkout is None:
+        pending_package_notice(force=bool(args.now))
+        notice = last_package_notice()
+    else:
+        pending_notice(checkout, force=bool(args.now))
+        notice = last_notice()
+    if notice is not None:
+        _mark(notice)
+    return _rendered(
+        notice,
+        args,
+        "ww is up to date.\n"
+        if checkout is not None
+        else "No package update notice is available.\n",
+    )
+
+
+def update_check_wanted(storage: Storage) -> bool:
+    """Whether this project and environment want the check to run."""
+    try:
+        configured = load_project_config(storage.project_config_path).update_check
+    except WwError:
+        configured = True
+    return check_enabled(configured)
+
+
+def _rendered(
+    notice: UpdateNotice | PackageUpdateNotice | None,
+    args: argparse.Namespace,
+    otherwise: str,
+) -> str:
+    if args.json_output:
+        return (
+            json.dumps(
+                {
+                    "update_available": notice is not None,
+                    "notice": notice.to_dict() if notice else None,
+                },
+                indent=2,
+            )
+            + "\n"
+        )
+    return notice.render() if notice else otherwise
+
+
+def _mark(notice: UpdateNotice | PackageUpdateNotice) -> None:
+    if isinstance(notice, PackageUpdateNotice):
+        mark_package_announced(notice)
+    else:
+        mark_announced(notice)

ww/completion_artifacts.py

@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Persist agent completion artifacts without changing workflow state."""
+
+from __future__ import annotations
+
+from ww.actions import PlannedAction, actions
+from ww.artifacts import RuleOutcome, RulesSummary, RuleStatus, render_step_artifact
+from ww.contracts import CheckStatus
+from ww.execution_models import CheckReport, ExecutionState, PlanSnapshot
+from ww.plan import PlanItem
+from ww.rule_checks import item_reports
+from ww.storage_adapters.base import ArtifactAddress, TaskArtifactStorage
+
+_REPORTED: dict[CheckStatus, RuleStatus] = {
+    "passed": "passed",
+    "failed": "failed",
+    "not_applicable": "not applicable",
+}
+
+
+def rule_outcomes(
+    state: ExecutionState, item: PlanItem, report: CheckReport | None
+) -> RulesSummary | None:
+    """What the completing step's artifact says about its rules and checks.
+
+    A rule checked by a derived check reports that check's result; one a
+    verifier judged reports the verdict and the verification item; any other
+    rule without a check is self-declared: the worker states in its result
+    how it followed it. A check reports its result in ``report``, or, when
+    the operator waived it, in the last report that ran it. Rejections an
+    operator retry moved into the history still count.
+    """
+    record = state.item_executions[state.cursor]
+    if not item.rules and not item.checks:
+        return None
+    results = {
+        result.id: result
+        for ran in (*record.check_reports, *((report,) if report else ()))
+        for result in ran.results
+    }
+    checked = {check.id for check in item.checks}
+    derived = {
+        rule_id: check.id
+        for check in record.resolved_checks
+        for rule_id in check.covers
+    }
+    held = record.held_completion
+    outcomes = []
+    for rule in item.rules:
+        if rule.id in checked:
+            continue
+        verdict = held.verdict(rule.id) if held is not None else None
+        if rule.id in derived:
+            result = results.get(derived[rule.id])
+            status = _REPORTED[result.status] if result else "not applicable"
+            outcomes.append(
+                RuleOutcome(rule.id, status, detail=f"check `{derived[rule.id]}`")
+            )
+        elif verdict is not None and verdict.verdict == "pass":
+            outcomes.append(
+                RuleOutcome(rule.id, "verified pass", detail=f"by `{verdict.by}`")
+            )
+        else:
+            outcomes.append(RuleOutcome(rule.id, "self-declared"))
+    for check in item.checks:
+        result = results.get(check.id)
+        outcomes.append(
+            RuleOutcome(
+                check.id,
+                _REPORTED[result.status] if result is not None else "not applicable",
+                hook=check.source == "hook",
+            )
+        )
+    order = {rule.id: index for index, rule in enumerate(item.rules)}
+    outcomes.sort(key=lambda outcome: order.get(outcome.id, len(order)))
+    return RulesSummary(
+        tuple(outcomes),
+        fix_attempts=sum(1 for earlier in item_reports(state) if earlier.failed),
+        waived=record.checks_waived,
+    )
+
+
+def write_completion_artifacts(
+    storage: TaskArtifactStorage,
+    task_id: str,
+    state: ExecutionState,
+    snapshot: PlanSnapshot,
+    item: PlanItem,
+    loop_entry: PlanItem | None,
+    artifact: str | None,
+    *,
+    rules: RulesSummary | None = None,
+) -> tuple[str | None, str | None]:
+    """Write the completed item and optional enclosing-loop artifacts.
+
+    ``rules`` is the completed item's own rule report; a loop wrapper's
+    artifact carries none.
+    """
+    if artifact is None:
+        return None, None
+
+    def attribution(plan_item: PlanItem) -> str:
+        if not isinstance(plan_item.operation, PlannedAction):
+            return "auto"
+        action = actions.get(plan_item.kind)
+        return action.traits(plan_item.operation.payload).artifact_attribution
+
+    step_paths = tuple(
+        dict.fromkeys(
+            plan_item.step
+            for plan_item in snapshot.plan.items
+            if plan_item.phase == "step"
+        )
+    )
+
+    def rendered(plan_item: PlanItem) -> str:
+        return render_step_artifact(
+            task_id=task_id,
+            workflow=state.workflow,
+            step=plan_item.step,
+            step_number=step_paths.index(plan_item.step) + 1,
+            step_total=len(step_paths),
+            skill=attribution(plan_item),
+            result=artifact,
+            rules=rules if plan_item is item else None,
+        )
+
+    def write(plan_item: PlanItem, content: str) -> str:
+        return storage.write_execution_artifact(
+            ArtifactAddress(
+                task_id,
+                state.workflow,
+                plan_item.step,
+                plan_item.position,
+                plan_item.name,
+                plan_item.phase,
+                run_id=state.run_id,
+                step_ordinals=plan_item.step_ordinals,
+                loop_iterations=tuple(
+                    (loop_id, iteration)
+                    for loop_id, iteration in state.loop_iterations
+                    if loop_id in plan_item.ancestors
+                ),
+            ),
+            content,
+        )
+
+    artifact_reference = None
+    if item.artifact:
+        artifact_reference = write(
+            item, rendered(item) if item.phase == "step" else artifact
+        )
+    wrapper_artifact_reference = None
+    if loop_entry is not None and loop_entry.artifact:
+        wrapper_artifact_reference = write(loop_entry, rendered(loop_entry))
+    return artifact_reference, wrapper_artifact_reference

ww/completion_inputs.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Validation for values supplied when completing workflow work."""
+
+from __future__ import annotations
+
+from ww.errors import StateError
+from ww.workflow_config import ProvidedVariable
+
+
+def validate_values(values: tuple[tuple[str, str], ...]) -> dict[str, str]:
+    """Return supplied values, rejecting duplicate names."""
+    result = dict(values)
+    if len(result) != len(values):
+        raise StateError("a completion variable can only be supplied once")
+    return result
+
+
+def group_metadata_values(
+    values: tuple[tuple[str, str], ...],
+) -> dict[str, tuple[str, ...]]:
+    """Group ``--metadata`` values by name; an append key may repeat."""
+    grouped: dict[str, tuple[str, ...]] = {}
+    for name, value in values:
+        grouped[name] = (*grouped.get(name, ()), value)
+    return grouped
+
+
+def validate_requested_values(
+    values: dict[str, str], requested: tuple[ProvidedVariable, ...]
+) -> None:
+    """Require exactly the variables requested by a plan item."""
+    expected = {item.name for item in requested}
+    unknown, missing = set(values) - expected, expected - set(values)
+    if unknown:
+        raise StateError(
+            "unexpected completion variable(s): " + ", ".join(sorted(unknown))
+        )
+    if missing:
+        raise StateError("missing required variable(s): " + ", ".join(sorted(missing)))