cluxion-agentplugin-preprocessing 0.3.0__tar.gz → 0.3.1__tar.gz

{cluxion_agentplugin_preprocessing-0.3.0 → cluxion_agentplugin_preprocessing-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cluxion-agentplugin-preprocessing
-Version: 0.3.0
+Version: 0.3.1
 Summary: Universal agent plugin for Cluxion preprocessing, honesty contracts, clarification, Rust work queue, and resource-aware harness handoff.
 Project-URL: Homepage, https://github.com/cluxion/cluxion-Agentplugin-preprocessing
 Project-URL: Repository, https://github.com/cluxion/cluxion-Agentplugin-preprocessing
@@ -108,6 +108,8 @@ cluxion-runtime plan --surface hermes --prompt "작업 설명"
 | `cluxion_context_compress` | context 사용률 초과 시 결정론적 압축 (pinned/recent 보존) |
 | `cluxion_guard` | 실시간 리소스 guard (`status`/`start`/`stop`/`enforce`/`auto-enforce`) |
 
+Hermes에서는 `on_session_start` hook이 guard daemon을 자동 시작합니다. `CLUXION_GUARD_AUTOSTART=0` 또는 `false`로 끌 수 있고, `post_tool_call` hook은 기본 30초마다 report-only `auto_enforce(dry_run=True)`를 실행합니다. 실제 적용은 `CLUXION_GUARD_AUTO_APPLY=1` 또는 `true`일 때만 켜집니다.
+
 ## 문서
 
 - [Docs/README.md](Docs/README.md) — **처음 읽는 분** + 목차
@@ -120,4 +122,4 @@ cluxion-runtime plan --surface hermes --prompt "작업 설명"
 
 ## License
 
-Apache-2.0
+Apache-2.0

{cluxion_agentplugin_preprocessing-0.3.0 → cluxion_agentplugin_preprocessing-0.3.1}/README.md

@@ -76,6 +76,8 @@ cluxion-runtime plan --surface hermes --prompt "작업 설명"
 | `cluxion_context_compress` | context 사용률 초과 시 결정론적 압축 (pinned/recent 보존) |
 | `cluxion_guard` | 실시간 리소스 guard (`status`/`start`/`stop`/`enforce`/`auto-enforce`) |
 
+Hermes에서는 `on_session_start` hook이 guard daemon을 자동 시작합니다. `CLUXION_GUARD_AUTOSTART=0` 또는 `false`로 끌 수 있고, `post_tool_call` hook은 기본 30초마다 report-only `auto_enforce(dry_run=True)`를 실행합니다. 실제 적용은 `CLUXION_GUARD_AUTO_APPLY=1` 또는 `true`일 때만 켜집니다.
+
 ## 문서
 
 - [Docs/README.md](Docs/README.md) — **처음 읽는 분** + 목차
@@ -88,4 +90,4 @@ cluxion-runtime plan --surface hermes --prompt "작업 설명"
 
 ## License
 
-Apache-2.0
+Apache-2.0

{cluxion_agentplugin_preprocessing-0.3.0 → cluxion_agentplugin_preprocessing-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cluxion-agentplugin-preprocessing"
-version = "0.3.0"
+version = "0.3.1"
 description = "Universal agent plugin for Cluxion preprocessing, honesty contracts, clarification, Rust work queue, and resource-aware harness handoff."
 readme = "README.md"
 requires-python = ">=3.11"

{cluxion_agentplugin_preprocessing-0.3.0 → cluxion_agentplugin_preprocessing-0.3.1}/src/cluxion_agentplugin_preprocessing/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = ["__version__"]

cluxion_agentplugin_preprocessing-0.3.1/src/cluxion_agentplugin_preprocessing/guard_watch.py

@@ -0,0 +1,112 @@
+"""Hermes hook wiring for automatic guard daemon watch.
+
+The hook surface is intentionally best-effort: failures are reported once to
+stderr and never raised into the host agent.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from typing import Any
+
+from cluxion_runtime.resources import guard_bridge
+
+AUTOSTART_ENV = "CLUXION_GUARD_AUTOSTART"
+AUTO_APPLY_ENV = "CLUXION_GUARD_AUTO_APPLY"
+WATCH_INTERVAL_ENV = "CLUXION_GUARD_WATCH_INTERVAL"
+DEFAULT_WATCH_INTERVAL_SECONDS = 30.0
+WARNING_INTERVAL_SECONDS = 300.0
+
+_lock = threading.Lock()
+_last_watch_at: float | None = None
+_last_warning_at: float | None = None
+
+
+def on_session_start(**_: Any) -> None:
+    """Start the guard daemon unless ``CLUXION_GUARD_AUTOSTART=0`` or ``false``.
+
+    Startup is idempotent: an already-running daemon is success. Hook failures
+    are logged as one concise stderr warning and never propagated to the host.
+    """
+    if not _autostart_enabled():
+        return
+    try:
+        result = guard_bridge.start_daemon()
+    except Exception as exc:
+        _warn(f"cluxion guard autostart failed: {exc}")
+        return
+    if not result.get("ok", False):
+        reason = result.get("reason") or result.get("error") or "unknown"
+        _warn(f"cluxion guard autostart failed: {reason}")
+
+
+def post_tool_call(**_: Any) -> None:
+    """Run a throttled guard watch after tool calls.
+
+    By default this is report-only and calls ``auto_enforce(..., dry_run=True)``.
+    Set ``CLUXION_GUARD_AUTO_APPLY=1`` or ``true`` to pass ``dry_run=False`` and
+    let the existing owned-only fail-closed enforcement path terminate
+    candidates.
+    """
+    global _last_watch_at
+
+    now = time.monotonic()
+    with _lock:
+        if _last_watch_at is not None and now - _last_watch_at < _watch_interval_seconds():
+            return
+        _last_watch_at = now
+
+    try:
+        result = guard_bridge.auto_enforce([os.getpid()], dry_run=not _auto_apply_enabled())
+    except Exception as exc:
+        _warn(f"cluxion guard watch failed: {exc}")
+        return
+    if not result.get("triggered", False) or not result.get("dry_run", True):
+        return
+
+    _warn_triggered(result, now)
+
+
+def _autostart_enabled() -> bool:
+    return os.environ.get(AUTOSTART_ENV, "1").strip().lower() not in {"0", "false"}
+
+
+def _auto_apply_enabled() -> bool:
+    return os.environ.get(AUTO_APPLY_ENV, "").strip().lower() in {"1", "true"}
+
+
+def _watch_interval_seconds() -> float:
+    raw = os.environ.get(WATCH_INTERVAL_ENV)
+    if raw is None:
+        return DEFAULT_WATCH_INTERVAL_SECONDS
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return DEFAULT_WATCH_INTERVAL_SECONDS
+
+
+def _warn_triggered(result: dict[str, Any], now: float) -> None:
+    global _last_warning_at
+
+    with _lock:
+        if _last_warning_at is not None and now - _last_warning_at < WARNING_INTERVAL_SECONDS:
+            return
+        _last_warning_at = now
+
+    pids = [str(entry.get("pid")) for entry in result.get("candidates", []) if isinstance(entry, dict)]
+    reasons = [str(reason) for reason in result.get("trigger_reasons", [])]
+    _warn(
+        "cluxion guard triggered"
+        f" candidates={','.join(pids) if pids else 'none'}"
+        f" reasons={'; '.join(reasons) if reasons else 'unknown'}"
+    )
+
+
+def _warn(message: str) -> None:
+    print(message, file=sys.stderr)
+
+
+__all__ = ["on_session_start", "post_tool_call"]

{cluxion_agentplugin_preprocessing-0.3.0 → cluxion_agentplugin_preprocessing-0.3.1}/src/cluxion_agentplugin_preprocessing/plugin.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING
 
-from cluxion_agentplugin_preprocessing import runner
+from cluxion_agentplugin_preprocessing import guard_watch, runner
 from cluxion_agentplugin_preprocessing.schemas import (
     BOOTSTRAP_SCHEMA,
     BROWSER_CLICK_SCHEMA,
@@ -30,6 +30,11 @@ if TYPE_CHECKING:
 
 def register(ctx: object) -> None:
     """Register Cluxion preprocessing tools with the host agent."""
+    register_hook = getattr(ctx, "register_hook", None)
+    if callable(register_hook):
+        register_hook("on_session_start", guard_watch.on_session_start)
+        register_hook("post_tool_call", guard_watch.post_tool_call)
+
     ctx.register_tool(
         name="cluxion_plan",
         toolset="cluxion",

cluxion_agentplugin_preprocessing-0.3.1/tests/test_guard_watch.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from cluxion_agentplugin_preprocessing import guard_watch, plugin
+
+
+@pytest.fixture(autouse=True)
+def reset_guard_watch(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(guard_watch, "_last_watch_at", None)
+    monkeypatch.setattr(guard_watch, "_last_warning_at", None)
+    monkeypatch.delenv(guard_watch.AUTOSTART_ENV, raising=False)
+    monkeypatch.delenv(guard_watch.AUTO_APPLY_ENV, raising=False)
+    monkeypatch.delenv(guard_watch.WATCH_INTERVAL_ENV, raising=False)
+
+
+class HookContext:
+    def __init__(self) -> None:
+        self.hooks: dict[str, object] = {}
+        self.tools: dict[str, object] = {}
+
+    def register_hook(self, name: str, handler: object) -> None:
+        self.hooks[name] = handler
+
+    def register_tool(self, *, name: str, **kwargs: object) -> None:
+        self.tools[name] = kwargs
+
+
+class ToolOnlyContext:
+    def __init__(self) -> None:
+        self.tools: dict[str, object] = {}
+
+    def register_tool(self, *, name: str, **kwargs: object) -> None:
+        self.tools[name] = kwargs
+
+
+def test_register_adds_guard_hooks_when_supported() -> None:
+    ctx = HookContext()
+
+    plugin.register(ctx)
+
+    assert ctx.hooks == {
+        "on_session_start": guard_watch.on_session_start,
+        "post_tool_call": guard_watch.post_tool_call,
+    }
+    assert "cluxion_guard" in ctx.tools
+
+
+def test_register_tolerates_context_without_hooks() -> None:
+    ctx = ToolOnlyContext()
+
+    plugin.register(ctx)
+
+    assert "cluxion_guard" in ctx.tools
+
+
+def test_autostart_default_on(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = 0
+
+    def fake_start_daemon() -> dict[str, object]:
+        nonlocal calls
+        calls += 1
+        return {"ok": True, "started": False, "reason": "already_running"}
+
+    monkeypatch.setattr(guard_watch.guard_bridge, "start_daemon", fake_start_daemon)
+
+    guard_watch.on_session_start(session_id="s1", telemetry_schema_version=1)
+
+    assert calls == 1
+
+
+@pytest.mark.parametrize("value", ["0", "false", "False"])
+def test_autostart_env_gate_off(monkeypatch: pytest.MonkeyPatch, value: str) -> None:
+    calls = 0
+
+    def fake_start_daemon() -> dict[str, object]:
+        nonlocal calls
+        calls += 1
+        return {"ok": True}
+
+    monkeypatch.setenv(guard_watch.AUTOSTART_ENV, value)
+    monkeypatch.setattr(guard_watch.guard_bridge, "start_daemon", fake_start_daemon)
+
+    guard_watch.on_session_start(session_id="s1", telemetry_schema_version=1)
+
+    assert calls == 0
+
+
+def test_autostart_exception_is_swallowed_with_warning(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def fake_start_daemon() -> dict[str, object]:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(guard_watch.guard_bridge, "start_daemon", fake_start_daemon)
+
+    guard_watch.on_session_start(session_id="s1", telemetry_schema_version=1)
+
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert "cluxion guard autostart failed: boom" in captured.err
+
+
+def test_watch_throttle(monkeypatch: pytest.MonkeyPatch) -> None:
+    now = 100.0
+    calls: list[dict[str, Any]] = []
+
+    def fake_monotonic() -> float:
+        return now
+
+    def fake_auto_enforce(owned_roots: list[int], *, dry_run: bool) -> dict[str, object]:
+        calls.append({"owned_roots": owned_roots, "dry_run": dry_run})
+        return {"ok": True, "triggered": False, "dry_run": dry_run}
+
+    monkeypatch.setattr(guard_watch.time, "monotonic", fake_monotonic)
+    monkeypatch.setattr(guard_watch.guard_bridge, "auto_enforce", fake_auto_enforce)
+
+    guard_watch.post_tool_call(tool_name="terminal", telemetry_schema_version=1)
+    guard_watch.post_tool_call(tool_name="terminal", telemetry_schema_version=1)
+    now = 131.0
+    guard_watch.post_tool_call(tool_name="terminal", telemetry_schema_version=1)
+
+    assert len(calls) == 2
+    assert calls[0]["dry_run"] is True
+    assert calls[1]["dry_run"] is True
+
+
+def test_triggered_dry_run_warning_is_rate_limited(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    now = 100.0
+
+    def fake_monotonic() -> float:
+        return now
+
+    def fake_auto_enforce(owned_roots: list[int], *, dry_run: bool) -> dict[str, object]:
+        return {
+            "ok": True,
+            "triggered": True,
+            "dry_run": dry_run,
+            "candidates": [{"pid": 123}, {"pid": 456}],
+            "trigger_reasons": ["cpu_avg 99.0 >= sustained_cpu 85.0"],
+        }
+
+    monkeypatch.setenv(guard_watch.WATCH_INTERVAL_ENV, "0")
+    monkeypatch.setattr(guard_watch.time, "monotonic", fake_monotonic)
+    monkeypatch.setattr(guard_watch.guard_bridge, "auto_enforce", fake_auto_enforce)
+
+    guard_watch.post_tool_call(tool_name="terminal", telemetry_schema_version=1)
+    guard_watch.post_tool_call(tool_name="terminal", telemetry_schema_version=1)
+
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert captured.err.count("cluxion guard triggered") == 1
+    assert "candidates=123,456" in captured.err
+    assert "cpu_avg 99.0 >= sustained_cpu 85.0" in captured.err
+
+
+def test_auto_apply_passes_dry_run_false(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls: list[dict[str, Any]] = []
+
+    def fake_auto_enforce(owned_roots: list[int], *, dry_run: bool) -> dict[str, object]:
+        calls.append({"owned_roots": owned_roots, "dry_run": dry_run})
+        return {"ok": True, "triggered": False, "dry_run": dry_run}
+
+    monkeypatch.setenv(guard_watch.AUTO_APPLY_ENV, "true")
+    monkeypatch.setattr(guard_watch.guard_bridge, "auto_enforce", fake_auto_enforce)
+
+    guard_watch.post_tool_call(session_id="s1", telemetry_schema_version=1)
+
+    assert calls == [{"owned_roots": [guard_watch.os.getpid()], "dry_run": False}]