@event4u/agent-config 6.0.0 → 7.0.0

package/dist/agent-src/templates/scripts/work_engine/dispatcher.py

@@ -1,331 +0,0 @@
-"""Linear step dispatcher for ``/implement-ticket``.
-
-The dispatcher holds no business logic. It walks the fixed eight-step
-order declared in ``docs/contracts/implement-ticket-flow.md``, hands
-each step a live ``DeliveryState``, and honours the three terminal
-outcomes:
-
-- ``SUCCESS`` — record and advance.
-- ``BLOCKED`` — record, copy questions onto the state, halt.
-- ``PARTIAL`` — record, copy questions onto the state, halt.
-
-Resumption semantics (Option A, flow contract §agent-directives):
-steps whose name is already marked ``success`` in
-``state.outcomes`` are **skipped**. This lets a caller re-invoke the
-dispatcher after executing an agent-directive (the ``implement``,
-``test``, ``verify`` steps cannot run from pure Python), update the
-relevant slice of ``DeliveryState``, record ``success`` on the
-resumed step, and continue without replaying earlier work.
-
-Step handlers are injected by the caller rather than discovered at
-import time. Phase 1 shipped the dispatcher with mock handlers;
-Phase 2 wires the real ones under ``steps/``. Keeping injection
-explicit means the dispatcher is trivially testable and never
-depends on handler import order.
-"""
-from __future__ import annotations
-
-from collections.abc import Mapping
-from importlib import import_module
-from typing import Any
-
-from .delivery_state import DeliveryState, Outcome, Step, StepResult
-from .hooks import HookContext, HookEvent, HookHalt, HookRunner
-from .state import KNOWN_DIRECTIVE_SETS
-
-_NOOP_RUNNER: HookRunner = HookRunner()
-"""Shared empty-registry runner reused when ``dispatch`` is called
-without an explicit ``hooks`` argument. ``HookRunner.emit`` short-circuits
-when no callbacks are registered, so the hot path stays branch-light
-while the call sites stay uniform."""
-
-STEP_ORDER: tuple[str, ...] = (
-    "refine",
-    "memory",
-    "analyze",
-    "plan",
-    "implement",
-    "test",
-    "verify",
-    "report",
-)
-"""Canonical execution order. Eight steps, fixed, no branching.
-
-Changing this order is a roadmap-level decision — not a PR rider — per
-the surface-growth guardrails in
-``agents/roadmaps/road-to-implement-ticket.md``.
-"""
-
-DEFAULT_DIRECTIVE_SET: str = "backend"
-"""Directive set chosen when ``state`` does not carry one explicitly.
-
-Backwards compatibility for v0 ``DeliveryState`` callers: the legacy
-shape has no ``directive_set`` field, so ``select_directive_set``
-falls back to ``"backend"`` and the engine behaves exactly as it did
-before R1 Phase 4.
-"""
-
-# Schema enum names use hyphens (``ui-trivial``) but Python packages
-# cannot. The loader is the single place that bridges between the two
-# forms; everywhere else uses the wire form.
-_PACKAGE_NAME_OVERRIDES: Mapping[str, str] = {"ui-trivial": "ui_trivial"}
-
-
-def dispatch(
-    state: DeliveryState,
-    steps: Mapping[str, Step],
-    hooks: HookRunner | None = None,
-) -> tuple[Outcome, str | None]:
-    """Run the eight steps linearly against ``state``.
-
-    Returns a ``(final_outcome, halting_step)`` tuple. ``halting_step``
-    is ``None`` when every step succeeded; otherwise it carries the
-    name of the step whose result halted the flow.
-
-    Parameters
-    ----------
-    state:
-        Live ``DeliveryState``. Mutated in place: each step's outcome
-        is recorded in ``state.outcomes`` under the step name, and
-        any surfaced questions land on ``state.questions``.
-    steps:
-        Mapping from step name to handler. Every entry in
-        :data:`STEP_ORDER` must be present; missing entries raise
-        ``KeyError`` at dispatch time rather than silently skipping,
-        so incomplete wiring surfaces as a hard failure.
-    hooks:
-        Optional :class:`HookRunner` carrying a registry of dispatcher-
-        layer hooks (``before_step``, ``after_step``, ``on_halt``,
-        ``on_error``). Default ``None`` preserves every existing call
-        site verbatim — internally ``dispatch`` falls back to a shared
-        empty-registry runner so hook bookkeeping stays uniform without
-        a per-emit ``if hooks is None`` branch.
-
-    Raises
-    ------
-    KeyError
-        If ``steps`` does not cover every entry in
-        :data:`STEP_ORDER`.
-    """
-    _assert_all_steps_present(steps)
-
-    # Clear stale questions from a previous halt before we resume so
-    # the caller never mistakes old options for fresh ones.
-    state.questions = []
-
-    runner = hooks if hooks is not None else _NOOP_RUNNER
-
-    for name in STEP_ORDER:
-        if state.outcomes.get(name) == Outcome.SUCCESS.value:
-            # Already completed on an earlier invocation — skip per the
-            # resume contract. The caller is responsible for keeping
-            # ``state.outcomes`` and the matching slice in sync.
-            continue
-
-        before_halt = runner.emit(
-            HookEvent.BEFORE_STEP,
-            HookContext(step_name=name, delivery=state),
-        )
-        if before_halt is not None:
-            return _hook_halt_blocked(state, runner, name, before_halt, result=None)
-
-        handler = steps[name]
-        try:
-            result = handler(state)
-        except Exception as exc:
-            # Let dispatcher-layer observers see the failure before the
-            # exception unwinds the engine. ``on_error`` is observe-only;
-            # the original exception is always re-raised.
-            runner.emit(
-                HookEvent.ON_ERROR,
-                HookContext(step_name=name, delivery=state, exception=exc),
-            )
-            raise
-        _validate_step_result(name, result)
-
-        state.outcomes[name] = result.outcome.value
-
-        after_halt = runner.emit(
-            HookEvent.AFTER_STEP,
-            HookContext(step_name=name, delivery=state, result=result),
-        )
-        if after_halt is not None:
-            return _hook_halt_blocked(state, runner, name, after_halt, result=result)
-
-        if result.outcome is Outcome.BLOCKED:
-            state.questions = list(result.questions)
-            _emit_on_halt(runner, name, state, result)
-            return Outcome.BLOCKED, name
-
-        if result.outcome is Outcome.PARTIAL:
-            state.questions = list(result.questions)
-            _emit_on_halt(runner, name, state, result)
-            return Outcome.PARTIAL, name
-
-    return Outcome.SUCCESS, None
-
-
-def _hook_halt_blocked(
-    state: DeliveryState,
-    runner: HookRunner,
-    name: str,
-    halt: HookHalt,
-    result: StepResult | None,
-) -> tuple[Outcome, str | None]:
-    """Translate a hook-driven :class:`HookHalt` into a clean engine halt.
-
-    Hook-driven halts are treated as first-class engine halts per the
-    P2 contract: the dispatcher returns ``(BLOCKED, step_name)`` with
-    ``state.questions`` rendered verbatim from the halt's ``surface``.
-    The step's outcome marker is set to ``"blocked"`` only when the
-    halt fires before the handler ran (so resume re-enters the gate);
-    when it fires after the handler, the marker the handler produced
-    is preserved so resume reflects what actually happened.
-    """
-    if result is None:
-        state.outcomes[name] = Outcome.BLOCKED.value
-    state.questions = list(halt.surface)
-    _emit_on_halt(runner, name, state, result)
-    return Outcome.BLOCKED, name
-
-
-def _emit_on_halt(
-    runner: HookRunner,
-    name: str,
-    state: DeliveryState,
-    result: StepResult | None,
-) -> None:
-    """Fire ``on_halt`` as an observe-only event.
-
-    A :class:`HookHalt` raised from inside ``on_halt`` would create a
-    halt-of-a-halt loop; the runner returns it but the dispatcher
-    deliberately ignores it — the halt surface is already populated.
-    """
-    runner.emit(
-        HookEvent.ON_HALT,
-        HookContext(step_name=name, delivery=state, result=result),
-    )
-
-
-def _assert_all_steps_present(steps: Mapping[str, Step]) -> None:
-    """Reject an incomplete step mapping up front.
-
-    We deliberately fail loudly here: a missing step would otherwise
-    raise deep inside the dispatch loop after partial state mutation,
-    which makes debugging the wiring harder than it needs to be.
-    """
-    missing = [name for name in STEP_ORDER if name not in steps]
-    if missing:
-        raise KeyError(
-            "Step mapping is missing handlers for: " + ", ".join(missing),
-        )
-
-
-def _validate_step_result(name: str, result: StepResult) -> None:
-    """Enforce the blocked/partial invariant: questions must be set.
-
-    A step that blocks without surfacing a question is a bug — there
-    is nothing for the user to answer. We raise ``ValueError`` instead
-    of silently recording the outcome so the defect is visible at the
-    earliest possible point.
-    """
-    if result.outcome in (Outcome.BLOCKED, Outcome.PARTIAL) and not result.questions:
-        raise ValueError(
-            f"Step {name!r} returned {result.outcome.value} with no questions; "
-            "blocked and partial outcomes must surface at least one numbered option.",
-        )
-
-
-def select_directive_set(state: Any) -> str:
-    """Return the directive set name to dispatch ``state`` against.
-
-    Looks for ``state.directive_set`` (the v1 :class:`work_engine.state.WorkState`
-    field) and falls back to :data:`DEFAULT_DIRECTIVE_SET` when the
-    attribute is missing — the legacy v0 :class:`DeliveryState` has no
-    such field, and existing callers must keep working unchanged
-    until R1 Phase 4 Step 1 lands the runtime switch.
-
-    The returned name is validated against :data:`KNOWN_DIRECTIVE_SETS`;
-    an unknown value raises ``ValueError`` rather than silently
-    falling back, so a typo in a hand-written state file fails loudly
-    instead of producing surprising behavior.
-    """
-    name = getattr(state, "directive_set", DEFAULT_DIRECTIVE_SET)
-    if not isinstance(name, str) or not name:
-        raise ValueError(
-            f"directive_set must be a non-empty string; got {name!r}",
-        )
-    if name not in KNOWN_DIRECTIVE_SETS:
-        raise ValueError(
-            f"unknown directive_set {name!r}; "
-            f"known sets: {sorted(KNOWN_DIRECTIVE_SETS)}",
-        )
-    return name
-
-
-def load_directive_set(name: str) -> Mapping[str, Step]:
-    """Import the ``directives.<name>`` package and return its step mapping.
-
-    The selected set's ``__init__`` exposes a ``get_steps()`` factory
-    (see :class:`work_engine.directives.backend`) that returns the
-    ``{step_name: handler}`` mapping the dispatcher walks. Unimplemented
-    sets (``ui``, ``ui-trivial``, ``mixed``) raise
-    ``NotImplementedError`` from their ``get_steps()`` so the failure
-    point is the loader, not a half-walked dispatch loop.
-
-    The schema enum carries hyphenated wire names (``ui-trivial``) but
-    Python packages must use underscores; :data:`_PACKAGE_NAME_OVERRIDES`
-    is the single translation point.
-    """
-    module = _import_directive_set(name)
-    get_steps = getattr(module, "get_steps", None)
-    if not callable(get_steps):
-        raise AttributeError(
-            f"work_engine.directives.{module.__name__.rsplit('.', 1)[-1]} "
-            "does not expose a callable get_steps()",
-        )
-    steps = get_steps()
-    if not isinstance(steps, Mapping):
-        raise TypeError(
-            f"work_engine.directives.{module.__name__.rsplit('.', 1)[-1]}"
-            f".get_steps() must return a Mapping; "
-            f"got {type(steps).__name__}",
-        )
-    return steps
-
-
-def assert_kind_supported(kind: str, set_name: str) -> None:
-    """Raise ``NotImplementedError`` if ``set_name`` cannot handle ``kind``.
-
-    Reads the per-set ``SUPPORTED_KINDS`` tuple (see
-    :data:`work_engine.directives.backend.SUPPORTED_KINDS`) and checks
-    membership. Distinct from :func:`select_directive_set`, which only
-    validates the directive-set *name*: this gate validates the
-    name/kind *pair*, so a future schema widening that adds new
-    ``input.kind`` values (R2 ``prompt``) halts loudly at the boundary
-    instead of crashing inside the first deterministic step.
-
-    Sets that have no ``SUPPORTED_KINDS`` attribute are treated as
-    "supports nothing" — the unimplemented stubs (``ui``,
-    ``ui-trivial``, ``mixed``) already raise from ``get_steps()``, so
-    this branch only matters during the brief window between adding a
-    new directive set and wiring its capability tuple.
-    """
-    module = _import_directive_set(set_name)
-    supported = getattr(module, "SUPPORTED_KINDS", ())
-    if kind not in supported:
-        raise NotImplementedError(
-            f"directive_set {set_name!r} does not handle "
-            f"input.kind={kind!r}; supported kinds: {sorted(set(supported))}",
-        )
-
-
-def _import_directive_set(name: str):
-    """Validate ``name`` and import the matching package module."""
-    if name not in KNOWN_DIRECTIVE_SETS:
-        raise ValueError(
-            f"unknown directive_set {name!r}; "
-            f"known sets: {sorted(KNOWN_DIRECTIVE_SETS)}",
-        )
-    package_name = _PACKAGE_NAME_OVERRIDES.get(name, name)
-    return import_module(f"work_engine.directives.{package_name}")

package/dist/agent-src/templates/scripts/work_engine/emitters.py

@@ -1,68 +0,0 @@
-"""Stdout / stderr emitters for the CLI entry point.
-
-Extracted from ``cli.py`` in P2.3 of
-``road-to-post-pr29-optimize.md``. Holds the two output helpers that
-shape the wire surface of ``main()``: the SUCCESS/halt branch printed
-on stdout, and the lifecycle-hook halt surface printed on stderr.
-"""
-from __future__ import annotations
-
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-
-from .delivery_state import Outcome
-from .hooks import HookHalt
-from .state import WorkState, dump
-
-
-def _emit(work: WorkState, final: Outcome, halting: str | None) -> None:
-    if final is Outcome.SUCCESS:
-        print(work.report)
-        return
-    print(f"[halt] outcome={final.value} step={halting or '(none)'}")
-    for line in work.questions:
-        print(line)
-
-
-def _emit_halt(
-    halt: HookHalt,
-    *,
-    work: WorkState | None = None,
-    state_file: Path | None = None,
-    event: str | None = None,
-) -> int:
-    """Render a :class:`HookHalt` surface to stderr and return exit 2.
-
-    Per the P3 halt branch table, every CLI-layer halt yields exit code
-    ``2`` regardless of which event fired it. State persistence is
-    governed by *where* in ``main`` the halt is detected: the call site
-    decides whether ``_save`` already ran.
-
-    When ``work`` + ``state_file`` are provided AND the state file
-    already exists on disk, the halt is appended to ``work.halts[]``
-    and the state is re-saved. This lets ``agent-config explain last``
-    surface the halt reason later. Fresh-run halts before the first
-    ``_save`` (state file absent) still leave no state on disk — the
-    pre-explain-v2 contract is preserved.
-    """
-    if halt.surface:
-        for line in halt.surface:
-            print(line, file=sys.stderr)
-    else:
-        print(f"halt: {halt.reason}", file=sys.stderr)
-    if work is not None and state_file is not None and state_file.exists():
-        work.halts.append({
-            "reason": halt.reason,
-            "step": event or "",
-            "surface": list(halt.surface),
-            "timestamp": datetime.now(tz=timezone.utc).isoformat(),
-        })
-        try:
-            dump(work, state_file)
-        except Exception:  # never let halt persistence mask the halt
-            pass
-    return 2
-
-
-__all__ = ["_emit", "_emit_halt"]

package/dist/agent-src/templates/scripts/work_engine/errors.py

@@ -1,19 +0,0 @@
-"""CLI-layer error type used by the dispatcher entry point.
-
-Lives in its own module so the helper modules (``state_io``,
-``input_builders``, etc.) can raise it without depending on
-``cli.py``, which would create an import cycle.
-
-Behaviour is identical to the original ``cli._CLIError`` it replaced
-in P2.3 of ``road-to-post-pr29-optimize.md`` — same name (private,
-underscore-prefixed) and same role: convert to exit code ``2`` at the
-``main()`` boundary.
-"""
-from __future__ import annotations
-
-
-class _CLIError(Exception):
-    """Raised on configuration or I/O problems. Converted to exit code 2."""
-
-
-__all__ = ["_CLIError"]

package/dist/agent-src/templates/scripts/work_engine/hook_bootstrap.py

@@ -1,91 +0,0 @@
-"""Lifecycle-hook registry assembly for the CLI entry point.
-
-Extracted from ``cli.py`` in P2.3 of
-``road-to-post-pr29-optimize.md``. Owns nothing but
-``_build_hook_registry`` and its chat-history helper. The function
-remains re-exported from ``work_engine.cli`` so the existing test
-import (``from work_engine.cli import _build_hook_registry``) and
-monkeypatch target (``work_engine.cli._build_hook_registry``) keep
-working without a breaking change.
-"""
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-from .hooks import HookRegistry
-from .hooks.builtin import (
-    ChatHistoryAppendHook,
-    ChatHistoryHaltAppendHook,
-    DecisionTraceHook,
-    DirectiveSetGuardHook,
-    HaltSurfaceAuditHook,
-    MemoryVisibilityHook,
-    StateShapeValidationHook,
-    TraceHook,
-    build_decision_gate_hook,
-)
-from .hooks.settings import HookSettings, load_hook_settings
-
-
-def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
-    """Build the CLI-side :class:`HookRegistry` for one ``main()`` run.
-
-    Reads ``hooks.*`` from ``.agent-settings.yml`` and registers the
-    enabled hooks. The master switch ``hooks.enabled`` defaults to
-    ``False`` when the block (or the file) is missing — the registry
-    stays empty and golden replay flows are byte-stable.
-
-    ``--no-hooks`` on the CLI forces an empty registry regardless of
-    settings, which is the explicit escape hatch golden-replay test
-    harnesses can use.
-    """
-    registry = HookRegistry()
-    if getattr(args, "no_hooks", False):
-        return registry
-
-    settings_path = getattr(args, "hooks_config", None)
-    settings = load_hook_settings(settings_path)
-    if not settings.enabled:
-        return registry
-
-    if settings.trace:
-        TraceHook().register(registry)
-    if settings.halt_surface_audit:
-        HaltSurfaceAuditHook().register(registry)
-    if settings.state_shape_validation:
-        StateShapeValidationHook().register(registry)
-    if settings.directive_set_guard:
-        DirectiveSetGuardHook().register(registry)
-    if settings.decision_trace:
-        DecisionTraceHook().register(registry)
-    gate_hook = build_decision_gate_hook(settings.decision_engine)
-    if gate_hook is not None:
-        gate_hook.register(registry)
-    if settings.memory_visibility:
-        MemoryVisibilityHook(
-            memory_cadence=settings.memory_cadence,
-            visibility_off=settings.memory_visibility_off,
-        ).register(registry)
-    if settings.chat_history_enabled:
-        _register_chat_history_hooks(registry, settings)
-
-    return registry
-
-
-def _register_chat_history_hooks(
-    registry: HookRegistry, settings: HookSettings,
-) -> None:
-    """Register the structural chat-history hooks bound to the configured script.
-
-    Hook-only contract (post road-to-chat-history-hook-only): only the
-    append + halt-append hooks remain; cooperative ``turn-check`` /
-    ``heartbeat`` hooks were removed when the cooperative always-rules
-    were retired.
-    """
-    script = Path(settings.chat_history_script)
-    ChatHistoryAppendHook(script).register(registry)
-    ChatHistoryHaltAppendHook(script).register(registry)
-
-
-__all__ = ["_build_hook_registry", "_register_chat_history_hooks"]

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

@@ -1,54 +0,0 @@
-"""``work_engine.hooks`` — cross-cutting lifecycle hooks for the engine.
-
-Phase 1 of ``agents/roadmaps/road-to-work-engine-hooks.md`` ships the
-primitives only. The dispatcher and CLI are not yet instrumented;
-golden tests must remain byte-identical until Phase 2 / Phase 3 land.
-
-Public surface:
-
-- :class:`HookEvent` — ten lifecycle events, two layers.
-- :class:`HookContext` — per-event payload.
-- :class:`HookError` / :class:`HookHalt` — three-tier error contract.
-- :class:`HookRegistry` — insertion-ordered event \u2192 callbacks map.
-- :class:`HookRunner` — single emit point, owns the error contract.
-
-The principle is documented in
-``agents/roadmaps/road-to-work-engine-hooks.md`` § Underlying
-principle: agent hooks are emulated by moving lifecycle ownership
-from the agent into the work engine. The engine owns boundaries.
-"""
-from __future__ import annotations
-
-from .builtin import (
-    ChatHistoryAppendHook,
-    ChatHistoryHaltAppendHook,
-    DecisionTraceHook,
-    DirectiveSetGuardHook,
-    HaltSurfaceAuditHook,
-    MemoryVisibilityHook,
-    StateShapeValidationHook,
-    TraceHook,
-)
-from .context import HookContext
-from .events import HookEvent
-from .exceptions import HookError, HookHalt
-from .registry import HookCallback, HookRegistry
-from .runner import HookRunner
-
-__all__ = [
-    "ChatHistoryAppendHook",
-    "ChatHistoryHaltAppendHook",
-    "DecisionTraceHook",
-    "DirectiveSetGuardHook",
-    "HaltSurfaceAuditHook",
-    "HookCallback",
-    "HookContext",
-    "HookError",
-    "HookEvent",
-    "HookHalt",
-    "HookRegistry",
-    "HookRunner",
-    "MemoryVisibilityHook",
-    "StateShapeValidationHook",
-    "TraceHook",
-]

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

@@ -1,35 +0,0 @@
-"""Concrete observability hooks shipped with the engine.
-
-Phase 4 hooks: low-risk, default-off, observe-only. They are registered
-by ``cli._build_hook_registry`` only when explicitly enabled in
-``.agent-settings.yml`` (Phase 6 wires the settings → registry path).
-
-Each hook is a small class exposing a ``register(registry)`` method so
-the registry stays the single source of truth for event → callback
-wiring. None of these hooks mutate engine state; failures surface as
-:class:`HookError` (non-fatal, the runner warns and continues).
-"""
-from __future__ import annotations
-
-from .chat_history_append import ChatHistoryAppendHook
-from .chat_history_halt_append import ChatHistoryHaltAppendHook
-from .decision_gate import DecisionGateHook, build_decision_gate_hook
-from .decision_trace import DecisionTraceHook
-from .directive_set_guard import DirectiveSetGuardHook
-from .halt_surface_audit import HaltSurfaceAuditHook
-from .memory_visibility import MemoryVisibilityHook
-from .state_shape_validation import StateShapeValidationHook
-from .trace import TraceHook
-
-__all__ = [
-    "ChatHistoryAppendHook",
-    "ChatHistoryHaltAppendHook",
-    "DecisionGateHook",
-    "DecisionTraceHook",
-    "DirectiveSetGuardHook",
-    "HaltSurfaceAuditHook",
-    "MemoryVisibilityHook",
-    "StateShapeValidationHook",
-    "TraceHook",
-    "build_decision_gate_hook",
-]

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

@@ -1,59 +0,0 @@
-"""Shared plumbing for chat-history hooks.
-
-Subprocess-driven so the work-engine package stays decoupled from
-``scripts/chat_history.py``'s internals. The ``runner`` injection
-point is the test seam — production passes ``subprocess.run``,
-tests pass a fake.
-"""
-from __future__ import annotations
-
-import subprocess
-import sys
-from pathlib import Path
-from typing import Callable, Sequence
-
-ProcessRunner = Callable[[Sequence[str]], "subprocess.CompletedProcess[str]"]
-"""Callable that runs a subprocess. Production default: ``_default_runner``."""
-
-EXIT_OK = 0
-EXIT_MISSING = 10
-EXIT_FOREIGN = 11
-EXIT_RETURNING = 12
-
-
-def _default_runner(cmd: Sequence[str]) -> "subprocess.CompletedProcess[str]":
-    return subprocess.run(list(cmd), capture_output=True, text=True, check=False)
-
-
-class _ChatHistoryHookBase:
-    """Shared plumbing — script path and runner.
-
-    Schema v4 derives session attribution from the platform ``session_id``
-    (passed by the platform-hook dispatcher), not from a derived
-    first-user-msg. work-engine internal hooks have no platform session
-    in scope, so they omit ``--session-id`` and entries land in the
-    ``<unknown>`` session bucket.
-    """
-
-    def __init__(
-        self,
-        script_path: Path,
-        *,
-        runner: ProcessRunner | None = None,
-    ) -> None:
-        self.script_path = Path(script_path)
-        self._runner = runner or _default_runner
-
-    def _invoke(self, *args: str) -> "subprocess.CompletedProcess[str]":
-        cmd = [sys.executable, str(self.script_path), *args]
-        return self._runner(cmd)
-
-
-__all__ = [
-    "EXIT_FOREIGN",
-    "EXIT_MISSING",
-    "EXIT_OK",
-    "EXIT_RETURNING",
-    "ProcessRunner",
-    "_ChatHistoryHookBase",
-]