@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/templates/scripts/work_engine/hooks/runner.py

@@ -0,0 +1,73 @@
+"""``HookRunner`` — single emit point for hook callbacks.
+
+Implements the three-tier error contract documented in
+``exceptions.py``:
+
+- ``HookError`` from a callback → caught, ``warnings.warn`` is emitted,
+  the runner continues with the next callback for the same event.
+  Returns ``None`` once the event is fully drained.
+- ``HookHalt`` from a callback → caught, **returned** to the caller
+  with no further callbacks invoked for this event. The caller
+  decides how to surface the halt (engine halt, CLI exit 2). Never
+  re-raised through the dispatch loop.
+- any other ``Exception`` → propagates unchanged. Treated as a hook
+  bug; dispatch unwinds.
+
+The runner is intentionally tiny. Behavior changes belong here so
+``dispatcher.py`` and ``cli.py`` stay free of hook bookkeeping.
+"""
+from __future__ import annotations
+
+import warnings
+
+from .context import HookContext
+from .events import HookEvent
+from .exceptions import HookError, HookHalt
+from .registry import HookRegistry
+
+
+class HookRunner:
+    """Emit hook events through a :class:`HookRegistry`.
+
+    Construct once per CLI invocation, share between the CLI and the
+    dispatcher. ``emit`` is the only public method on the hot path.
+    """
+
+    def __init__(self, registry: HookRegistry | None = None) -> None:
+        self._registry = registry if registry is not None else HookRegistry()
+
+    @property
+    def registry(self) -> HookRegistry:
+        """Return the underlying registry.
+
+        Exposed so callers can register additional hooks after
+        construction (e.g. in tests). Not used on the hot path.
+        """
+        return self._registry
+
+    def emit(self, event: HookEvent, ctx: HookContext) -> HookHalt | None:
+        """Fire all callbacks registered for ``event``.
+
+        Returns ``None`` when every callback completed (with or without
+        a swallowed :class:`HookError`). Returns the first
+        :class:`HookHalt` raised, after which no further callbacks are
+        invoked for this event. Any other exception propagates.
+        """
+        callbacks = self._registry.for_event(event)
+        if not callbacks:
+            return None
+        for callback in callbacks:
+            try:
+                callback(ctx)
+            except HookHalt as halt:
+                return halt
+            except HookError as err:
+                warnings.warn(
+                    f"hook {event.value} raised HookError: {err}",
+                    stacklevel=2,
+                )
+                continue
+        return None
+
+
+__all__ = ["HookRunner"]

package/.agent-src/templates/scripts/work_engine/hooks/settings.py

@@ -0,0 +1,141 @@
+"""Read ``hooks.*`` from ``.agent-settings.yml`` into :class:`HookSettings`.
+
+Mirror of the chat-history settings pattern (``scripts/command_suggester/
+settings.py``):
+
+* Lazy PyYAML import — the engine works without yaml installed when no
+  settings file is present (test fixtures, cloud bundles).
+* Default-permissive: a missing file or missing ``hooks:`` block returns
+  :class:`HookSettings` with ``enabled=False`` — every hook off, every
+  golden replay safe by construction.
+* Malformed YAML / unreadable file → defaults; the engine degrades
+  silently rather than crashing the CLI.
+* Chat-history hooks gate on **two** switches: ``hooks.chat_history.
+  enabled`` AND the global ``chat_history.enabled``. Either off → no
+  chat-history hook registers.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
+DEFAULT_CHAT_HISTORY_SCRIPT = "scripts/chat_history.py"
+
+
+@dataclass(frozen=True)
+class HookSettings:
+    """Resolved view of the ``hooks:`` block.
+
+    ``enabled`` is the master switch. When ``False`` the registry stays
+    empty regardless of the per-hook fields; this is the default when no
+    settings file exists or no ``hooks`` block is declared, and it is
+    what keeps golden-replay tests byte-stable.
+    """
+
+    enabled: bool = False
+    trace: bool = False
+    halt_surface_audit: bool = False
+    state_shape_validation: bool = False
+    directive_set_guard: bool = False
+    chat_history_enabled: bool = False
+    chat_history_script: str = DEFAULT_CHAT_HISTORY_SCRIPT
+
+
+_DEFAULT = HookSettings()
+
+
+def load_hook_settings(
+    settings_path: Path | str | None = None,
+) -> HookSettings:
+    """Return :class:`HookSettings` hydrated from ``.agent-settings.yml``.
+
+    ``settings_path`` defaults to ``./.agent-settings.yml`` relative to
+    the current working directory — same convention as chat-history.
+    """
+    path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
+    raw = _read_yaml(path)
+    if raw is None:
+        return _DEFAULT
+    return _settings_from_raw(raw)
+
+
+def _read_yaml(path: Path) -> dict[str, Any] | None:
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return _DEFAULT
+    enabled = _coerce_bool(hooks.get("enabled"), False)
+    if not enabled:
+        return HookSettings(enabled=False)
+
+    chat_section = hooks.get("chat_history")
+    if isinstance(chat_section, dict):
+        chat_block_enabled = _coerce_bool(chat_section.get("enabled"), True)
+        chat_script = str(
+            chat_section.get("script") or DEFAULT_CHAT_HISTORY_SCRIPT
+        )
+    else:
+        chat_block_enabled = True
+        chat_script = DEFAULT_CHAT_HISTORY_SCRIPT
+
+    global_chat = data.get("chat_history")
+    global_chat_on = (
+        isinstance(global_chat, dict)
+        and _coerce_bool(global_chat.get("enabled"), False)
+    )
+
+    return HookSettings(
+        enabled=True,
+        trace=_coerce_bool(hooks.get("trace"), False),
+        halt_surface_audit=_coerce_bool(
+            hooks.get("halt_surface_audit"), True
+        ),
+        state_shape_validation=_coerce_bool(
+            hooks.get("state_shape_validation"), True
+        ),
+        directive_set_guard=_coerce_bool(
+            hooks.get("directive_set_guard"), True
+        ),
+        chat_history_enabled=chat_block_enabled and global_chat_on,
+        chat_history_script=chat_script,
+    )
+
+
+def _coerce_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, str):
+        s = value.strip().lower()
+        if s in ("true", "yes", "on", "1"):
+            return True
+        if s in ("false", "no", "off", "0"):
+            return False
+    return default
+
+
+__all__ = [
+    "DEFAULT_CHAT_HISTORY_SCRIPT",
+    "DEFAULT_SETTINGS_FILE",
+    "HookSettings",
+    "load_hook_settings",
+]

package/.agent-src/templates/scripts/work_engine/input_builders.py

@@ -0,0 +1,163 @@
+"""File-based input builders and the load-or-build dispatch helper.
+
+Extracted from ``cli.py`` in P2.3 of
+``road-to-post-pr29-optimize.md``. Owns the CLI's "first run" path:
+when no state file exists, build a fresh :class:`WorkState` from
+``--ticket-file``, ``--prompt-file``, ``--diff-file`` or
+``--file-file``. Every builder is byte-identical in behaviour to the
+pre-split version — the resolvers it calls and the persona / routing
+post-processing did not move.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .cli_args import _FMT_V0, _FMT_V1
+from .errors import _CLIError
+from .intent import populate_routing
+from .resolvers.diff import DiffResolverError, build_envelope as _build_diff_envelope
+from .resolvers.file import FileResolverError, build_envelope as _build_file_envelope
+from .resolvers.prompt import PromptResolverError, build_envelope as _build_prompt_envelope
+from .state import Input, WorkState
+from .state_io import _load, _maybe_raise_legacy_hint, _read_json
+
+
+def _load_or_build(
+    state_file: Path,
+    args: argparse.Namespace,
+) -> tuple[WorkState, str]:
+    """Return the WorkState to dispatch against plus its wire format.
+
+    Either loaded from ``state_file`` (format-preserving) or freshly
+    built from ``--ticket-file`` (R1), ``--prompt-file`` (R2),
+    ``--diff-file`` (R3) or ``--file-file`` (R3). Fresh ticket files
+    default to v0 wire format so that newly captured Goldens stay
+    byte-equal with the pre-Phase-4 baseline; the prompt / diff / file
+    paths emit v1 directly (v0 has no envelope concept for these
+    kinds). v1 round-trips for state files already on disk in v1 shape.
+    """
+    if state_file.exists():
+        return _load(state_file)
+    _maybe_raise_legacy_hint(state_file)
+    inputs = [
+        ("--ticket-file", args.ticket_file),
+        ("--prompt-file", args.prompt_file),
+        ("--diff-file", args.diff_file),
+        ("--file-file", args.file_file),
+    ]
+    supplied = [name for name, value in inputs if value is not None]
+    if len(supplied) > 1:
+        raise _CLIError(
+            f"{', '.join(supplied)} are mutually exclusive; pass exactly "
+            "one when building an initial state.",
+        )
+    if not supplied:
+        raise _CLIError(
+            f"No state file at {state_file} and no --ticket-file, "
+            "--prompt-file, --diff-file, or --file-file given; cannot "
+            "build an initial state.",
+        )
+    if args.prompt_file is not None:
+        return _build_from_prompt_file(args), _FMT_V1
+    if args.diff_file is not None:
+        return _build_from_diff_file(args), _FMT_V1
+    if args.file_file is not None:
+        return _build_from_file_file(args), _FMT_V1
+    ticket = _read_json(args.ticket_file)
+    if not isinstance(ticket, dict):
+        raise _CLIError(
+            f"--ticket-file must carry a JSON object; got {type(ticket).__name__}.",
+        )
+    work = WorkState(input=Input(kind="ticket", data=ticket))
+    if args.persona:
+        work.persona = args.persona
+    populate_routing(work)
+    return work, _FMT_V0
+
+
+def _build_from_prompt_file(args: argparse.Namespace) -> WorkState:
+    """Read ``--prompt-file`` as raw text and wrap it in a prompt envelope.
+
+    The file is read verbatim (UTF-8) and handed to the prompt resolver,
+    which validates non-emptiness and returns the canonical
+    ``Input(kind="prompt", data={raw, reconstructed_ac, assumptions})``
+    envelope. Persona is honoured the same way as the ticket path.
+    """
+    try:
+        raw = args.prompt_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise _CLIError(f"Cannot read {args.prompt_file}: {exc}") from exc
+    try:
+        envelope = _build_prompt_envelope(raw)
+    except PromptResolverError as exc:
+        raise _CLIError(f"--prompt-file is not a valid prompt: {exc}") from exc
+    work = WorkState(input=envelope)
+    if args.persona:
+        work.persona = args.persona
+    populate_routing(work)
+    return work
+
+
+def _build_from_diff_file(args: argparse.Namespace) -> WorkState:
+    """Read ``--diff-file`` as raw text and wrap it in a diff envelope.
+
+    The file is read verbatim (UTF-8) and handed to the diff resolver,
+    which validates the unified-diff header heuristic and returns the
+    canonical
+    ``Input(kind="diff", data={raw, reconstructed_ac, assumptions})``
+    envelope. ``populate_routing`` then routes the envelope to the
+    UI-improve directive set without running the prose classifier — see
+    :mod:`work_engine.intent.classify` for the routing contract.
+    """
+    try:
+        raw = args.diff_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise _CLIError(f"Cannot read {args.diff_file}: {exc}") from exc
+    try:
+        envelope = _build_diff_envelope(raw)
+    except DiffResolverError as exc:
+        raise _CLIError(f"--diff-file is not a valid diff: {exc}") from exc
+    work = WorkState(input=envelope)
+    if args.persona:
+        work.persona = args.persona
+    populate_routing(work)
+    return work
+
+
+def _build_from_file_file(args: argparse.Namespace) -> WorkState:
+    """Read ``--file-file`` as a single-line path and wrap it in a file envelope.
+
+    The file is read verbatim (UTF-8); the first non-empty line is taken
+    as the path reference and handed to the file resolver, which
+    validates path shape (non-empty, NUL-free, not a URL) and returns
+    the canonical
+    ``Input(kind="file", data={path, reconstructed_ac, assumptions})``
+    envelope. Trailing whitespace and additional lines are ignored —
+    the resolver treats the file's content as the path itself, not as
+    structured payload.
+    """
+    try:
+        raw = args.file_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise _CLIError(f"Cannot read {args.file_file}: {exc}") from exc
+    path = raw.strip().splitlines()[0] if raw.strip() else ""
+    try:
+        envelope = _build_file_envelope(path)
+    except FileResolverError as exc:
+        raise _CLIError(
+            f"--file-file does not carry a valid path: {exc}",
+        ) from exc
+    work = WorkState(input=envelope)
+    if args.persona:
+        work.persona = args.persona
+    populate_routing(work)
+    return work
+
+
+__all__ = [
+    "_build_from_diff_file",
+    "_build_from_file_file",
+    "_build_from_prompt_file",
+    "_load_or_build",
+]

package/.agent-src/templates/scripts/work_engine/intent/__init__.py

@@ -0,0 +1,47 @@
+"""Intent classification for the universal engine (R3 Phase 1 Step 2).
+
+The :mod:`work_engine.intent.classify` module turns a raw user prompt
+(or a ticket's title + body) into one of the five labels the dispatcher
+routes against:
+
+- ``ui-build`` — new screen, page, or component.
+- ``ui-improve`` — change to an existing screen / component.
+- ``ui-trivial`` — single-file, single-concern micro-edit (color, copy,
+  one class, one prop). Hard preconditions are enforced again at apply
+  time; the classifier only labels the *intent*, not the safety floor.
+- ``mixed`` — both UI and backend signals; routes to the mixed track.
+- ``backend-coding`` — default; no UI signal.
+
+The classifier is intentionally heuristic-only — it consumes nothing
+beyond the prompt text and optional ticket title. Confidence-band
+gating, AC reconstruction, and assumption surfacing all stay in
+``directives/backend/refine.py`` (R2). This module only owns the
+*label*; the dispatcher owns the routing.
+"""
+from __future__ import annotations
+
+from . import classify
+from .classify import (
+    INTENT_BACKEND,
+    INTENT_MIXED,
+    INTENT_UI_BUILD,
+    INTENT_UI_IMPROVE,
+    INTENT_UI_TRIVIAL,
+    KNOWN_INTENTS,
+    classify_intent,
+    directive_set_for,
+    populate_routing,
+)
+
+__all__ = [
+    "INTENT_BACKEND",
+    "INTENT_MIXED",
+    "INTENT_UI_BUILD",
+    "INTENT_UI_IMPROVE",
+    "INTENT_UI_TRIVIAL",
+    "KNOWN_INTENTS",
+    "classify",
+    "classify_intent",
+    "directive_set_for",
+    "populate_routing",
+]