claude-smart 0.2.42 → 0.2.44

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

@@ -0,0 +1,34 @@
+# server/api_endpoints
+Description: Bridge between FastAPI routes and business logic — builds `RequestContext`, validates requests, and delegates into `Reflexio`. Most endpoints are registered on the `core_router` in `../api.py`; the files here are the handlers/helpers it calls.
+
+> For the complete endpoint list (publish, retrieval, search, profile/playbook lifecycle, evaluation, Braintrust, operations), see the parent [server README](../README.md#api-endpoints).
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `request_context.py` | `RequestContext` — bundles `org_id`, `storage`, `configurator`, `prompt_manager`. Built per request via `get_request_context()` (FastAPI `Depends`). The one object every handler reads storage/config/prompts through. |
+| `publisher_api.py` | Publishing + direct CRUD helpers: `add_user_interaction/profile/playbook`, `update_*`, and the full family of single / by-ids / bulk delete helpers for interactions, profiles, playbooks, requests, and sessions; plus `run_playbook_aggregation()` and `clear_user_data()`. |
+| `account_api.py` | Identity/config helpers behind `/api/whoami`, `/api/my_config`. |
+| `health_api.py` | `GET /`, `/health`, `/healthz`, `/healthz/eval`; `install()` adds response-time + liveness tracking. |
+| `pending_tool_call_api.py` | Router for resumable-extraction human clarification: list/get, `resolve`, `answer`, `not_applicable`, `cancel`; HMAC signature verify + migration-retry helpers. |
+| `stall_state_api.py` | `GET /api/stall_state`, `POST /api/stall_state/notified` — extraction-agent waiting state. |
+| `precondition_checks.py` | `precondition_checks()` — shared request validation. |
+
+## Architecture Pattern
+
+```
+api.py (core_router + sub-routers)
+  -> Depends(get_request_context) -> RequestContext(org_id, storage, configurator, prompt_manager)
+    -> get_reflexio(org_id) -> Reflexio (reflexio_lib) -> services/
+```
+
+- **`RequestContext` is the context-passing contract** — handlers receive it via `Depends` and never reach for storage/config/prompts globally.
+- **Route handlers call `Reflexio` through `get_reflexio(org_id)`** — these helper files do **not** instantiate `Reflexio()` directly.
+- **Auth is injected, not implemented here** — the OS app uses `default_get_org_id` / `DEFAULT_ORG_ID`; the enterprise extension swaps in authenticated org resolution (see `reflexio_ext/server/api_endpoints/`).
+
+## Requirements / Problems to Avoid
+
+- **NEVER instantiate `Reflexio()` in a handler** — use `get_reflexio(org_id)` from `server/cache/`.
+- **Keep business logic in `services/`** — endpoints validate, build context, and delegate; they don't embed extraction/evaluation logic.
+- **Pending-tool-call writes can race** — use the migration-retry + HMAC-verify helpers already in `pending_tool_call_api.py` rather than writing raw.

package/plugin/vendor/reflexio/reflexio/server/api_endpoints/account_api.py

@@ -0,0 +1,143 @@
+"""Account/diagnostics endpoints.
+
+Exposes two read-only endpoints that power CLI observability:
+
+- ``whoami``: masked summary of the caller's resolved storage routing.
+  Safe to call without special permission — never returns raw secrets.
+- ``my_config``: raw storage credentials for the caller's org.
+  Token-gated and rendered by ``reflexio config storage`` so operators
+  can inspect (and with ``--reveal``, copy) their own config.
+
+Both call through the cached ``Reflexio`` instance so per-org config
+lookups honour the same configurator that data reads/writes use.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, cast
+
+from reflexio.lib._storage_labels import describe_storage
+from reflexio.models.api_schema.service_schemas import (
+    MyConfigResponse,
+    WhoamiResponse,
+)
+from reflexio.server.cache.reflexio_cache import get_reflexio
+
+logger = logging.getLogger(__name__)
+
+# Generic, user-facing message used whenever loading a caller's storage
+# configuration fails. Exact exception text (connection strings, file
+# paths, SQL errors) must never leak to the HTTP response body.
+_GENERIC_STORAGE_LOAD_FAILURE = "Failed to load storage configuration"
+
+
+def whoami(org_id: str) -> WhoamiResponse:
+    """Return the caller's masked storage routing summary.
+
+    Args:
+        org_id: Organization identifier, resolved by the FastAPI
+            auth dependency from the Bearer token (or ``DEFAULT_ORG_ID``
+            in self-host mode).
+
+    Returns:
+        WhoamiResponse: Always includes ``org_id``; storage fields are
+            ``None`` / ``storage_configured=False`` when the org has no
+            storage configured yet.
+    """
+    try:
+        reflexio = get_reflexio(org_id=org_id)
+    except Exception:
+        logger.exception("whoami: failed to load reflexio for %s", org_id)
+        return WhoamiResponse(
+            success=False,
+            org_id=org_id,
+            storage_configured=False,
+            message=_GENERIC_STORAGE_LOAD_FAILURE,
+        )
+
+    configurator = reflexio.request_context.configurator
+    storage_config = configurator.get_current_storage_configuration()
+    storage_type, storage_label = describe_storage(storage_config)
+    return WhoamiResponse(
+        success=True,
+        org_id=org_id,
+        storage_type=storage_type,
+        storage_label=storage_label,
+        storage_configured=storage_config is not None
+        and configurator.is_storage_configured(),
+    )
+
+
+# Guard the my_config endpoint on OS/self-host so it isn't exposed by
+# default on unauthenticated localhost deployments. The FastAPI layer
+# (``reflexio.server.api.create_app``) now owns the enterprise opt-in:
+# when a custom ``get_org_id`` is provided together with ``require_auth``,
+# it sets ``app.state.my_config_enabled = True``. This helper keeps the
+# OS-only ``REFLEXIO_ALLOW_MY_CONFIG`` env var as a fallback for self-hosts.
+_ALLOW_MY_CONFIG_ENV_VAR = "REFLEXIO_ALLOW_MY_CONFIG"
+
+
+def my_config_allowed() -> bool:
+    """Return whether ``GET /api/my_config`` is enabled via the env var.
+
+    Returns True when ``REFLEXIO_ALLOW_MY_CONFIG=true`` is set
+    (OS self-host opt-in). App-state driven enablement lives in the
+    FastAPI endpoint wrapper in ``reflexio.server.api`` and does not
+    flow through this helper.
+    """
+    return os.environ.get(_ALLOW_MY_CONFIG_ENV_VAR, "").lower() in {"1", "true", "yes"}
+
+
+def my_config(org_id: str) -> MyConfigResponse:
+    """Return the caller's raw storage configuration.
+
+    This is the "download my creds" endpoint. On OS/self-host it is
+    guarded by ``REFLEXIO_ALLOW_MY_CONFIG``; on enterprise the FastAPI
+    route wraps it in Bearer-token auth and sets ``app.state.my_config_enabled``.
+
+    Args:
+        org_id: Organization identifier.
+
+    Returns:
+        MyConfigResponse: Serialised ``StorageConfig`` as a dict, or an
+            empty response with ``success=False`` when nothing is
+            configured.
+    """
+    try:
+        reflexio = get_reflexio(org_id=org_id)
+    except Exception:
+        logger.exception("my_config: failed to load reflexio for %s", org_id)
+        return MyConfigResponse(
+            success=False,
+            message=_GENERIC_STORAGE_LOAD_FAILURE,
+        )
+
+    configurator = reflexio.request_context.configurator
+    storage_config = configurator.get_current_storage_configuration()
+    if storage_config is None:
+        return MyConfigResponse(
+            success=False,
+            storage_config=None,
+            message="No storage configured for this org",
+        )
+    storage_type, _ = describe_storage(storage_config)
+    # Credential-export requests are security-sensitive — log at warning
+    # so they survive production log-level filtering and show up in any
+    # audit review.
+    logger.warning(
+        "my_config credential export requested for org=%s type=%s",
+        org_id,
+        storage_type,
+    )
+    storage_config_payload: dict[str, Any] = storage_config.model_dump()
+    redact = getattr(configurator, "redact_storage_config_for_response", None)
+    if callable(redact):
+        storage_config_payload = cast(dict[str, Any], redact(storage_config))
+
+    return MyConfigResponse(
+        success=True,
+        storage_config=storage_config_payload,
+        storage_type=storage_type,
+    )

package/plugin/vendor/reflexio/reflexio/server/api_endpoints/health_api.py

@@ -0,0 +1,91 @@
+"""Health-check endpoint and per-process metrics.
+
+Exposes ``GET /healthz`` returning a small JSON payload useful for verifying
+worker recycling (each worker has its own PID + request count). The middleware
+that increments ``request_count`` is per-process — counts are NOT synchronized
+across workers, which is intentional: it lets operators see load distribution
+across the worker pool.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+from fastapi import FastAPI, Request, Response
+
+from reflexio.server.services.agent_success_evaluation import _eval_health
+
+_STARTED_AT = time.monotonic()
+_REQUEST_COUNT = 0
+
+
+def _read_rss_mb() -> float | None:
+    """Return the current process's resident set size in MiB, or None.
+
+    Returns:
+        float | None: RSS in MiB; None when psutil is unavailable.
+    """
+    try:
+        import psutil
+    except ImportError:
+        return None
+    return psutil.Process().memory_info().rss / 1024.0 / 1024.0
+
+
+_AMBER_SECONDS = 5 * 60
+_RED_SECONDS = 30 * 60
+
+
+def _liveness_from_tick(last_tick_monotonic: float | None) -> str:
+    """Map scheduler-tick age to a green/amber/red liveness color.
+
+    Args:
+        last_tick_monotonic (float | None): The last recorded scheduler tick,
+            from `time.monotonic()`; None if the scheduler has not yet ticked.
+
+    Returns:
+        str: One of "green", "amber", "red".
+    """
+    if last_tick_monotonic is None:
+        return "red"
+    age = time.monotonic() - last_tick_monotonic
+    if age > _RED_SECONDS:
+        return "red"
+    if age > _AMBER_SECONDS:
+        return "amber"
+    return "green"
+
+
+def install(app: FastAPI) -> None:
+    """Install the /healthz route and request-count middleware on ``app``.
+
+    Args:
+        app (FastAPI): The FastAPI application to attach to.
+    """
+
+    @app.middleware("http")
+    async def _count_requests(request: Request, call_next: Any) -> Response:
+        global _REQUEST_COUNT
+        _REQUEST_COUNT += 1
+        return await call_next(request)
+
+    @app.get("/healthz")
+    def healthz() -> dict[str, Any]:
+        """Return per-worker process metrics for liveness/observability."""
+        return {
+            "pid": os.getpid(),
+            "uptime_sec": time.monotonic() - _STARTED_AT,
+            "request_count": _REQUEST_COUNT,
+            "rss_mb": _read_rss_mb(),
+        }
+
+    @app.get("/healthz/eval")
+    def healthz_eval() -> dict[str, Any]:
+        """Return evaluation-pipeline health: skip counts, failure counts, liveness."""
+        status = _eval_health.get_status()
+        return {
+            **status,
+            "liveness": _liveness_from_tick(status["last_tick_monotonic"]),
+        }