cluxion-agentplugin-preprocessing 0.3.12__tar.gz → 0.3.14__tar.gz

{cluxion_agentplugin_preprocessing-0.3.12 → cluxion_agentplugin_preprocessing-0.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cluxion-agentplugin-preprocessing
-Version: 0.3.12
+Version: 0.3.14
 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

{cluxion_agentplugin_preprocessing-0.3.12 → cluxion_agentplugin_preprocessing-0.3.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cluxion-agentplugin-preprocessing"
-version = "0.3.12"
+version = "0.3.14"
 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.12 → cluxion_agentplugin_preprocessing-0.3.14}/rust/cluxion_queue/src/guard.rs

@@ -19,9 +19,13 @@ const DEFAULT_CPU_SAMPLE_MS: u64 = 100;
 const MAX_REPORTED_PIDS: usize = 50;
 const DEFAULT_CPU_HOT_THRESHOLD: f64 = 50.0;
 const DEFAULT_RSS_HOT_THRESHOLD_MB: u64 = 1024;
-pub const DEFAULT_DAEMON_INTERVAL_MS: u64 = 200;
-pub const DEFAULT_DAEMON_WINDOW: usize = 25;
+pub const DEFAULT_DAEMON_INTERVAL_MS: u64 = 1000;
+pub const DEFAULT_DAEMON_WINDOW: usize = 10;
+pub const PROC_SCAN_EVERY_N_TICKS: u64 = 5;
 pub const STATE_FILE_NAME: &str = "guard_state.json";
+pub const HEARTBEAT_FILE_NAME: &str = "guard_heartbeat";
+pub const PID_FILE_NAME: &str = "guard_daemon.pid";
+pub const DEFAULT_IDLE_TTL_MS: u64 = 600_000;
 
 fn epoch_ms() -> u64 {
     SystemTime::now()
@@ -30,6 +34,26 @@ fn epoch_ms() -> u64 {
         .unwrap_or(0)
 }
 
+fn idle_ttl_ms() -> u64 {
+    std::env::var("CLUXION_GUARD_IDLE_TTL_MS")
+        .ok()
+        .and_then(|raw| raw.parse::<u64>().ok())
+        .unwrap_or(DEFAULT_IDLE_TTL_MS)
+}
+
+/// True when the heartbeat mtime is older than `ttl_ms` relative to `now_ms`.
+pub fn is_idle(heartbeat_mtime_ms: u64, now_ms: u64, ttl_ms: u64) -> bool {
+    now_ms.saturating_sub(heartbeat_mtime_ms) > ttl_ms
+}
+
+fn heartbeat_mtime_ms(path: &Path) -> Option<u64> {
+    let modified = std::fs::metadata(path).ok()?.modified().ok()?;
+    modified
+        .duration_since(UNIX_EPOCH)
+        .ok()
+        .map(|duration| duration.as_millis() as u64)
+}
+
 fn uint_field(payload: &Value, key: &str, default: u64) -> u64 {
     payload.get(key).and_then(Value::as_u64).unwrap_or(default)
 }
@@ -48,7 +72,14 @@ pub fn sample(payload: &Value) -> Result<Value, QueueError> {
     Ok(sample_from(&sys))
 }
 
-fn sample_from(sys: &System) -> Value {
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct ProcessScanCache {
+    process_count: usize,
+    zombie_count: usize,
+    zombie_pids: Vec<u64>,
+}
+
+fn scan_process_fields(sys: &System) -> ProcessScanCache {
     let mut zombie_pids: Vec<u64> = sys
         .processes()
         .iter()
@@ -58,19 +89,88 @@ fn sample_from(sys: &System) -> Value {
     zombie_pids.sort_unstable();
     let zombie_count = zombie_pids.len();
     zombie_pids.truncate(MAX_REPORTED_PIDS);
+    ProcessScanCache {
+        process_count: sys.processes().len(),
+        zombie_count,
+        zombie_pids,
+    }
+}
+
+fn build_current_snapshot(sys: &System, process_cache: &ProcessScanCache) -> Value {
     json!({
         "ok": true,
         "total_ram_mb": sys.total_memory() / 1_048_576,
         "available_ram_mb": sys.available_memory() / 1_048_576,
         "swap_used_mb": sys.used_swap() / 1_048_576,
         "cpu_percent": f64::from(sys.global_cpu_usage()),
-        "process_count": sys.processes().len(),
-        "zombie_count": zombie_count,
-        "zombie_pids": zombie_pids,
+        "process_count": process_cache.process_count,
+        "zombie_count": process_cache.zombie_count,
+        "zombie_pids": process_cache.zombie_pids.clone(),
         "sampled_at_ms": epoch_ms(),
     })
 }
 
+fn sample_from(sys: &System) -> Value {
+    build_current_snapshot(sys, &scan_process_fields(sys))
+}
+
+fn push_window_sample(
+    cpu_window: &mut Vec<f64>,
+    ram_window: &mut Vec<u64>,
+    window: usize,
+    cpu: f64,
+    ram: u64,
+) {
+    if cpu_window.len() == window {
+        cpu_window.remove(0);
+        ram_window.remove(0);
+    }
+    cpu_window.push(cpu);
+    ram_window.push(ram);
+}
+
+fn build_daemon_state(
+    current: &Value,
+    cpu_window: &[f64],
+    ram_window: &[u64],
+    interval_ms: u64,
+) -> Value {
+    json!({
+        "ok": true,
+        "current": current,
+        "window": {
+            "samples": cpu_window.len(),
+            "cpu_avg": cpu_window.iter().sum::<f64>() / cpu_window.len() as f64,
+            "cpu_peak": cpu_window.iter().cloned().fold(0.0, f64::max),
+            "min_available_ram_mb": ram_window.iter().min().copied().unwrap_or(0),
+        },
+        "interval_ms": interval_ms,
+        "updated_at_ms": epoch_ms(),
+    })
+}
+
+fn daemon_tick(
+    sys: &mut System,
+    process_cache: &mut ProcessScanCache,
+    cpu_window: &mut Vec<f64>,
+    ram_window: &mut Vec<u64>,
+    window: usize,
+    interval_ms: u64,
+    tick: u64,
+) -> Value {
+    if tick % PROC_SCAN_EVERY_N_TICKS == 0 {
+        sys.refresh_processes(ProcessesToUpdate::All, true);
+        *process_cache = scan_process_fields(sys);
+    }
+    sys.refresh_memory();
+    sys.refresh_cpu_usage();
+    let current = build_current_snapshot(sys, process_cache);
+    let cpu = current["cpu_percent"].as_f64().unwrap_or(0.0);
+    let ram = current["available_ram_mb"].as_u64().unwrap_or(0);
+    push_window_sample(cpu_window, ram_window, window, cpu, ram);
+    build_daemon_state(&current, cpu_window, ram_window, interval_ms)
+}
+
 /// Scan processes against registered owner roots. A process is `owned`
 /// only when its parent lineage reaches one of `owned_roots`; everything
 /// else — including processes whose lineage cannot be walked — is
@@ -157,50 +257,53 @@ fn is_owned(pid: u64, owned_roots: &[u64], parents: &HashMap<u64, u64>) -> bool
 }
 
 /// Polling daemon: refresh, fold into a rolling window, publish state
-/// atomically (write to a temp file, then rename). Runs until killed.
+/// atomically (write to a temp file, then rename). Self-exits when the
+/// heartbeat file is stale; otherwise runs until killed.
+///
+/// Cheap ticks refresh memory/CPU every `interval_ms`; full process scans run
+/// every [`PROC_SCAN_EVERY_N_TICKS`] ticks and their results are cached for
+/// intervening cheap ticks.
 pub fn run_daemon(store_dir: &Path, interval_ms: u64, window: usize) -> Result<(), QueueError> {
     std::fs::create_dir_all(store_dir)?;
     let state_path = store_dir.join(STATE_FILE_NAME);
     let tmp_path = store_dir.join(format!("{STATE_FILE_NAME}.tmp"));
+    let heartbeat_path = store_dir.join(HEARTBEAT_FILE_NAME);
+    let pid_path = store_dir.join(PID_FILE_NAME);
+    let idle_ttl = idle_ttl_ms();
     let interval = std::time::Duration::from_millis(interval_ms.max(100));
     let window = window.max(1);
+    let interval_ms = interval.as_millis() as u64;
 
     let mut sys = System::new();
-    sys.refresh_memory();
-    sys.refresh_cpu_usage();
+    let mut process_cache = ProcessScanCache {
+        process_count: 0,
+        zombie_count: 0,
+        zombie_pids: Vec::new(),
+    };
     let mut cpu_window: Vec<f64> = Vec::with_capacity(window);
     let mut ram_window: Vec<u64> = Vec::with_capacity(window);
+    let mut tick: u64 = 0;
 
     loop {
-        std::thread::sleep(interval);
-        sys.refresh_memory();
-        sys.refresh_cpu_usage();
-        sys.refresh_processes(ProcessesToUpdate::All, true);
-        let current = sample_from(&sys);
-
-        let cpu = current["cpu_percent"].as_f64().unwrap_or(0.0);
-        let ram = current["available_ram_mb"].as_u64().unwrap_or(0);
-        if cpu_window.len() == window {
-            cpu_window.remove(0);
-            ram_window.remove(0);
+        if let Some(mtime) = heartbeat_mtime_ms(&heartbeat_path) {
+            if is_idle(mtime, epoch_ms(), idle_ttl) {
+                let _ = std::fs::remove_file(&pid_path);
+                return Ok(());
+            }
         }
-        cpu_window.push(cpu);
-        ram_window.push(ram);
-
-        let state = json!({
-            "ok": true,
-            "current": current,
-            "window": {
-                "samples": cpu_window.len(),
-                "cpu_avg": cpu_window.iter().sum::<f64>() / cpu_window.len() as f64,
-                "cpu_peak": cpu_window.iter().cloned().fold(0.0, f64::max),
-                "min_available_ram_mb": ram_window.iter().min().copied().unwrap_or(0),
-            },
-            "interval_ms": interval.as_millis() as u64,
-            "updated_at_ms": epoch_ms(),
-        });
+        let state = daemon_tick(
+            &mut sys,
+            &mut process_cache,
+            &mut cpu_window,
+            &mut ram_window,
+            window,
+            interval_ms,
+            tick,
+        );
         std::fs::write(&tmp_path, serde_json::to_vec(&state)?)?;
         std::fs::rename(&tmp_path, &state_path)?;
+        tick += 1;
+        std::thread::sleep(interval);
     }
 }
 
@@ -262,4 +365,126 @@ mod tests {
         // No roots registered -> nothing is owned.
         assert!(!is_owned(10, &[], &parents));
     }
+
+    #[test]
+    fn daemon_tick_caches_process_fields_between_scans() {
+        let mut sys = System::new();
+        sys.refresh_processes(ProcessesToUpdate::All, true);
+        let mut process_cache = scan_process_fields(&sys);
+        let mut cpu_window: Vec<f64> = Vec::with_capacity(3);
+        let mut ram_window: Vec<u64> = Vec::with_capacity(3);
+
+        let scan_tick_state = daemon_tick(
+            &mut sys,
+            &mut process_cache,
+            &mut cpu_window,
+            &mut ram_window,
+            3,
+            1000,
+            0,
+        );
+        let scan_process_count = scan_tick_state["current"]["process_count"]
+            .as_u64()
+            .expect("process_count");
+        assert!(scan_process_count > 0);
+
+        let stale_cache = ProcessScanCache {
+            process_count: 1,
+            zombie_count: 2,
+            zombie_pids: vec![99, 100],
+        };
+        process_cache = stale_cache.clone();
+
+        let cheap_tick_state = daemon_tick(
+            &mut sys,
+            &mut process_cache,
+            &mut cpu_window,
+            &mut ram_window,
+            3,
+            1000,
+            1,
+        );
+        assert_eq!(
+            cheap_tick_state["current"]["process_count"].as_u64(),
+            Some(1)
+        );
+        assert_eq!(
+            cheap_tick_state["current"]["zombie_count"].as_u64(),
+            Some(2)
+        );
+        assert_eq!(
+            cheap_tick_state["current"]["zombie_pids"],
+            json!([99, 100])
+        );
+
+        let rescan_tick_state = daemon_tick(
+            &mut sys,
+            &mut process_cache,
+            &mut cpu_window,
+            &mut ram_window,
+            3,
+            1000,
+            PROC_SCAN_EVERY_N_TICKS,
+        );
+        assert_ne!(process_cache, stale_cache);
+        assert!(process_cache.process_count > 0);
+        assert_eq!(
+            rescan_tick_state["current"]["process_count"].as_u64(),
+            Some(process_cache.process_count as u64)
+        );
+    }
+
+    #[test]
+    fn is_idle_detects_stale_and_fresh_heartbeats() {
+        let ttl = 600_000;
+        let now = 1_700_000_000_000u64;
+        assert!(is_idle(now - ttl - 1, now, ttl));
+        assert!(!is_idle(now - ttl, now, ttl));
+        assert!(!is_idle(now - 1, now, ttl));
+    }
+
+    #[test]
+    fn daemon_state_json_has_required_keys() {
+        let mut sys = System::new();
+        sys.refresh_processes(ProcessesToUpdate::All, true);
+        let mut process_cache = scan_process_fields(&sys);
+        let mut cpu_window: Vec<f64> = Vec::with_capacity(2);
+        let mut ram_window: Vec<u64> = Vec::with_capacity(2);
+
+        let state = daemon_tick(
+            &mut sys,
+            &mut process_cache,
+            &mut cpu_window,
+            &mut ram_window,
+            2,
+            1000,
+            0,
+        );
+
+        for key in ["ok", "current", "window", "interval_ms", "updated_at_ms"] {
+            assert!(state.get(key).is_some(), "missing top-level key: {key}");
+        }
+        for key in [
+            "ok",
+            "total_ram_mb",
+            "available_ram_mb",
+            "swap_used_mb",
+            "cpu_percent",
+            "process_count",
+            "zombie_count",
+            "zombie_pids",
+            "sampled_at_ms",
+        ] {
+            assert!(
+                state["current"].get(key).is_some(),
+                "missing current key: {key}"
+            );
+        }
+        for key in ["samples", "cpu_avg", "cpu_peak", "min_available_ram_mb"] {
+            assert!(
+                state["window"].get(key).is_some(),
+                "missing window key: {key}"
+            );
+        }
+    }
 }

cluxion_agentplugin_preprocessing-0.3.14/src/cluxion_agentplugin_preprocessing/__init__.py

@@ -0,0 +1,12 @@
+"""Universal Cluxion preprocessing agent plugin."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cluxion-agentplugin-preprocessing")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.3.13"
+
+__all__ = ["__version__"]

{cluxion_agentplugin_preprocessing-0.3.12 → cluxion_agentplugin_preprocessing-0.3.14}/src/cluxion_agentplugin_preprocessing/guard_watch.py

@@ -6,6 +6,7 @@ stderr and never raised into the host agent.
 
 from __future__ import annotations
 
+import contextlib
 import os
 import sys
 import threading
@@ -35,6 +36,7 @@ def on_session_start(**_: Any) -> None:
         return
     try:
         result = guard_bridge.start_daemon()
+        guard_bridge.touch_heartbeat()
     except Exception as exc:
         _warn(f"cluxion guard autostart failed: {exc}")
         return
@@ -53,6 +55,9 @@ def post_tool_call(**_: Any) -> None:
     """
     global _last_warning_at, _last_watch_at
 
+    with contextlib.suppress(Exception):
+        guard_bridge.touch_heartbeat()
+
     now = time.monotonic()
     try:
         with _lock:

{cluxion_agentplugin_preprocessing-0.3.12 → cluxion_agentplugin_preprocessing-0.3.14}/src/cluxion_agentplugin_preprocessing/plugin.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import importlib.resources
 import json
+import os
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -26,6 +27,12 @@ from cluxion_agentplugin_preprocessing.schemas import (
     SERVE_LOCAL_SCHEMA,
     WEB_SEARCH_SCHEMA,
 )
+from cluxion_runtime.core.context_compress import (
+    DEFAULT_TRIGGER_RATIO,
+    _resolve_context_limit,
+    compress,
+)
+from cluxion_runtime.core.preprocess import estimate_tokens
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -38,6 +45,10 @@ def register(ctx: object) -> None:
         register_hook("on_session_start", guard_watch.on_session_start)
         register_hook("post_tool_call", guard_watch.post_tool_call)
 
+    register_mw = getattr(ctx, "register_middleware", None)
+    if callable(register_mw):
+        register_mw("llm_request", _auto_compress_middleware)
+
     ctx.register_tool(
         name="cluxion_plan",
         toolset="cluxion",
@@ -275,4 +286,57 @@ def _json_result(callback: Callable[[], str]) -> str:
         return json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False, sort_keys=True)
 
 
+def _autocompress_enabled() -> bool:
+    value = os.environ.get("CLUXION_PREPROCESS_AUTOCOMPRESS", "1").strip().lower()
+    return value not in ("0", "false", "no", "off")
+
+
+def _auto_compress_middleware(
+    request: dict[str, object],
+    original_request: object = None,
+    model: str | None = None,
+    **_: object,
+) -> dict[str, object] | None:
+    del original_request
+    if os.environ.get("CLUXION_PREPROCESS_IN_COMPRESS") == "1":
+        return None
+    if not _autocompress_enabled():
+        return None
+
+    messages_key = "messages"
+    raw_messages = request.get("messages")
+    if not isinstance(raw_messages, list):
+        raw_messages = request.get("input")
+        messages_key = "input"
+    if not isinstance(raw_messages, list):
+        return None
+
+    try:
+        total_tokens = 0
+        for raw in raw_messages:
+            if isinstance(raw, dict):
+                total_tokens += estimate_tokens(str(raw.get("content", "")))
+            else:
+                total_tokens += estimate_tokens(str(raw))
+
+        limit_payload: dict[str, object] = {}
+        if model:
+            limit_payload["model"] = model
+        ctx_limit = request.get("context_limit_tokens")
+        if isinstance(ctx_limit, int) and not isinstance(ctx_limit, bool) and ctx_limit > 0:
+            limit_payload["context_limit_tokens"] = ctx_limit
+        context_limit = _resolve_context_limit(limit_payload)
+        if total_tokens / context_limit < DEFAULT_TRIGGER_RATIO:
+            return None
+
+        payload: dict[str, object] = {"messages": raw_messages, **limit_payload}
+        result = compress(payload)
+        shrunk = result.get("messages")
+        if not isinstance(shrunk, list):
+            return None
+        return {"request": {**request, messages_key: shrunk}, "source": "preprocessing"}
+    except Exception:
+        return None
+
+
 __all__ = ["register"]

{cluxion_agentplugin_preprocessing-0.3.12 → cluxion_agentplugin_preprocessing-0.3.14}/src/cluxion_runtime/core/context_compress.py

@@ -1,17 +1,16 @@
-"""Deterministic context compression: stage 1 of the 70% -> 30% pipeline.
+"""Context compression: 70% trigger -> 30% target pipeline.
 
-Pure-Python mirror of ``rust/cluxion_queue/src/context.rs`` — every
+Stage 1 (deterministic) mirrors ``rust/cluxion_queue/src/context.rs`` — every
 constant, threshold, ordering rule, and the token estimator must stay in
-lockstep so the three backends produce identical output (parity-tested).
+lockstep so the three backends produce identical Stage-1 output (parity-tested).
+
+Stages 2 (LLM summarization via ``hermes -z``) and 3 (hybrid forgetting) are
+Python-only; the Rust mirror intentionally does not replicate LLM or forgetforge
+calls. Disable them with ``enable_llm_summary`` / ``enable_forget`` for Stage-1
+parity.
 
 What stays untouched: pinned messages (explicit ``pinned``, the first
 user message = task intent, the most recent ``keep_recent`` turns).
-Stages run oldest-first and stop as soon as usage reaches the target:
-  A. truncate long messages (head + tail excerpt)
-  B. drop exact duplicates (trimmed-content match)
-  C. fold remaining old turns into one-line digests
-If the target is still not met the result carries ``ai_summary_request``
-telling the host AI which messages to summarize and what to preserve.
 """
 
 from __future__ import annotations
@@ -19,6 +18,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from cluxion_runtime.core.hybrid_forget import apply_hybrid_forget
+from cluxion_runtime.core.llm_compress import hermes_available, summarize_messages
 from cluxion_runtime.core.preprocess import estimate_tokens
 
 if TYPE_CHECKING:
@@ -70,6 +71,12 @@ def compress(payload: Mapping[str, object]) -> dict[str, object]:
     trigger_ratio = _ratio(payload, "trigger_ratio", DEFAULT_TRIGGER_RATIO)
     target_ratio = _ratio(payload, "target_ratio", DEFAULT_TARGET_RATIO)
     keep_recent = _uint(payload, "keep_recent_turns", DEFAULT_KEEP_RECENT)
+    enable_llm = _bool_flag(payload, "enable_llm_summary", True)
+    enable_forget = _bool_flag(payload, "enable_forget", True)
+    model = payload.get("model") if isinstance(payload.get("model"), str) else None
+    session_id = payload.get("session_id") if isinstance(payload.get("session_id"), str) else None
+    timeout_raw = payload.get("llm_timeout_s")
+    timeout_s = float(timeout_raw) if isinstance(timeout_raw, (int, float)) and not isinstance(timeout_raw, bool) else 120.0
 
     tokens_before = sum(estimate_tokens(m.content) for m in messages)
     usage_before = tokens_before / context_limit
@@ -102,11 +109,69 @@ def compress(payload: Mapping[str, object]) -> dict[str, object]:
         if changed:
             stages.append("digest")
 
-    summary_request = None
-    if total > target_tokens:
+    summary_request: dict[str, object] | None = None
+    dropped_without_backup = False
+    over_target_pinned_only = False
+    forced_over_target = False
+
+    if total > target_tokens and enable_llm and hermes_available():
         summary_request = _build_summary_request(messages, pinned, total, target_tokens)
+        indices = summary_request["summarize_indices"]
+        if isinstance(indices, list) and indices:
+            summaries = summarize_messages(
+                messages,
+                indices,  # type: ignore[arg-type]
+                str(summary_request.get("instructions", "")),
+                model=model,
+                timeout_s=timeout_s,
+            )
+            if summaries is not None:
+                for idx, summary in summaries.items():
+                    if idx in pinned or idx < 0 or idx >= len(messages):
+                        continue
+                    old_tokens = estimate_tokens(messages[idx].content)
+                    messages[idx].content = summary
+                    total = total - old_tokens + estimate_tokens(summary)
+                stages.append("llm_summary")
+                summary_request = None
+        # fail-safe: keep Stage-1 output and ai_summary_request on LLM failure
+
+    if total > target_tokens and enable_forget:
+        forget_result = apply_hybrid_forget(
+            messages,
+            pinned,
+            total,
+            target_tokens,
+            session_id=session_id,
+        )
+        messages = forget_result.messages
+        total = forget_result.tokens_after
+        dropped_without_backup = forget_result.dropped_without_backup
+        over_target_pinned_only = forget_result.over_target_pinned_only
+        if forget_result.dropped_indices:
+            stages.append("forget")
+        pinned = _pinned_indices(messages, keep_recent)
 
-    return _result_payload(messages, tokens_before, total, context_limit, stages, summary_request, pinned)
+    if total > target_tokens:
+        if summary_request is None:
+            summary_request = _build_summary_request(messages, pinned, total, target_tokens)
+        if over_target_pinned_only or not any(idx not in pinned for idx in range(len(messages))):
+            over_target_pinned_only = True
+        if total / context_limit > trigger_ratio:
+            forced_over_target = True
+
+    return _result_payload(
+        messages,
+        tokens_before,
+        total,
+        context_limit,
+        stages,
+        summary_request,
+        pinned,
+        dropped_without_backup=dropped_without_backup,
+        over_target_pinned_only=over_target_pinned_only,
+        forced_over_target=forced_over_target,
+    )
 
 
 def _resolve_context_limit(payload: Mapping[str, object]) -> int:
@@ -136,6 +201,13 @@ def _uint(payload: Mapping[str, object], key: str, default: int) -> int:
     return default
 
 
+def _bool_flag(payload: Mapping[str, object], key: str, default: bool) -> bool:
+    value = payload.get(key)
+    if isinstance(value, bool):
+        return value
+    return default
+
+
 def _pinned_indices(messages: list[_Msg], keep_recent: int) -> list[int]:
     pinned = [idx for idx, msg in enumerate(messages) if msg.pinned]
     first_user = next((idx for idx, msg in enumerate(messages) if msg.role == "user"), None)
@@ -235,8 +307,12 @@ def _result_payload(
     stages: list[str],
     summary_request: dict[str, object] | None,
     pinned: list[int],
+    *,
+    dropped_without_backup: bool = False,
+    over_target_pinned_only: bool = False,
+    forced_over_target: bool = False,
 ) -> dict[str, object]:
-    return {
+    result: dict[str, object] = {
         "ok": True,
         "compressed": bool(stages),
         "tokens_before": tokens_before,
@@ -249,6 +325,13 @@ def _result_payload(
         "messages": [{"role": m.role, "content": m.content, "pinned": m.pinned} for m in messages],
         "ai_summary_request": summary_request,
     }
+    if dropped_without_backup:
+        result["dropped_without_backup"] = True
+    if over_target_pinned_only:
+        result["over_target_pinned_only"] = True
+    if forced_over_target:
+        result["forced_over_target"] = True
+    return result
 
 
-__all__ = ["compress", "estimate_tokens"]
+__all__ = ["compress", "estimate_tokens"]