froid-loop 0.11.1__py3-none-any.whl

froid_loop/settings_schema.py

@@ -0,0 +1,276 @@
+"""Schema-driven settings: the presentation layer over policy.toml.
+
+The settings UI used to carry a hand-written list of field descriptors. That
+list now lives in ``data/settings/core.toml`` as a *schema* — widget kind,
+label, help text, options, bounds — while defaults and select options are
+*referenced* from the ``policy.py`` dataclasses/enum-sets rather than copied, so
+``policy.py`` stays the single source of truth for the runtime model and a sync
+test guarantees the schema can never drift from it.
+
+Two shapes mirror the old screen vocabulary:
+
+  * ``SettingSpec`` — one field (the old ``_Field``): section, key, widget kind,
+    options, resolved default, placeholder, numeric bounds, label, description.
+    ``widget_id`` is unchanged so every existing widget id (``#limits-max_review_cycles``,
+    ``#adapter-review-model`` …) is byte-identical.
+  * ``SectionSpec`` — a collapsible group: name (the TOML section key), display
+    label, description, its fields, and the owning plugin ("" for core).
+
+``load_core_schema()`` parses the bundled core schema; ``build_registry(project,
+policy)`` returns it plus a ``PluginInfo`` for every *discovered* plugin — its
+enable state (membership in ``[plugins] enabled``), whether enabling it grants
+trust (a ``[python]`` module), and its ``[[settings]]`` fields. The screen groups
+these under a dedicated Plugins area; reading manifests never imports plugin
+Python. The registry is what the settings screen consumes — it never reaches
+back into this module's internals.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field, replace
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from . import policy as policy_mod
+from .plugins import load_plugins
+from .plugins.model import SettingSpec as PluginSettingSpec
+from .policy import STAGES
+
+# plugin [[settings]] types -> settings-screen widget kinds. The screen knows
+# switch/int/float/str/select; a plugin declares bool/int/float/str/select.
+_PLUGIN_KIND = {"bool": "switch", "int": "int", "float": "float", "str": "str", "select": "select"}
+
+
+@dataclass(frozen=True)
+class SettingSpec:
+    """One settings field. Same vocabulary as the screen's former ``_Field`` so
+    the generic compose/collect/save logic is untouched."""
+
+    section: str
+    key: str
+    kind: str  # select | int | float | str | switch | lines | args
+    options: tuple[str, ...] = ()
+    default: Any = None
+    placeholder: str = ""
+    minimum: float | None = None
+    maximum: float | None = None
+    label: str = ""  # display override; falls back to key when empty
+    description: str = ""  # muted caption shown below the field row
+
+    @property
+    def widget_id(self) -> str:
+        return f"{self.section}-{self.key}".replace(".", "-")
+
+
+@dataclass(frozen=True)
+class SectionSpec:
+    """A collapsible settings group. ``name`` is the policy.toml section key
+    (may be dotted, e.g. ``adapter.dev``). Core only — plugin settings are
+    carried by ``PluginInfo``."""
+
+    name: str
+    fields: tuple[SettingSpec, ...]
+    label: str = ""  # display label; falls back to name
+    description: str = ""
+
+    @property
+    def title(self) -> str:
+        base = self.label or self.name
+        return f"{base} — {self.description}" if self.description else base
+
+
+@dataclass(frozen=True)
+class PluginInfo:
+    """One discovered plugin as the settings screen sees it: an enable toggle
+    (when trust-gated) plus its settings fields.
+
+    ``trust_needed`` is True for a plugin that declares an in-process ``[python]``
+    module — enabling it grants trust (its name enters ``[plugins] enabled``).
+    Data-only plugins are always active and carry no toggle. ``fields`` are this
+    plugin's settings under ``plugins.<name>``; they render whether or not the
+    plugin is enabled (the screen greys them until enabled)."""
+
+    name: str
+    description: str
+    enabled: bool
+    trust_needed: bool
+    fields: tuple[SettingSpec, ...] = ()
+
+
+@dataclass(frozen=True)
+class SettingsRegistry:
+    """Core schema plus a PluginInfo per discovered plugin — the settings
+    screen's source.
+
+    ``plugin_schemas`` maps each plugin that contributes settings to its declared
+    specs so the screen can pass them to ``policy.loads`` for typed validation of
+    the ``[plugins.<name>]`` tables on save (every discovered plugin, since
+    settings are data that may be set whether or not the plugin is enabled).
+    """
+
+    sections: tuple[SectionSpec, ...]
+    plugins: tuple[PluginInfo, ...] = ()
+    plugin_schemas: dict[str, tuple[PluginSettingSpec, ...]] = field(default_factory=dict)
+
+    def fields(self) -> tuple[SettingSpec, ...]:
+        core = tuple(f for s in self.sections for f in s.fields)
+        plugin = tuple(f for p in self.plugins for f in p.fields)
+        return core + plugin
+
+
+# --------------------------------------------------------------- ref resolution
+
+
+def _resolve_ref(ref: str) -> Any:
+    """``"ScmPolicy.merge_strategy"`` -> the dataclass default value;
+    ``"GATE_MODES"`` -> the module-level enum set (caller sorts it)."""
+    cls_name, _, attr = ref.partition(".")
+    target = getattr(policy_mod, cls_name)
+    return getattr(target, attr) if attr else target
+
+
+def _resolve_field(section: str, raw: dict) -> SettingSpec:
+    if "options_ref" in raw:
+        options = tuple(sorted(_resolve_ref(raw["options_ref"])))
+    else:
+        options = tuple(str(o) for o in raw.get("options", ()))
+    if "default_ref" in raw:
+        default = _resolve_ref(raw["default_ref"])
+    else:
+        default = raw.get("default")
+    return SettingSpec(
+        section=section,
+        key=str(raw["key"]),
+        kind=str(raw["kind"]),
+        options=options,
+        default=default,
+        placeholder=str(raw.get("placeholder", "")),
+        minimum=raw.get("minimum"),
+        maximum=raw.get("maximum"),
+        label=str(raw.get("label", "")),
+        description=str(raw.get("description", "")),
+    )
+
+
+def _expand_section(raw: dict) -> list[SectionSpec]:
+    """One core.toml ``[[section]]`` -> one SectionSpec, except a stage template
+    (``expand_stages``) fans out to one section per STAGES entry, substituting
+    ``{stage}`` in the name/label/description and reusing the same field set."""
+    fields_raw = raw.get("field", [])
+    if raw.get("expand_stages"):
+        sections = []
+        for stage in STAGES:
+            name = str(raw["name"]).format(stage=stage)
+            sections.append(
+                SectionSpec(
+                    name=name,
+                    fields=tuple(_resolve_field(name, f) for f in fields_raw),
+                    label=str(raw.get("label", "")).format(stage=stage),
+                    description=str(raw.get("description", "")).format(stage=stage),
+                )
+            )
+        return sections
+    name = str(raw["name"])
+    return [
+        SectionSpec(
+            name=name,
+            fields=tuple(_resolve_field(name, f) for f in fields_raw),
+            label=str(raw.get("label", "")),
+            description=str(raw.get("description", "")),
+        )
+    ]
+
+
+def load_core_schema() -> tuple[SectionSpec, ...]:
+    """Parse the bundled core schema into ordered SectionSpecs (render order)."""
+    text = (
+        resources.files("froid_loop.data").joinpath("settings/core.toml").read_text(encoding="utf-8")
+    )
+    doc = tomllib.loads(text)
+    sections: list[SectionSpec] = []
+    for raw in doc.get("section", []):
+        sections.extend(_expand_section(raw))
+    return tuple(sections)
+
+
+# ------------------------------------------------------------- plugin sections
+
+
+def _plugin_fields(name: str, specs: tuple[PluginSettingSpec, ...]) -> tuple[SettingSpec, ...]:
+    section = f"plugins.{name}"
+    return tuple(
+        SettingSpec(
+            section=section,
+            key=s.key,
+            kind=_PLUGIN_KIND.get(s.type, "str"),
+            options=s.options,
+            default=s.default,
+            minimum=s.min,
+            maximum=s.max,
+            label=s.label,
+            description=s.help,
+        )
+        for s in specs
+    )
+
+
+def _inject_mux_backends(sections: tuple[SectionSpec, ...], policy: Any) -> tuple[SectionSpec, ...]:
+    """Populate the ``mux.backend`` select with the backends registered on THIS host.
+
+    Registered backends are a runtime fact (not a policy enum set), so the option
+    list is built per screen-open from ``detect_multiplexers()`` rather than baked
+    into ``core.toml``. Any value already present in policy is unioned in, so a
+    backend forced via ``froid-loop mux set --force <name>`` on a host where it is not
+    registered is never silently dropped when the settings screen saves (a blank
+    Select would collect to ``None`` = delete the key). The empty string (auto-select)
+    stays the implicit blank choice and is not listed."""
+    from .adapters.multiplexer import detect_multiplexers
+
+    current = getattr(getattr(policy, "mux", None), "backend", "") or ""
+    names = [info.name for info in detect_multiplexers()]
+    options = tuple(name for name in dict.fromkeys([*names, current]) if name)
+    out: list[SectionSpec] = []
+    for section in sections:
+        if section.name != "mux":
+            out.append(section)
+            continue
+        fields = tuple(
+            replace(f, options=options) if f.key == "backend" else f for f in section.fields
+        )
+        out.append(replace(section, fields=fields))
+    return tuple(out)
+
+
+def build_registry(project: Path | None = None, policy: Any = None) -> SettingsRegistry:
+    """Core schema, plus a PluginInfo for every *discovered* plugin.
+
+    Every plugin found by discovery is surfaced so the screen can offer an enable
+    toggle (membership in ``[plugins] enabled``) and group its settings. Reading
+    manifests never imports/executes plugin Python — that stays trust-gated for
+    hooks. A plugin's settings are data that render whether or not it is enabled
+    (the screen greys them until enabled), so ``plugin_schemas`` covers every
+    plugin that contributes settings, making each ``[plugins.<name>]`` table
+    typed on save regardless of toggle state."""
+    sections = _inject_mux_backends(load_core_schema(), policy)
+    enabled = set(getattr(getattr(policy, "plugins", None), "enabled", ()) or ())
+    manifests = load_plugins(project)
+    plugins: list[PluginInfo] = []
+    plugin_schemas: dict[str, tuple[PluginSettingSpec, ...]] = {}
+    for name in sorted(manifests):
+        manifest = manifests[name]
+        plugins.append(
+            PluginInfo(
+                name=name,
+                description=manifest.description,
+                enabled=name in enabled,
+                trust_needed=manifest.python is not None,
+                fields=_plugin_fields(name, manifest.settings),
+            )
+        )
+        if manifest.settings:
+            plugin_schemas[name] = manifest.settings
+    return SettingsRegistry(
+        sections=sections, plugins=tuple(plugins), plugin_schemas=plugin_schemas
+    )

froid_loop/signals.py

@@ -0,0 +1,160 @@
+"""Watch the per-run events directory for hook-written event files.
+
+The hook script (data/froid_loop_hook.py) and its importable twin (:mod:`events`,
+behind ``froid-loop relay``) write one JSON file per event, atomically (tmp +
+rename), named "<ts_ns>-<task_id>-<event>.json". Plain polling of a near-empty
+directory is cheap and crash-safe; no inotify.
+
+Two directories, not one (#494). The channel now lives out of the project tree,
+under the user-scoped state root (``runs.events_dir_for``), because a branch
+switch, a worktree mount or a rollback must not be able to take a live run's
+control plane away. The *legacy* in-tree ``<run_dir>/events`` stays polled as
+well, and that is the whole version-skew guard: the relay a target project has
+installed is a COPY taken at init time, so an upgraded orchestrator routinely
+drives sessions whose hook only knows the old location. Without the second poll
+that pairing loses every Stop event and every session stalls to
+``session_timeout_min`` — the loudest possible regression, delivered silently.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class HookEvent:
+    ts: int
+    event: str  # Stop | SessionStart | SessionEnd | PreCompact
+    task_id: str
+    session_id: str | None
+    transcript_path: str | None
+    path: Path
+
+
+class SignalWatcher:
+    """Poll one or two event directories for a run's hook events.
+
+    ``events_dir`` is the primary — the out-of-tree channel this orchestrator
+    directs its sessions to via ``FROID_LOOP_EVENTS_DIR``, and the only one
+    created here. ``legacy_dir`` is the pre-#494 in-tree ``<run_dir>/events``,
+    polled when given so a project carrying an older installed relay still
+    completes its sessions (see the module docstring). It is deliberately NOT
+    created: an orchestrator that recreated the in-tree directory would undo the
+    move for the operator's `git status` while gaining nothing — a legacy relay
+    that writes there makes the directory itself.
+
+    The single-positional-argument form is unchanged, and stays the shape the
+    probe (``probe.py``, watching its own capture dir) and the unit tests use.
+    """
+
+    def __init__(self, events_dir: Path, legacy_dir: Path | None = None):
+        self.events_dir = events_dir
+        self.legacy_dir = legacy_dir
+        # Keyed by (directory, filename), not by filename: one name identifies an
+        # event only WITHIN a directory, and the two dirs are written by two
+        # independent relays. Keying on the name alone would let a file consumed
+        # from one dir mask a different event of the same name in the other, and a
+        # masked event here is a lost Stop — the run then waits out
+        # session_timeout_min with its completion signal sitting on disk.
+        self._consumed: set[tuple[str, str]] = set()
+        self._pending: list[HookEvent] = []  # polled but not yet delivered via wait_for
+        events_dir.mkdir(parents=True, exist_ok=True)
+
+    def _dirs(self) -> list[Path]:
+        """Primary first, then the legacy dir when there is a distinct one. The
+        equality check keeps a caller that passes the same path twice from
+        double-scanning; it cannot produce duplicate events either way (the
+        ``_consumed`` key would repeat), but the second scan would be pure waste."""
+        if self.legacy_dir is None or self.legacy_dir == self.events_dir:
+            return [self.events_dir]
+        return [self.events_dir, self.legacy_dir]
+
+    def poll(self) -> list[HookEvent]:
+        """Return new, well-formed events since the last poll, oldest first.
+
+        Ordering is by the parsed ``ts`` across BOTH directories, so which relay
+        wrote an event never affects where it lands in the sequence.
+
+        A missing *legacy* directory is the normal case (nothing installed writes
+        there any more) and is skipped silently. A missing *primary* still raises,
+        as it always has: this watcher created it, so its absence means something
+        removed the live control plane out from under the run.
+        """
+        events: list[HookEvent] = []
+        dirs = self._dirs()
+        for directory in dirs:
+            try:
+                entries = list(directory.iterdir())
+            except OSError:
+                if directory == self.events_dir:
+                    raise
+                continue  # legacy dir absent — the ordinary case
+            for entry in entries:
+                key = (str(directory), entry.name)
+                if key in self._consumed or entry.suffix != ".json":
+                    continue
+                self._consumed.add(key)
+                try:
+                    data = json.loads(entry.read_text(encoding="utf-8"))
+                except (json.JSONDecodeError, OSError):
+                    continue
+                if not isinstance(data, dict) or "event" not in data or "task_id" not in data:
+                    continue
+                events.append(
+                    HookEvent(
+                        ts=int(data.get("ts", 0)),
+                        event=str(data["event"]),
+                        task_id=str(data["task_id"]),
+                        session_id=data.get("session_id"),
+                        transcript_path=data.get("transcript_path"),
+                        path=entry,
+                    )
+                )
+        events.sort(key=lambda e: e.ts)
+        return events
+
+    def wait_for(
+        self,
+        task_id: str,
+        kinds: set[str],
+        timeout_s: float,
+        poll_interval: float = 1.0,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+        since_ns: int = 0,
+    ) -> HookEvent | None:
+        """Block until an event for task_id with kind in `kinds` arrives, or timeout.
+
+        Events polled but not matched stay buffered for later wait_for calls —
+        several events often land in one poll (e.g. SessionStart + Stop) and
+        none may be lost.
+
+        Events older than `since_ns` (wall-clock ns, the session's launch time)
+        are dropped: a resumed run reuses task_ids, and a fresh watcher re-sees the
+        events directory from scratch, so a prior cycle's Stop event would
+        otherwise replay instantly and the old result.json be read as a bogus
+        completion. Sessions run sequentially, so since_ns only advances; anything
+        below the current floor is genuinely stale and safe to discard.
+
+        A re-ARMED run no longer reuses them — `runs.rearm_escalation` bumps
+        `StoryTask.generation`, which `engine._session_task_id` folds into the id
+        (#705). That removes one source of collision; it does not make this floor
+        redundant, because a plain resume re-mints the SAME id by design (that is
+        how crash replay finds its record) and is the case this guard was written
+        for.
+        """
+        deadline = clock() + timeout_s
+        while True:
+            self._pending.extend(self.poll())
+            if since_ns:
+                self._pending = [e for e in self._pending if e.ts >= since_ns]
+            for i, event in enumerate(self._pending):
+                if event.task_id == task_id and event.event in kinds:
+                    return self._pending.pop(i)
+            if clock() >= deadline:
+                return None
+            sleep(poll_interval)