claude-smart 0.2.48 → 0.2.50

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

@@ -8,8 +8,15 @@ wrapper over the ``record_usage_event`` hook (which only enqueues). No DB I/O.
 
 from __future__ import annotations
 
+import logging
+import uuid
+from collections.abc import Mapping
+from typing import Any
+
 from reflexio.server.usage_metrics import record_usage_event
 
+logger = logging.getLogger(__name__)
+
 _INTERNAL = (
     "internal"  # == BillingCallerType.INTERNAL.value (kept literal; OSS stays clean)
 )
@@ -29,7 +36,10 @@ def record_extraction_tokens(
 ) -> None:
     """Emit the Learning cost facet — call only when extraction fired.
 
-    No-op when ``billing_input_tokens <= 0``.
+    No-op when ``billing_input_tokens <= 0``. Each call mints a fresh
+    ``event_key=f"tok:{uuid4()}"`` so two token emits under the same
+    ``request_id`` (e.g. profile + playbook extraction in one request) never
+    collapse into one billed event downstream.
 
     Args:
         org_id: Organisation identifier.
@@ -51,6 +61,7 @@ def record_extraction_tokens(
         pipeline=pipeline,
         request_id=request_id,
         session_id=session_id,
+        event_key=f"tok:{uuid.uuid4()}",
         count_value=billing_input_tokens,
         prompt_tokens=prompt_tokens,
         completion_tokens=completion_tokens,
@@ -68,12 +79,26 @@ def record_learnings_generated(
     platform_llm: bool | None,
     platform_storage: bool | None,
     pipeline: str | None = None,
+    user_id: str | None = None,
     request_id: str | None = None,
     session_id: str | None = None,
+    source: str | None = None,
+    agent_version: str | None = None,
+    playbook_name: str | None = None,
+    entity_type: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
 ) -> None:
     """Emit the Learning value facet — number of profiles/playbooks generated.
 
-    No-op when ``count <= 0``.
+    Documented FALLBACK for callers that genuinely lack a per-record id list
+    (e.g. dedup/consolidation can reduce the persisted count below the raw
+    extracted count, so there is no safe 1:1 id per unit of ``count``). Prefer
+    :func:`record_learnings_generated_records` whenever the caller has the
+    durable learning ids in scope. No-op when ``count <= 0``.
+
+    Emits a single event carrying a synthesized ``event_key=f"learn-batch:{uuid4()}"``
+    (distinct per call) so this aggregate event still has a dedup key, even
+    though it is not entity-backed.
 
     Args:
         org_id: Organisation identifier.
@@ -81,8 +106,14 @@ def record_learnings_generated(
         platform_llm: True iff the platform supplies the LLM for this org.
         platform_storage: True iff the platform supplies storage; None defers to rollup.
         pipeline: Optional pipeline tag (e.g. ``"playbook"``).
+        user_id: Optional user ID tied to the generated learning.
         request_id: Optional request correlation ID.
         session_id: Optional session ID.
+        source: Optional metering source/path label.
+        agent_version: Optional agent version tied to the generated learning.
+        playbook_name: Optional playbook name for playbook learnings.
+        entity_type: Optional entity type (e.g. ``"profile"``).
+        metadata: Optional path-specific usage metadata.
     """
     if count <= 0:
         return
@@ -91,15 +122,237 @@ def record_learnings_generated(
         event_name="learnings_generated",
         event_category="learning",
         pipeline=pipeline,
+        user_id=user_id,
         request_id=request_id,
         session_id=session_id,
+        source=source,
+        agent_version=agent_version,
+        playbook_name=playbook_name,
+        entity_type=entity_type,
+        event_key=f"learn-batch:{uuid.uuid4()}",
         count_value=count,
         platform_llm=platform_llm,
         platform_storage=platform_storage,
         caller_type=_INTERNAL,
+        metadata=metadata,
     )
 
 
+def record_learnings_generated_records(
+    *,
+    org_id: str,
+    learning_ids: list[str],
+    platform_llm: bool | None,
+    platform_storage: bool | None,
+    pipeline: str | None = None,
+    user_id: str | None = None,
+    request_id: str | None = None,
+    session_id: str | None = None,
+    source: str | None = None,
+    agent_version: str | None = None,
+    playbook_name: str | None = None,
+    entity_type: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> None:
+    """Emit the Learning value facet — one event per generated learning record.
+
+    Entity-backed alternative to :func:`record_learnings_generated`: emits one
+    ``learnings_generated`` event per id in ``learning_ids`` (``count_value=1``,
+    ``event_key=f"learn:{entity_type}:{id}"``, ``entity_id=id``) instead of a
+    single aggregate event, so downstream dedup can key on the learning id.
+    The ``entity_type`` segment is required for collision-freedom: entity-backed
+    callers draw ids from separate autoincrement primary keys in separate
+    tables (e.g. ``user_playbook_id`` and ``agent_playbook_id`` both start at
+    1), so the same integer id can legitimately occur in two tables — without
+    the entity-type segment those would mint the same ``event_key`` and
+    collapse into one event downstream. When ``entity_type`` is falsy, a
+    stable ``"_"`` placeholder is used (``learn:_:{id}``) rather than emitting
+    ``entity_type=None`` literally into the key. The summed ``count_value``
+    across the emitted events equals ``len(learning_ids)`` — unchanged from
+    the total a caller would have passed as ``count`` to
+    :func:`record_learnings_generated`.
+
+    Callers must pass real, durable ids — never fabricate one to pad the
+    list. No-op when ``learning_ids`` is empty.
+
+    Args:
+        org_id: Organisation identifier.
+        learning_ids: Ids of the learnings durably generated in this run
+            (e.g. ``profile_id`` / ``user_playbook_id`` / ``agent_playbook_id``).
+        platform_llm: True iff the platform supplies the LLM for this org.
+        platform_storage: True iff the platform supplies storage; None defers to rollup.
+        pipeline: Optional pipeline tag (e.g. ``"playbook"``).
+        user_id: Optional user ID tied to the generated learning.
+        request_id: Optional request correlation ID.
+        session_id: Optional session ID.
+        source: Optional metering source/path label.
+        agent_version: Optional agent version tied to the generated learning.
+        playbook_name: Optional playbook name for playbook learnings.
+        entity_type: Optional entity type (e.g. ``"profile"``).
+        metadata: Optional path-specific usage metadata (shared across events).
+    """
+    key_entity_type = entity_type or "_"
+    for learning_id in learning_ids:
+        record_usage_event(
+            org_id=org_id,
+            event_name="learnings_generated",
+            event_category="learning",
+            pipeline=pipeline,
+            user_id=user_id,
+            request_id=request_id,
+            session_id=session_id,
+            source=source,
+            agent_version=agent_version,
+            playbook_name=playbook_name,
+            entity_type=entity_type,
+            entity_id=learning_id,
+            event_key=f"learn:{key_entity_type}:{learning_id}",
+            count_value=1,
+            platform_llm=platform_llm,
+            platform_storage=platform_storage,
+            caller_type=_INTERNAL,
+            metadata=metadata,
+        )
+
+
+def emit_learnings_generated(
+    *,
+    org_id: str,
+    configurator: Any,
+    count: int,
+    source: str,
+    pipeline: str | None = None,
+    user_id: str | None = None,
+    request_id: str | None = None,
+    agent_version: str | None = None,
+    playbook_name: str | None = None,
+    entity_type: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> None:
+    """Resolve ``platform_llm`` from config and emit the Learning value facet.
+
+    Convenience wrapper for the non-extraction learning-mutation paths (reflection,
+    resumable-extraction finalization, aggregation, offline-tuner auto-apply). It
+    owns the ``configurator.get_config()`` + ``platform_llm_from_config`` lookup so
+    each call site stays a thin one-liner, and — critically — is **guarded**: the
+    product path must never fail because metering failed, so config resolution and
+    emission are wrapped and any exception is logged and swallowed (mirroring the
+    extraction path's ``_record_billing_learning_events``). No-op when
+    ``count <= 0``.
+
+    Args:
+        org_id: Organisation identifier.
+        configurator: Object exposing ``get_config()`` for platform-LLM resolution.
+        count: Number of learnings durably produced by this path.
+        source: Metering source/path label (e.g. ``"reflection"``).
+        pipeline: Optional pipeline tag (e.g. ``"playbook"``).
+        user_id: Optional user ID tied to the generated learning.
+        request_id: Optional request correlation ID.
+        agent_version: Optional agent version tied to the generated learning.
+        playbook_name: Optional playbook name for playbook learnings.
+        entity_type: Optional entity type (e.g. ``"profile"``).
+        metadata: Optional path-specific usage metadata.
+    """
+    if count <= 0:
+        return
+    try:
+        from reflexio.server.billing_signals import platform_llm_from_config
+
+        config = configurator.get_config()
+        record_learnings_generated(
+            org_id=org_id,
+            count=count,
+            platform_llm=platform_llm_from_config(config),
+            platform_storage=None,
+            pipeline=pipeline,
+            user_id=user_id,
+            request_id=request_id,
+            source=source,
+            agent_version=agent_version,
+            playbook_name=playbook_name,
+            entity_type=entity_type,
+            metadata=metadata,
+        )
+    except Exception:
+        logger.warning(
+            "emit_learnings_generated failed for source=%s org=%s; "
+            "learnings_generated event not emitted",
+            source,
+            org_id,
+            exc_info=True,
+        )
+
+
+def emit_learnings_generated_records(
+    *,
+    org_id: str,
+    configurator: Any,
+    learning_ids: list[str],
+    source: str,
+    pipeline: str | None = None,
+    user_id: str | None = None,
+    request_id: str | None = None,
+    agent_version: str | None = None,
+    playbook_name: str | None = None,
+    entity_type: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> None:
+    """Resolve ``platform_llm`` from config and emit one event per learning id.
+
+    Entity-backed counterpart to :func:`emit_learnings_generated`, currently
+    adopted by two of the non-extraction learning-mutation paths —
+    resumable-extraction finalization and aggregation — the callers with
+    durable per-record ids in scope. Extraction, reflection, and offline-tuner
+    auto-apply do not have a safe 1:1 id per unit of count (see
+    :func:`record_learnings_generated_records`) and use the count-based
+    :func:`emit_learnings_generated` fallback instead. Same guard semantics:
+    config resolution and emission are wrapped and any exception is logged
+    and swallowed — the product path must never fail because metering
+    failed. No-op when ``learning_ids`` is empty.
+
+    Args:
+        org_id: Organisation identifier.
+        configurator: Object exposing ``get_config()`` for platform-LLM resolution.
+        learning_ids: Ids of the learnings durably produced by this path.
+        source: Metering source/path label (e.g. ``"reflection"``).
+        pipeline: Optional pipeline tag (e.g. ``"playbook"``).
+        user_id: Optional user ID tied to the generated learning.
+        request_id: Optional request correlation ID.
+        agent_version: Optional agent version tied to the generated learning.
+        playbook_name: Optional playbook name for playbook learnings.
+        entity_type: Optional entity type (e.g. ``"profile"``).
+        metadata: Optional path-specific usage metadata (shared across events).
+    """
+    if not learning_ids:
+        return
+    try:
+        from reflexio.server.billing_signals import platform_llm_from_config
+
+        config = configurator.get_config()
+        record_learnings_generated_records(
+            org_id=org_id,
+            learning_ids=learning_ids,
+            platform_llm=platform_llm_from_config(config),
+            platform_storage=None,
+            pipeline=pipeline,
+            user_id=user_id,
+            request_id=request_id,
+            source=source,
+            agent_version=agent_version,
+            playbook_name=playbook_name,
+            entity_type=entity_type,
+            metadata=metadata,
+        )
+    except Exception:
+        logger.warning(
+            "emit_learnings_generated_records failed for source=%s org=%s; "
+            "learnings_generated events not emitted",
+            source,
+            org_id,
+            exc_info=True,
+        )
+
+
 def record_applied_learnings(
     *,
     org_id: str,
@@ -114,6 +367,8 @@ def record_applied_learnings(
     """Emit the Application line — surfaced top-K learnings.
 
     No-op unless ``caller_type == "production_agent"`` AND ``surfaced_count > 0``.
+    Each call mints a fresh ``event_key=f"applied:{uuid4()}"`` — a distinct
+    key per search-response moment, never collapsed by ``request_id``.
 
     Args:
         org_id: Organisation identifier.
@@ -134,6 +389,7 @@ def record_applied_learnings(
         pipeline=pipeline,
         request_id=request_id,
         session_id=session_id,
+        event_key=f"applied:{uuid.uuid4()}",
         count_value=surfaced_count,
         platform_llm=platform_llm,
         platform_storage=platform_storage,
@@ -152,7 +408,10 @@ def record_search_request(
 
     No-op unless ``caller_type == "production_agent"``. Unlike
     :func:`record_applied_learnings`, empty search responses still count because
-    this measures requests made, not learnings surfaced.
+    this measures requests made, not learnings surfaced. Each call mints a
+    fresh ``event_key=f"search:{uuid4()}"`` — a distinct key per request, so
+    two searches under the same ``request_id`` are never collapsed into one
+    billed event downstream.
 
     Args:
         org_id: Organisation identifier.
@@ -168,6 +427,7 @@ def record_search_request(
         event_category="application",
         request_id=request_id,
         session_id=session_id,
+        event_key=f"search:{uuid.uuid4()}",
         count_value=1,
         caller_type=caller_type,
     )

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

@@ -0,0 +1,164 @@
+"""Process-wide bounded executor for deferred fire-and-forget callbacks.
+
+Replaces thread-per-fire in the debounce schedulers (tagging, group
+evaluation, playbook optimization) so thread count is O(1) instead of
+O(active keys) (spec section 6.2). Sizes are module constants, not env vars.
+
+Overflow policy: drop-oldest (a dropped fire is a stale debounced trigger —
+the next event for that key re-creates it) with one warning log per drop and
+a throttled anomaly when drops exceed ``_DROP_RATE_PER_MINUTE`` in a rolling
+minute (the "this is routine, resize it" signal).
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from typing import NamedTuple
+
+from reflexio.server.tracing import capture_anomaly
+
+logger = logging.getLogger(__name__)
+
+_WORKERS = 16
+_QUEUE_SIZE = 256
+_DROP_RATE_PER_MINUTE = 10
+_DROP_ANOMALY_THROTTLE_SECONDS = 3600.0
+
+
+class _DropFacts(NamedTuple):
+    """Facts about one drop, collected while ``_cond`` is held.
+
+    Carries everything :meth:`BoundedCallbackExecutor._emit_drop` needs to log
+    + escalate AFTER the lock is released, so the contended lock is never held
+    across a logging/anomaly call.
+    """
+
+    dropped_name: str
+    drops_last_minute: int
+    fire_anomaly: bool
+
+
+class BoundedCallbackExecutor:
+    """Fixed worker pool + bounded FIFO queue with drop-oldest overflow.
+
+    Args:
+        workers: Number of daemon worker threads.
+        queue_size: Max queued callbacks before drop-oldest applies.
+    """
+
+    def __init__(
+        self, *, workers: int = _WORKERS, queue_size: int = _QUEUE_SIZE
+    ) -> None:
+        self._queue: deque[tuple[str, Callable[[], None]]] = deque()
+        self._queue_size = queue_size
+        self._cond = threading.Condition()
+        self._drop_times: deque[float] = deque()
+        self._last_drop_anomaly = 0.0
+        for i in range(workers):
+            threading.Thread(
+                target=self._worker_loop,
+                daemon=True,
+                name=f"callback-exec-{i}",
+            ).start()
+
+    def submit(self, name: str, fn: Callable[[], None]) -> None:
+        """Enqueue a callback; on a full queue, evict the oldest queued fire.
+
+        Args:
+            name: Short label for logs (e.g. the scheduler key).
+            fn: Zero-arg callback to run on a worker.
+        """
+        drop_facts: _DropFacts | None = None
+        with self._cond:
+            if len(self._queue) >= self._queue_size:
+                dropped_name, _ = self._queue.popleft()
+                drop_facts = self._record_drop_locked(dropped_name)
+            self._queue.append((name, fn))
+            self._cond.notify()
+        if drop_facts is not None:
+            self._emit_drop(drop_facts)
+
+    def _record_drop_locked(self, dropped_name: str) -> _DropFacts:
+        """Collect the facts of one drop while ``self._cond`` is held.
+
+        Only bookkeeping happens under the lock (all 16 workers + all
+        producers contend on it): pruning the rolling drop-time window and
+        deciding — and, if firing, committing — the throttle state
+        (``_last_drop_anomaly``) so the decision stays race-free. Logging and
+        anomaly emission are the caller's job, done AFTER the lock is
+        released (see :meth:`_emit_drop`).
+        """
+        now = time.monotonic()
+        self._drop_times.append(now)
+        while self._drop_times and now - self._drop_times[0] > 60.0:
+            self._drop_times.popleft()
+        drops_last_minute = len(self._drop_times)
+        fire_anomaly = (
+            drops_last_minute > _DROP_RATE_PER_MINUTE
+            and now - self._last_drop_anomaly > _DROP_ANOMALY_THROTTLE_SECONDS
+        )
+        if fire_anomaly:
+            self._last_drop_anomaly = now
+        return _DropFacts(
+            dropped_name=dropped_name,
+            drops_last_minute=drops_last_minute,
+            fire_anomaly=fire_anomaly,
+        )
+
+    def _emit_drop(self, facts: _DropFacts) -> None:
+        """Log one drop and (if decided under the lock) escalate the anomaly.
+
+        Called with ``self._cond`` NOT held — logging and ``capture_anomaly``
+        never happen while the contended lock is owned. References the
+        module-level ``capture_anomaly`` name (not a bound attribute) so
+        tests that ``monkeypatch.setattr(module, "capture_anomaly", ...)``
+        still intercept the call.
+        """
+        logger.warning(
+            "event=callback_executor_drop_oldest dropped=%s", facts.dropped_name
+        )
+        if facts.fire_anomaly:
+            capture_anomaly(
+                "callback_executor.drop_rate_exceeded",
+                drops_last_minute=facts.drops_last_minute,
+            )
+
+    def _worker_loop(self) -> None:
+        while True:
+            with self._cond:
+                while not self._queue:
+                    self._cond.wait()
+                name, fn = self._queue.popleft()
+            try:
+                fn()
+            except BaseException:  # noqa: BLE001 — daemon worker threads must
+                # survive anything a callback raises (including a callback
+                # that itself raises SystemExit); KeyboardInterrupt is only
+                # ever delivered to the main thread, so swallowing it here is
+                # safe. The fixed 16-worker pool must never silently shrink.
+                logger.exception(
+                    "event=callback_executor_callback_failed name=%s", name
+                )
+
+
+_executor: BoundedCallbackExecutor | None = None
+_executor_lock = threading.Lock()
+
+
+def submit_callback(name: str, fn: Callable[[], None]) -> None:
+    """Submit to the lazily-created process-wide executor.
+
+    Args:
+        name: Short label for logs.
+        fn: Zero-arg callback.
+    """
+    global _executor  # noqa: PLW0603
+    if _executor is None:
+        with _executor_lock:
+            if _executor is None:
+                _executor = BoundedCallbackExecutor()
+    _executor.submit(name, fn)