claude-smart 0.2.48 → 0.2.50

package/plugin/vendor/reflexio/reflexio/server/scheduling.py

@@ -19,6 +19,9 @@ set of hooks so no observable behaviour changes:
   ``start`` is a logged no-op when a feature gate is off).
 - :meth:`_on_started` / :meth:`_on_stopped` emit each scheduler's own start/stop
   log line (through its own module logger, so output is byte-identical).
+- ``leader_gate`` (optional): a fleet-coordination gate consulted before each
+  tick; ``None`` (the default and the OSS-local case) preserves today's
+  always-tick behavior byte-for-byte.
 
 A scheduler whose loop is materially different (e.g. a bounded-attempt retrier
 that waits *before* each attempt and exits on first success) may override
@@ -31,7 +34,31 @@ nothing from ``reflexio_ext``.
 
 from __future__ import annotations
 
+import logging
 import threading
+from typing import Protocol
+
+logger = logging.getLogger(__name__)
+
+# How long a non-leader waits before re-checking the gate. Fixed (no interval
+# memoization): a follower that becomes leader starts ticking within <=60s.
+_FOLLOWER_POLL_SECONDS: float = 60.0
+
+
+class LeaderGate(Protocol):
+    """Fleet-coordination gate consulted before each tick.
+
+    Implementations must NEVER raise from ``should_run`` — error handling
+    (including fail-open) lives inside the implementation (spec §4.1). The
+    scheduler base nonetheless defends against a contract violation: if
+    ``should_run`` raises anyway, the base logs the error and fails open
+    (runs the tick) rather than trusting the contract blindly and letting the
+    daemon thread die silently.
+    """
+
+    def should_run(self) -> bool:
+        """Return whether this instance should run the next tick."""
+        ...
 
 
 class ThreadedScheduler:
@@ -44,12 +71,17 @@ class ThreadedScheduler:
 
     Args:
         thread_name (str): OS thread name for the daemon (aids debugging / logs).
+        leader_gate (LeaderGate | None): Optional fleet-coordination gate
+            consulted before each tick. Defaults to None (always tick).
     """
 
-    def __init__(self, *, thread_name: str) -> None:
+    def __init__(
+        self, *, thread_name: str, leader_gate: LeaderGate | None = None
+    ) -> None:
         self._thread_name = thread_name
         self._stop_event = threading.Event()
         self._thread: threading.Thread | None = None
+        self._leader_gate = leader_gate
 
     def start(self) -> None:
         """Start the daemon thread, unless it is gated off or already running.
@@ -125,8 +157,37 @@ class ThreadedScheduler:
         """
         raise NotImplementedError
 
+    def _elected_interval(self) -> float:
+        """Run one gated iteration; return the seconds to wait before the next.
+
+        ``None`` gate -> tick (today's behavior). Gate ``True`` -> tick.
+        Gate ``False`` -> skip and wait the fixed follower poll.
+
+        The gate contract says ``should_run`` never raises (see
+        :class:`LeaderGate`), but this has zero defense of its own: an escaped
+        exception here would kill the daemon thread permanently and silently.
+        A raise is therefore caught defensively and treated as fail-open (tick
+        runs; duplicate work is safe, silence is not) rather than propagated.
+
+        Returns:
+            float: Seconds to wait before the next loop iteration.
+        """
+        if self._leader_gate is None:
+            return self._run_once()
+        try:
+            should_run = self._leader_gate.should_run()
+        except Exception:
+            logger.exception(
+                "event=%s_leader_gate_error — failing open", self._thread_name
+            )
+            return self._run_once()
+        if should_run:
+            return self._run_once()
+        logger.debug("event=%s_skip_not_leader", self._thread_name)
+        return _FOLLOWER_POLL_SECONDS
+
     def _run_loop(self) -> None:
-        """Drive :meth:`_run_once` until stopped, waiting its returned interval."""
+        """Drive gated iterations until stopped, waiting each returned interval."""
         while not self._stop_event.is_set():
-            interval = self._run_once()
+            interval = self._elected_interval()
             self._stop_event.wait(interval)

package/plugin/vendor/reflexio/reflexio/server/services/README.md

@@ -22,7 +22,7 @@ strings before deleting old import paths in the same PR.
 
 | File | Purpose |
 |------|---------|
-| `generation_service.py` | `GenerationService` — saves interactions, runs profile + playbook generation in parallel (ThreadPoolExecutor), schedules deferred evaluation when `session_id` is present. |
+| `generation_service.py` | `GenerationService` — saves interactions, runs/defer-runs profile + playbook generation, schedules deferred evaluation when `session_id` is present, exposes `run_deferred_learning()` for the non-durable publish worker, and the durable `compute_deferred_learning()` → `persist_deferred_learning()` → `emit_deferred_learning_side_effects()` split (compute outside any scope; only persist + fence inside `commit_scope()`). |
 | `publish_learning_worker.py` | Deferred post-persist publish learning worker — queues async publish learning after durable interaction writes and requeues under publish limiter pressure. |
 | `base_generation_service.py` + `base_generation/` | `BaseGenerationService` stable import surface plus mixins for batch progress, config filtering, extraction lifecycle, should-run prechecks, status transitions, and usage billing. Per-extractor timeout `EXTRACTOR_TIMEOUT_SECONDS = 300`. |
 | `operation_state_utils.py` | `OperationStateManager` — all `_operation_state` access (progress, concurrency locks, extractor/aggregator bookmarks, cluster fingerprints, cancellation). |
@@ -38,10 +38,11 @@ strings before deleting old import paths in the same PR.
 | `agent_success_evaluation/` | `AgentSuccessEvaluationService` | `service.py` (session-level service), `runner.py` (`run_group_evaluation`), `scheduler.py` (`GroupEvaluationScheduler`, 10-min defer), `regen_jobs.py`, `components/evaluator.py` |
 | `reflection/` | `ReflectionService` | `service.py`, `components/extractor.py` — post-horizon reflection; runs **before** extraction so extractors read post-reflection state |
 
-## Async Extraction
+## Durable and Async Extraction
 
 | Directory | Purpose |
 |-----------|---------|
+| `durable_learning/` | Durable `learning_jobs` scheduler + worker. Gated by `REFLEXIO_DURABLE_LEARNING_QUEUE`; discovers orgs with pending work, claims jobs with leases, then per job runs `compute_deferred_learning()` **outside** any writer transaction, applies `persist_deferred_learning()` + fenced `complete_learning_job()` inside a short `storage.commit_scope()`, and fires `emit_deferred_learning_side_effects()` post-commit — fenced completion guarantees exactly-once side effects. |
 | `extraction/` | Shared async extraction runtime: `resumable_agent.py`, `resume_scheduler.py`, `resume_worker.py`, `pending_tool_call_dispatch.py` (`ask_human`), `prior_answer_search.py`, `agent_run_records.py`, and `outcome.py`. Long-horizon / tool-mediated extraction continues outside the request path. See [README](extraction/README.md). |
 
 ## Evaluation, Search & Integrations
@@ -57,13 +58,13 @@ strings before deleting old import paths in the same PR.
 | `pre_retrieval/` | `QueryReformulator` (`_query_reformulator.py`) + `DocumentExpander` (`_document_expander.py`) - query rewrite and doc expansion for recall. Compact by design; see [README](pre_retrieval/README.md). |
 | `tagging/` | `TaggingService` (`service.py`) + deferred `tagging_scheduler.py` - post-generation profile/playbook tagging. Compact by design; see [README](tagging/README.md). |
 | `unified_search_service.py` | `run_unified_search()` — two-phase parallel search across profiles / agent playbooks / user playbooks. |
-| `retrieval/` | `relevance_floor.py` — result relevance thresholding. |
+| `retrieval/` | `relevance_floor.py` — result relevance thresholding. `temporal.py` — temporal post-processing driven by reformulation signals: query time windows → per-arm SQL filters, near-duplicate freshness collapse for current-value questions, timestamp ordering for latest-value questions. (Superseded/expired rows are already excluded by storage search SQL.) |
 
 ## Persistence & Config
 
 | Path | Purpose |
 |------|---------|
-| `storage/` | `storage_base/` and `sqlite_storage/` keep legacy domain facades while focused subpackages own `profiles/`, `playbook/`, `agent_run/`, `governance/`, and SQLite `base/` helpers; plus `governance_validation.py` and `retention*.py`. Access via `request_context.storage` only. |
+| `storage/` | `storage_base/` and `sqlite_storage/` keep legacy domain facades while focused subpackages own `profiles/`, `playbook/`, `agent_run/`, `governance/`, durable `learning_jobs`, and SQLite `base/` helpers; plus `governance_validation.py` and `retention*.py`. Access via `request_context.storage` only. |
 | `configurator/` | `DefaultConfigurator` — loads YAML config and creates the storage backend. |
 
 ## Key Rules
@@ -72,5 +73,6 @@ strings before deleting old import paths in the same PR.
 - **NEVER import storage implementations directly** — use `request_context.storage` (`BaseStorage`).
 - **ALWAYS use `LiteLLMClient`** for completions/embeddings and `request_context.prompt_manager.render_prompt(...)` for prompts — no hardcoded prompts, no direct OpenAI/Claude clients.
 - **All `_operation_state` writes go through `OperationStateManager`** — don't touch the table directly (it backs locks, bookmarks, progress, and cancellation).
+- **All durable queue claims go through `LearningJobStoreABC`** — do not update `learning_jobs` directly; completion is fenced by `claim_token` and must roll back the surrounding `commit_scope` when superseded.
 - **`tool_can_use` lives at root `Config`** — shared by playbook extraction and success evaluation, not per-service.
 - **Preserve governance subject refs/barriers** — route validation through `services/governance/` and `storage/governance_validation.py`; do not bypass retention or subject-write checks in storage implementations.

package/plugin/vendor/reflexio/reflexio/server/services/agent_success_evaluation/README.md

@@ -5,9 +5,10 @@ Session-level agent success evaluation module.
 ## Module Shape
 
 - `service.py`: `AgentSuccessEvaluationService`, the request-path service that runs configured evaluators and saves result rows.
-- `runner.py`: `run_group_evaluation(...)`, the background/manual workflow entry point that loads a session, runs the service, dispatches shadow comparison, and marks operation state.
+- `runner.py`: `run_group_evaluation(...)`, the background/manual workflow entry point that loads a session, runs the service, and marks operation state. After agent-success work it also runs the retrieved-learning evaluation (independent completion; generation + session-fingerprint fenced) and returns a `GroupEvaluationOutcome` carrying both statuses.
 - `scheduler.py`: `GroupEvaluationScheduler`, the deferred inactivity scheduler.
 - `components/evaluator.py`: `AgentSuccessEvaluator`, the LLM evaluator component.
+- `components/retrieved_learning_evaluator.py`: `RetrievedLearningEvaluator`, per-learning relevance/impact judges over `Interaction.retrieved_learnings`; results go to the `retrieved_learning_evaluation` table.
 - `regen_jobs.py`: regeneration job planning and execution; remains root-level because API/admin regenerate flows import it directly.
 - `_eval_health.py`: producer/scheduler health counters.
 - `agent_success_evaluation_constants.py`: prompt/model output constants.
@@ -15,7 +16,7 @@ Session-level agent success evaluation module.
 
 ## Prompt IDs
 
-- Owns `agent_success_evaluation`.
+- Owns `agent_success_evaluation`, `retrieved_learning_relevance`, and `retrieved_learning_impact`.
 - Keeps historical/configured prompt ID `agent_success_evaluation_with_comparison` stable where prompt mapping tests require it.
 
 Do not reintroduce the deleted service/evaluator/runner/scheduler legacy

package/plugin/vendor/reflexio/reflexio/server/services/agent_success_evaluation/_eval_health.py

@@ -51,6 +51,34 @@ class EvalHealth:
         self._skip_counts: Counter[SkipReason] = Counter()
         self._failures: deque[float] = deque()
         self._last_tick_monotonic: float | None = None
+        self._retrieved_outcome_counts: Counter[str] = Counter()
+        self._retrieved_invalid_ref_count = 0
+        self._retrieved_failed_relevance_chunks = 0
+        self._retrieved_failed_impact_chunks = 0
+
+    def record_retrieved_outcome(
+        self, status: str, *, diagnostics: dict[str, Any] | None = None
+    ) -> None:
+        """Record one retrieved-learning evaluation outcome.
+
+        Args:
+            status (str): Final invocation status (complete/degraded/failed/
+                not_applicable/...).
+            diagnostics (dict, optional): Evaluator diagnostics; the
+                invalid-ref and failed-chunk counters are accumulated from it.
+        """
+        with self._lock:
+            self._retrieved_outcome_counts[status] += 1
+            if diagnostics:
+                self._retrieved_invalid_ref_count += int(
+                    diagnostics.get("invalid_ref_count") or 0
+                )
+                self._retrieved_failed_relevance_chunks += int(
+                    diagnostics.get("failed_relevance_chunks") or 0
+                )
+                self._retrieved_failed_impact_chunks += int(
+                    diagnostics.get("failed_impact_chunks") or 0
+                )
 
     def record_skip(self, reason: SkipReason) -> None:
         """Bump the counter for `reason` by one.
@@ -99,6 +127,12 @@ class EvalHealth:
                 "skip_counts": {r.value: self._skip_counts[r] for r in SkipReason},
                 "producer_failures_24h": len(self._failures),
                 "last_tick_monotonic": self._last_tick_monotonic,
+                "retrieved_learning": {
+                    "outcome_counts": dict(self._retrieved_outcome_counts),
+                    "invalid_ref_count": self._retrieved_invalid_ref_count,
+                    "failed_relevance_chunks": self._retrieved_failed_relevance_chunks,
+                    "failed_impact_chunks": self._retrieved_failed_impact_chunks,
+                },
             }
 
     def _trim_locked(self, now_ts: float) -> None:
@@ -116,6 +150,13 @@ def record_skip(reason: SkipReason) -> None:
     _HEALTH.record_skip(reason)
 
 
+def record_retrieved_outcome(
+    status: str, *, diagnostics: dict[str, Any] | None = None
+) -> None:
+    """Module-level proxy to the singleton."""
+    _HEALTH.record_retrieved_outcome(status, diagnostics=diagnostics)
+
+
 def record_producer_failure(at_ts: float | None = None) -> None:
     """Module-level proxy to the singleton."""
     _HEALTH.record_producer_failure(at_ts=at_ts)