openhands-agent-server 1.36.0__tar.gz → 1.37.0__tar.gz

{openhands_agent_server-1.36.0 → openhands_agent_server-1.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-agent-server
-Version: 1.36.0
+Version: 1.37.0
 Summary: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk
@@ -18,3 +18,5 @@ Requires-Dist: sqlalchemy>=2
 Requires-Dist: uvicorn>=0.31.1
 Requires-Dist: websockets>=12
 Requires-Dist: wsproto>=1.2.0
+Provides-Extra: posthog
+Requires-Dist: posthog<7,>=6; extra == "posthog"

{openhands_agent_server-1.36.0 → openhands_agent_server-1.37.0}/openhands/agent_server/api.py

@@ -28,6 +28,9 @@ from openhands.agent_server.conversation_router import conversation_router
 from openhands.agent_server.conversation_service import (
     get_default_conversation_service,
 )
+from openhands.agent_server.credential_binding import (
+    router as credential_binding_router,
+)
 from openhands.agent_server.dependencies import (
     check_session_api_key,
     check_workspace_session,
@@ -61,6 +64,23 @@ from openhands.agent_server.settings_router import settings_router
 from openhands.agent_server.skills_router import skills_router
 from openhands.agent_server.sockets import sockets_router
 from openhands.agent_server.sub_agents_router import sub_agents_router
+from openhands.agent_server.telemetry import (
+    build_telemetry_sink,
+    emit_server_started,
+    emit_server_stopped,
+    get_event_factory,
+    get_telemetry_sink,
+    shutdown_telemetry_sink,
+)
+from openhands.agent_server.telemetry.factory import (
+    DISTINCT_ID_HEADER,
+    distinct_id_from_header,
+)
+from openhands.agent_server.telemetry.models import (
+    EventName,
+    RequestFailedProperties,
+)
+from openhands.agent_server.telemetry.sanitizer import normalize_exception
 from openhands.agent_server.tool_preload_service import get_tool_preload_service
 from openhands.agent_server.tool_router import tool_router
 from openhands.agent_server.vscode_router import vscode_router
@@ -133,6 +153,13 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
 
         config: Config = api.state.config
         deferred = config.deferred_init
+
+        # Deferred pods boot with telemetry disabled and are rebuilt by
+        # InitService, so they emit `server_started` there instead.
+        api.state.telemetry_sink = await build_telemetry_sink(config)
+        if not deferred:
+            emit_server_started()
+
         vscode_service = get_vscode_service()
         desktop_service = get_desktop_service()
         tool_preload_service = get_tool_preload_service()
@@ -265,12 +292,67 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
 
                 await stop_stateless_services()
     finally:
+        # Outer finally so a startup failure cannot leak the drain task, and
+        # after `async with service` so terminal events are still accepted.
+        emit_server_stopped()
+        await shutdown_telemetry_sink()
+
         if tmux_tmpdir_was_defaulted and os.environ.get("TMUX_TMPDIR") == str(
             tmux_tmpdir
         ):
             os.environ.pop("TMUX_TMPDIR", None)
 
 
+def _emit_request_failed(request: Request, exc: Exception, error_id: str) -> None:
+    """Report an unhandled 5xx as a sanitized diagnostic event.
+
+    Sends the *route template* (``/api/conversations/{conversation_id}``)
+    rather than ``request.url.path``, which embeds real identifiers. Fully
+    defensive: an error in the telemetry path must not replace the 500 the
+    caller is already getting with a different failure.
+    """
+    try:
+        sink = get_telemetry_sink()
+        if not sink.enabled:
+            return
+
+        factory = get_event_factory()
+        if factory is None:
+            return
+
+        route = request.scope.get("route")
+        route_template = getattr(route, "path", None)
+        if not isinstance(route_template, str) or not route_template:
+            # Unmatched route: reporting the raw path could leak identifiers.
+            route_template = "/unmatched"
+
+        method = request.method.upper()
+        if method not in ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"):
+            return
+
+        fingerprint = normalize_exception(exc)
+        # Attribute to the frontend's analytics identity when it supplied one;
+        # request-scoped activity has no conversation user_id otherwise.
+        distinct_id = distinct_id_from_header(request.headers.get(DISTINCT_ID_HEADER))
+        sink.emit(
+            factory.build(
+                EventName.REQUEST_FAILED,
+                RequestFailedProperties(
+                    route_template=route_template,
+                    method=method,  # type: ignore[arg-type]
+                    status_code=500,
+                    error_class=fingerprint.error_class,
+                    error_category=fingerprint.error_category,
+                    error_fingerprint=fingerprint.error_fingerprint,
+                    error_id=error_id,
+                ),
+                user_id=distinct_id,
+            )
+        )
+    except Exception:
+        logger.debug("Could not emit request_failed telemetry", exc_info=True)
+
+
 def _get_root_path(config: Config) -> str:
     root_path = ""
     if config.web_url:
@@ -343,6 +425,7 @@ def _add_api_routes(app: FastAPI) -> None:
     api_router = APIRouter(prefix="/api", dependencies=dependencies)
     api_router.include_router(event_router)
     api_router.include_router(conversation_router)
+    api_router.include_router(credential_binding_router)
     api_router.include_router(tool_router)
     api_router.include_router(bash_router)
     api_router.include_router(git_router)
@@ -517,6 +600,7 @@ def _add_exception_handlers(api: FastAPI) -> None:
                 error_id,
                 exc_info=(type(exc), exc, exc.__traceback__),
             )
+            _emit_request_failed(request, exc, error_id)
             return JSONResponse(status_code=500, content=content)
 
         # Logs full stack trace for any unhandled error that FastAPI would
@@ -528,6 +612,7 @@ def _add_exception_handlers(api: FastAPI) -> None:
             error_id,
             exc_info=(type(exc), exc, exc.__traceback__),
         )
+        _emit_request_failed(request, exc, error_id)
         return JSONResponse(status_code=500, content=content)
 
     @api.exception_handler(HTTPException)

{openhands_agent_server-1.36.0 → openhands_agent_server-1.37.0}/openhands/agent_server/config.py

@@ -2,7 +2,7 @@ import json
 import logging
 import os
 from pathlib import Path
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
@@ -111,6 +111,85 @@ class WebhookSpec(BaseModel):
     )
 
 
+TelemetryExporterKind = Literal["none", "posthog", "http"]
+"""Which exporter ships diagnostic events, if any."""
+
+
+class TelemetrySpec(BaseModel):
+    """Deployment-supplied product-analytics transport settings.
+
+    This carries *transport* only. Whether telemetry may be delivered is
+    resolved from consent (``misc_settings.telemetry.consent``, optionally
+    seeded or overridden by ``OH_TELEMETRY_CONSENT``) — there is no deployment
+    "mode" here, and nothing in the agent-server special-cases a hosted
+    deployment.
+    """
+
+    exporter: TelemetryExporterKind = Field(
+        default="none",
+        description=(
+            "Exporter to use. 'none' (the default) never delivers, and is what "
+            "library and headless consumers get. 'posthog' requires the "
+            "[posthog] extra. 'http' POSTs sanitized batches to "
+            "telemetry_http_endpoint."
+        ),
+    )
+    posthog_api_key: SecretStr | None = Field(
+        default=None,
+        description=(
+            "PostHog project API key. Required by the 'posthog' exporter; "
+            "without it telemetry stays inactive."
+        ),
+    )
+    posthog_host: str = Field(
+        default="https://us.i.posthog.com",
+        description="PostHog ingestion host.",
+    )
+    http_endpoint: str | None = Field(
+        default=None,
+        description=(
+            "Endpoint the 'http' exporter POSTs sanitized event batches to. "
+            "Intended to front a backend that revalidates auth and consent "
+            "before forwarding onward."
+        ),
+    )
+    http_token: SecretStr | None = Field(
+        default=None,
+        description="Bearer token sent by the 'http' exporter, if required.",
+    )
+    salt: SecretStr | None = Field(
+        default=None,
+        description=(
+            "Key used to pseudonymize conversation identifiers. Falls back to "
+            "a per-process random salt, which keeps pseudonyms stable within a "
+            "run but unlinkable across runs."
+        ),
+    )
+    max_queue_size: int = Field(
+        default=1000,
+        ge=1,
+        description=(
+            "Upper bound on buffered diagnostic events. The queue is bounded "
+            "on ingest: past this many events the oldest are dropped, so a "
+            "failing exporter cannot grow memory without limit."
+        ),
+    )
+    event_buffer_size: int = Field(
+        default=20, ge=1, description="Maximum events per delivery batch."
+    )
+    flush_delay: float = Field(
+        default=30.0,
+        gt=0,
+        description="Seconds to wait before flushing a partial batch.",
+    )
+    num_retries: int = Field(
+        default=2, ge=0, description="Retries before a batch is dropped."
+    )
+    retry_delay: float = Field(
+        default=5.0, ge=0, description="Base seconds between delivery retries."
+    )
+
+
 class Config(BaseModel):
     """
     Immutable configuration for a server running in local mode.
@@ -270,6 +349,13 @@ class Config(BaseModel):
             "to expire before the first renewal, effectively making it one-shot."
         ),
     )
+    telemetry: TelemetrySpec = Field(
+        default_factory=TelemetrySpec,
+        description=(
+            "Product-analytics policy. Disabled by default; see TelemetrySpec. "
+            "Distinct from LLM completion logging and from Laminar/OTel tracing."
+        ),
+    )
     model_config: ClassVar[ConfigDict] = {"frozen": True}
 
     @property