@event4u/agent-config 6.0.0 → 7.0.0

package/dist/agent-src/templates/scripts/work_engine/hooks/builtin/state_shape_validation.py

@@ -1,52 +0,0 @@
-"""``StateShapeValidationHook`` — round-trip the v1 envelope on load and save.
-
-Fires on :data:`HookEvent.AFTER_LOAD` and :data:`HookEvent.BEFORE_SAVE`.
-For each event, serialises the live :class:`work_engine.state.WorkState`
-through ``state.to_dict`` and re-validates via ``state.from_dict``. A
-:class:`work_engine.state.SchemaError` from either side is reported as
-a :class:`HookError` so the runner warns and continues — observability,
-not a gate.
-
-The hook only sees the post-migration v1 shape. ``_load_or_build`` owns
-v0 → v1 migration; this hook is the safety net catching any drift the
-migration or a hand-edited state file might have produced.
-"""
-from __future__ import annotations
-
-from ..context import HookContext
-from ..events import HookEvent
-from ..exceptions import HookError
-from ..registry import HookRegistry
-
-
-class StateShapeValidationHook:
-    """Round-trips the loaded ``WorkState`` against the v1 schema."""
-
-    def register(self, registry: HookRegistry) -> None:
-        """Register on AFTER_LOAD and BEFORE_SAVE."""
-        registry.register(HookEvent.AFTER_LOAD, self._validate)
-        registry.register(HookEvent.BEFORE_SAVE, self._validate)
-
-    def _validate(self, ctx: HookContext) -> None:
-        work = ctx.work
-        if work is None:
-            # Should not happen on AFTER_LOAD/BEFORE_SAVE; treat as
-            # a hook-side bug rather than swallow silently.
-            raise HookError(
-                "state-shape validation: HookContext.work is None at "
-                f"event for state_file={ctx.state_file}",
-            )
-
-        # Local imports keep the hook module import-light and avoid a
-        # cycle with ``work_engine.state`` at package import time.
-        from ...state import SchemaError, from_dict, to_dict  # noqa: PLC0415
-
-        try:
-            from_dict(to_dict(work))
-        except SchemaError as exc:
-            raise HookError(
-                f"state-shape validation failed: {exc}",
-            ) from exc
-
-
-__all__ = ["StateShapeValidationHook"]

package/dist/agent-src/templates/scripts/work_engine/hooks/builtin/trace.py

@@ -1,84 +0,0 @@
-"""``TraceHook`` — emit one stderr line per hook event.
-
-Useful for debugging dispatch flow and Phase 5 chat-history wiring.
-Registers on every :class:`HookEvent`; output goes to a configurable
-stream (default ``sys.stderr``) so tests can capture it.
-
-Pure observability — never mutates context, never halts. A misbehaving
-sink (e.g. closed stream) raises :class:`HookError`, which the runner
-swallows with a warning per the three-tier contract.
-"""
-from __future__ import annotations
-
-import sys
-from typing import IO
-
-from ..context import HookContext
-from ..events import HookEvent
-from ..exceptions import HookError
-from ..registry import HookRegistry
-
-
-class TraceHook:
-    """Stderr-trace hook for every lifecycle event.
-
-    Parameters
-    ----------
-    stream:
-        Output stream. Defaults to ``sys.stderr``. Tests pass an
-        ``io.StringIO`` to capture the trace without touching stderr.
-    prefix:
-        Line prefix. Defaults to ``"[hook]"`` for visual separation
-        from regular CLI output.
-    """
-
-    def __init__(
-        self,
-        stream: IO[str] | None = None,
-        prefix: str = "[hook]",
-    ) -> None:
-        self._stream = stream if stream is not None else sys.stderr
-        self._prefix = prefix
-
-    def register(self, registry: HookRegistry) -> None:
-        """Register the trace callback for every :class:`HookEvent`."""
-        for event in HookEvent:
-            registry.register(event, self._make_callback(event))
-
-    def _make_callback(self, event: HookEvent):
-        def _cb(ctx: HookContext) -> None:
-            try:
-                line = self._format(event, ctx)
-                self._stream.write(line + "\n")
-                self._stream.flush()
-            except (OSError, ValueError) as exc:
-                raise HookError(f"trace stream unavailable: {exc}") from exc
-
-        return _cb
-
-    def _format(self, event: HookEvent, ctx: HookContext) -> str:
-        """Build a one-line trace record.
-
-        Format: ``[hook] event=<name> step=<step> set=<set> outcome=<o>``.
-        Missing fields are skipped so the line stays short on events that
-        only carry a subset of the context.
-        """
-        parts: list[str] = [self._prefix, f"event={event.value}"]
-        if ctx.step_name:
-            parts.append(f"step={ctx.step_name}")
-        if ctx.set_name:
-            parts.append(f"set={ctx.set_name}")
-        if ctx.result is not None:
-            outcome = getattr(ctx.result, "outcome", None)
-            if outcome is not None:
-                parts.append(f"outcome={getattr(outcome, 'value', outcome)}")
-        if ctx.final is not None:
-            parts.append(f"final={getattr(ctx.final, 'value', ctx.final)}")
-        if ctx.halting:
-            parts.append(f"halting={ctx.halting}")
-        if ctx.exception is not None:
-            parts.append(f"exception={type(ctx.exception).__name__}")
-        return " ".join(parts)
-
-
-__all__ = ["TraceHook"]

package/dist/agent-src/templates/scripts/work_engine/hooks/context.py

@@ -1,66 +0,0 @@
-"""``HookContext`` — payload carried into every hook callback.
-
-One dataclass for both layers. Most fields are ``None`` for any given
-event; the per-event subset is documented below and locked by the
-roadmap's hook event surface table. Hooks must tolerate missing fields
-gracefully — accessing a field that is ``None`` for the current event
-is a hook bug, not an engine bug.
-
-Per-event subset (mirrors the roadmap):
-
-Dispatcher layer (``delivery`` is set; ``work`` is ``None``):
-    - ``before_step``   → ``step_name``, ``delivery``
-    - ``after_step``    → ``step_name``, ``delivery``, ``result``
-    - ``on_halt``       → ``step_name``, ``delivery``, ``result``
-    - ``on_error``      → ``step_name``, ``delivery``, ``exception``
-
-CLI layer (``work`` is set; ``delivery`` may be set after load):
-    - ``before_load``       → ``state_file``, ``args``
-    - ``after_load``        → ``state_file``, ``work``, ``fmt``
-    - ``before_dispatch``   → ``work``, ``delivery``, ``set_name``
-    - ``after_dispatch``    → ``work``, ``delivery``, ``final``,
-                              ``halting``
-    - ``before_save``       → ``work``, ``delivery``, ``fmt``
-    - ``after_save``        → ``work``, ``state_file``, ``fmt``
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-
-@dataclass
-class HookContext:
-    """Per-event payload passed to every hook callback.
-
-    Fields are intentionally optional — the runner does not validate
-    which ones are populated for a given event. The contract is
-    enforced by the call sites in ``dispatcher.py`` and ``cli.py``,
-    not by the dataclass.
-
-    ``extra`` exists as an escape hatch for hook-specific state that
-    does not warrant a dedicated field. Use sparingly; if a piece of
-    state is read by more than one hook, promote it to a real field.
-    """
-
-    # Dispatcher-layer refs.
-    step_name: str | None = None
-    delivery: Any = None  # DeliveryState — typed Any to avoid an import cycle.
-    result: Any = None  # StepResult
-    exception: BaseException | None = None
-
-    # CLI-layer refs.
-    work: Any = None  # WorkState — typed Any to avoid an import cycle.
-    state_file: Path | None = None
-    fmt: str | None = None
-    set_name: str | None = None
-    final: Any = None  # Outcome
-    halting: str | None = None
-    args: Any = None  # argparse.Namespace
-
-    # Escape hatch for hook-specific state.
-    extra: dict[str, Any] = field(default_factory=dict)
-
-
-__all__ = ["HookContext"]

package/dist/agent-src/templates/scripts/work_engine/hooks/events.py

@@ -1,44 +0,0 @@
-"""Hook event surface for ``work_engine``.
-
-Ten events split across two layers per
-``agents/roadmaps/road-to-work-engine-hooks.md`` (locked).
-
-Dispatcher-layer events fire from inside ``dispatcher.dispatch()`` and
-operate on ``DeliveryState`` (legacy, internal). CLI-layer events fire
-from ``cli.main()`` and operate on ``WorkState`` (v1 envelope) plus
-auxiliary refs (``state_file``, ``fmt``, ``args``). The split is
-deliberate — see the ``Hook event surface (locked)`` section of the
-roadmap for the per-event context payloads.
-
-Adding events is a roadmap-level decision: hook consumers depend on
-the surface staying stable, and an enum makes accidental string typos
-fail at import time.
-"""
-from __future__ import annotations
-
-from enum import Enum
-
-
-class HookEvent(str, Enum):
-    """Lifecycle events emitted by the work engine.
-
-    Subclassing ``str`` keeps round-trips trivial for telemetry and
-    JSON tracing — the value is the event name verbatim.
-    """
-
-    # Dispatcher layer (DeliveryState).
-    BEFORE_STEP = "before_step"
-    AFTER_STEP = "after_step"
-    ON_HALT = "on_halt"
-    ON_ERROR = "on_error"
-
-    # CLI layer (WorkState).
-    BEFORE_LOAD = "before_load"
-    AFTER_LOAD = "after_load"
-    BEFORE_DISPATCH = "before_dispatch"
-    AFTER_DISPATCH = "after_dispatch"
-    BEFORE_SAVE = "before_save"
-    AFTER_SAVE = "after_save"
-
-
-__all__ = ["HookEvent"]

package/dist/agent-src/templates/scripts/work_engine/hooks/exceptions.py

@@ -1,79 +0,0 @@
-"""Hook control-flow signals.
-
-Three-tier error contract (locked by roadmap P1):
-
-- ``HookError`` — non-fatal. Hook implementation failed; the runner
-  catches it, warns via ``warnings.warn``, and continues with the next
-  callback for the same event. Work proceeds.
-- ``HookHalt`` — fatal-controlled. Hook demands a clean stop (canonical
-  example: chat-history ``turn-check`` foreign session). The runner
-  catches it and **returns** it to the caller, who decides how to
-  surface it (engine halt, CLI exit code 2 + readable surface). Not
-  re-raised through the dispatch loop.
-- any other ``Exception`` — fatal-uncontrolled. Treated as a bug in the
-  hook. The runner lets it propagate verbatim; dispatch unwinds.
-
-Both signals share a private ``_HookSignal`` base so the runner can
-distinguish hook-originated control flow from genuine bugs without
-catching ``BaseException``.
-"""
-from __future__ import annotations
-
-
-class _HookSignal(Exception):
-    """Internal marker for hook-originated control flow.
-
-    Not part of the public API. The runner uses ``isinstance`` checks
-    against the concrete subclasses below; the base exists only so a
-    single ``except _HookSignal`` would cover both signals if a future
-    refactor needs it.
-    """
-
-
-class HookError(_HookSignal):
-    """Non-fatal hook failure.
-
-    Raised (or ``warn``-equivalent — both forms work) when a hook
-    callback fails in a way the *engine* should ignore. The runner
-    catches it, emits a ``warnings.warn`` with the message, and moves
-    on to the next callback registered for the event.
-
-    Example:
-        ``raise HookError("trace sink unavailable: connection refused")``
-
-    Use this for transient or non-critical hook failures (telemetry
-    sinks, optional reporters). Do **not** use it to signal "stop the
-    engine" — that is what :class:`HookHalt` is for.
-    """
-
-
-class HookHalt(_HookSignal):
-    """Fatal-controlled stop requested by a hook.
-
-    Hooks raise this when execution must not continue (e.g. chat-history
-    ``turn-check`` returns ``foreign``: a different session owns the
-    log, work cannot safely proceed). The runner catches it and returns
-    it to the caller; the caller turns it into the appropriate halt
-    surface:
-
-    - Dispatcher layer → ``Outcome.BLOCKED`` with ``state.questions``
-      populated from ``surface``.
-    - CLI layer → exit code 2, ``surface`` printed to stderr, no state
-      saved unless the halt fires after ``_save()``.
-
-    ``surface`` is a list of pre-formatted numbered options per the
-    ``user-interaction`` rule (one entry per line). Callers must not
-    reformat — surface is rendered verbatim.
-
-    ``reason`` is a short machine-readable code (e.g. ``"foreign"``,
-    ``"missing"``, ``"validation_failed"``) for logging and tests; it
-    is not shown to the user.
-    """
-
-    def __init__(self, reason: str, surface: list[str] | None = None) -> None:
-        super().__init__(reason)
-        self.reason = reason
-        self.surface: list[str] = list(surface or [])
-
-
-__all__ = ["HookError", "HookHalt"]

package/dist/agent-src/templates/scripts/work_engine/hooks/registry.py

@@ -1,60 +0,0 @@
-"""``HookRegistry`` — insertion-ordered map from event to callbacks.
-
-Phase 1 ships insertion-ordered registration only. If a real ordering
-need surfaces later (e.g. trace must fire before mutation hooks), add
-a priority field as a follow-up — do not pre-build it (per Notes
-section of the roadmap).
-
-The registry is a plain container. It does not invoke callbacks, does
-not catch exceptions, and does not know about the error contract;
-that responsibility lives in :class:`HookRunner`.
-"""
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import Iterable
-
-from .context import HookContext
-from .events import HookEvent
-
-HookCallback = Callable[[HookContext], None]
-"""A hook callback. Returns ``None`` on success, raises ``HookError``
-or ``HookHalt`` to signal control flow per ``exceptions.py``."""
-
-
-class HookRegistry:
-    """Insertion-ordered registry of hook callbacks per event.
-
-    Single instance per CLI invocation. Built once in ``cli.main()``
-    and shared with ``dispatch()`` so dispatcher events and CLI events
-    are routed through the same callback set.
-    """
-
-    def __init__(self) -> None:
-        self._hooks: dict[HookEvent, list[HookCallback]] = {}
-
-    def register(self, event: HookEvent, callback: HookCallback) -> None:
-        """Register ``callback`` for ``event``.
-
-        Multiple callbacks for the same event are allowed; they fire
-        in registration order.
-        """
-        self._hooks.setdefault(event, []).append(callback)
-
-    def for_event(self, event: HookEvent) -> tuple[HookCallback, ...]:
-        """Return callbacks registered for ``event`` in insertion order.
-
-        Returns an empty tuple when no callbacks are registered — the
-        runner uses this to short-circuit a no-op fast path.
-        """
-        return tuple(self._hooks.get(event, ()))
-
-    def events(self) -> Iterable[HookEvent]:
-        """Iterate over events that have at least one callback.
-
-        Diagnostics-only; not used on the hot path.
-        """
-        return self._hooks.keys()
-
-
-__all__ = ["HookCallback", "HookRegistry"]

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

@@ -1,73 +0,0 @@
-"""``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/dist/agent-src/templates/scripts/work_engine/hooks/settings.py

@@ -1,196 +0,0 @@
-"""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.
-
-Per road-to-portable-dev-preferences P3, the YAML read goes through
-:func:`work_engine._lib.agent_settings.load_agent_settings`, which
-cascades the whitelisted ``rule_loading_tier`` (and other DX-comfort keys)
-from ``~/.event4u/agent-config/agent-settings.yml`` (legacy
-``~/.config/agent-config/agent-settings.yml`` read as fallback) when
-the project file omits them. Project values always win.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-from work_engine._lib.agent_settings import load_agent_settings
-from work_engine.scoring.decision_engine import (
-    DecisionEngineConfigError,
-    DecisionEngineSettings,
-    parse as _parse_decision_engine,
-)
-
-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.
-
-    ``decision_engine`` carries the parsed gate config so
-    :class:`DecisionGateHook` can read it without re-parsing
-    ``.agent-settings.yml``. When the block is absent or malformed the
-    field stays at the default (every gate ``off``).
-    """
-
-    enabled: bool = False
-    trace: bool = False
-    halt_surface_audit: bool = False
-    state_shape_validation: bool = False
-    directive_set_guard: bool = False
-    decision_trace: bool = False
-    memory_visibility: bool = False
-    memory_visibility_off: bool = False
-    memory_cadence: str = "always"
-    chat_history_enabled: bool = False
-    chat_history_script: str = DEFAULT_CHAT_HISTORY_SCRIPT
-    decision_engine: DecisionEngineSettings = DecisionEngineSettings()
-
-
-_DEFAULT = HookSettings()
-
-
-def load_hook_settings(
-    settings_path: Path | str | None = None,
-    user_global_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.
-    ``user_global_path`` defaults to
-    ``~/.event4u/agent-config/agent-settings.yml`` (with a read fallback
-    to the legacy ``~/.config/agent-config/agent-settings.yml``) and
-    only cascades the whitelisted DX-comfort keys (currently
-    ``rule_loading_tier`` and ``memory.cadence``) when the project file
-    omits them. See road-to-portable-dev-preferences P3.
-    """
-    path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
-    raw = load_agent_settings(
-        project_path=path,
-        user_global_path=user_global_path,
-    )
-    if not raw:
-        return _DEFAULT
-    return _settings_from_raw(raw)
-
-
-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)
-
-    decision_engine_raw = data.get("decision_engine")
-    try:
-        decision_engine_settings = _parse_decision_engine(decision_engine_raw)
-    except DecisionEngineConfigError:
-        decision_engine_settings = DecisionEngineSettings()
-
-    if not enabled:
-        return HookSettings(
-            enabled=False,
-            decision_engine=decision_engine_settings,
-        )
-
-    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)
-    )
-
-    decision_trace_on = decision_engine_settings.surface_traces
-
-    memory_section = data.get("memory")
-    visibility_off = False
-    memory_cadence = "always"
-    if isinstance(memory_section, dict):
-        raw = memory_section.get("visibility")
-        if isinstance(raw, str) and raw.strip().lower() == "off":
-            visibility_off = True
-        elif isinstance(raw, bool) and raw is False:
-            visibility_off = True
-        cadence_raw = memory_section.get("cadence")
-        if cadence_raw is not None:
-            memory_cadence = str(cadence_raw).strip().lower() or "always"
-
-    memory_hooks = hooks.get("memory_visibility")
-    if isinstance(memory_hooks, dict):
-        memory_visibility_on = _coerce_bool(
-            memory_hooks.get("enabled"), True,
-        )
-    else:
-        memory_visibility_on = True
-
-    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
-        ),
-        decision_trace=decision_trace_on,
-        memory_visibility=memory_visibility_on,
-        memory_visibility_off=visibility_off,
-        memory_cadence=memory_cadence,
-        chat_history_enabled=chat_block_enabled and global_chat_on,
-        chat_history_script=chat_script,
-        decision_engine=decision_engine_settings,
-    )
-
-
-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",
-]