agent-observatory-cli 0.1.0__py3-none-any.whl

observatory/server.py

@@ -0,0 +1,368 @@
+"""Small local HTTP receiver and dashboard, using only the Python standard library."""
+from __future__ import annotations
+
+import hmac
+import gzip
+import io
+import json
+import os
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+from .core import Store, normalize_native, normalize_otlp, TRACE_ID
+from .otlp_proto import decode_trace_request
+from .logs import normalize_otlp_logs, decode_log_request
+from .metrics import normalize_otlp_metrics, decode_metric_request
+from .watch import start_watchers
+from .distribution import installer_info, package_archive
+
+UI = Path(__file__).with_name("index.html")
+MAX_BODY = 8 * 1024 * 1024
+
+
+def handler_for(store: Store, token: str | None = None, quiet=False):
+    class Handler(BaseHTTPRequestHandler):
+        def _json(self, code, value):
+            data = json.dumps(value, ensure_ascii=False).encode()
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(data)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(data)
+
+        def _protobuf_ok(self):
+            # Empty OTLP export response means the full batch was accepted.
+            self.send_response(200)
+            self.send_header("Content-Type", "application/x-protobuf")
+            self.send_header("Content-Length", "0")
+            self.end_headers()
+
+        def _authorized(self):
+            if not token:
+                return True
+            header = self.headers.get("Authorization", "")
+            return hmac.compare_digest(header, f"Bearer {token}")
+
+        def _route(self):
+            route = urlparse(self.path)
+            # The static shell contains no telemetry; its API requests still need a token.
+            if self.command == "GET" and route.path in {"/", "/setup.js", "/setup.css", "/activity.js", "/activity.css"}:
+                return route
+            if not self._authorized():
+                self._json(401, {"error": "unauthorized"})
+                return None
+            return route
+
+        def do_GET(self):
+            route = self._route()
+            if route is None:
+                return
+            path = route.path
+            if path == "/":
+                data = UI.read_bytes()
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.send_header("Content-Length", str(len(data)))
+                self.send_header("Cache-Control", "no-store")
+                self.end_headers()
+                self.wfile.write(data)
+            elif path in {"/setup.js", "/setup.css", "/activity.js", "/activity.css"}:
+                data = UI.with_name(path[1:]).read_bytes()
+                self.send_response(200)
+                self.send_header("Content-Type", "text/javascript; charset=utf-8" if path.endswith(".js") else "text/css; charset=utf-8")
+                self.send_header("Content-Length", str(len(data)))
+                self.send_header("Cache-Control", "no-store")
+                self.end_headers()
+                self.wfile.write(data)
+            elif path == "/api/health":
+                local = getattr(store, "local_agent_monitor", None)
+                self._json(200, {"ok": True, "local_agents": local.status() if local else {"enabled": False}})
+            elif path == "/api/setup":
+                self._json(200, {**installer_info(),
+                                 "auth_required": bool(token),
+                                 "integrations": ["OpenAI Python SDK", "Anthropic Python SDK", "LangChain / LangGraph"]})
+            elif path == "/api/package":
+                data, filename = package_archive()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/gzip")
+                self.send_header("Content-Length", str(len(data)))
+                self.send_header("Content-Disposition", f'attachment; filename="{filename}"')
+                self.send_header("Cache-Control", "no-store")
+                self.end_headers()
+                self.wfile.write(data)
+            elif path == "/api/connections":
+                self._json(200, {"connections": store.connections()})
+            elif path == "/api/activity":
+                query = parse_qs(route.query)
+                try:
+                    page = store.activity_page(limit=int(query.get("limit", [100])[0]),
+                        service=query.get("service", [None])[0], domain=query.get("domain", [None])[0],
+                        query=query.get("q", [None])[0], session_id=query.get("session_id", [None])[0],
+                        cursor=query.get("cursor", [None])[0],
+                        include_reviews=query.get("include_reviews", ["1"])[0]!="0",
+                        errors_only=query.get("errors_only", ["0"])[0]=="1")
+                    self._json(200, page)
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+            elif path == "/api/metrics":
+                self._json(200, store.metrics())
+            elif path == "/api/mcp":
+                query = parse_qs(route.query)
+                try:
+                    page = store.mcp_page(limit=int(query.get('limit', [100])[0]),
+                        service=query.get('service', [None])[0], session_id=query.get('session_id', [None])[0],
+                        query=query.get('q', [None])[0], cursor=query.get('cursor', [None])[0],
+                        include_reviews=query.get('include_reviews', ['1'])[0]!='0')
+                    self._json(200, {**page, 'scope': 'stored MCP operations'})
+                except ValueError as exc:
+                    self._json(400, {'error': str(exc)})
+            elif path == "/api/usage-series":
+                query = parse_qs(route.query)
+                try:
+                    days = int(query.get("days", [7])[0])
+                    step = query.get("step", ["day"])[0]
+                    service = query.get("service", [None])[0]
+                    self._json(200, store.usage_series(days=days, step=step, service=service))
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+            elif path == "/api/logs":
+                self._json(200, {"logs": store.logs(limit=500)})
+            elif path == "/api/measurements":
+                query = parse_qs(route.query, keep_blank_values=True)
+                try:
+                    limit = max(1, min(500, int(query.get("limit", [500])[0])))
+                    temporality = query.get("temporality", [None])[0]
+                    points = store.metric_points(limit=limit,
+                        service=query.get("service", [None])[0], name=query.get("name", [None])[0],
+                        kind=query.get("kind", [None])[0],
+                        temporality=int(temporality) if temporality is not None else None,
+                        scope_name=query.get("scope_name", [None])[0],
+                        unit=query.get("unit", [None])[0],
+                        description=query.get("description", [None])[0])
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+                    return
+                self._json(200, {"points": points})
+            elif path == "/api/metric-catalog":
+                query = parse_qs(route.query)
+                try:
+                    limit = max(1, min(500, int(query.get("limit", [200])[0])))
+                    self._json(200, {"metrics": store.metric_catalog(limit=limit)})
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+            elif path == "/api/findings":
+                query = parse_qs(route.query)
+                try:
+                    limit = max(1, min(500, int(query.get("limit", [100])[0])))
+                    page = store.finding_page(limit=limit, cursor=query.get("cursor", [None])[0])
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+                    return
+                self._json(200, page)
+            elif path == "/api/sessions":
+                query = parse_qs(route.query)
+                try:
+                    limit = max(1, min(500, int(query.get("limit", [100])[0])))
+                    self._json(200, {"sessions": store.sessions(limit=limit)})
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+            elif path == "/api/endpoints":
+                query = parse_qs(route.query)
+                try:
+                    limit = max(1, min(500, int(query.get("limit", [100])[0])))
+                    self._json(200, {"endpoints": store.endpoints(limit=limit)})
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+            elif path == "/api/outcomes":
+                self._json(200, {"outcomes": list(store.outcomes().values())})
+            elif path == "/api/traces":
+                query = parse_qs(route.query)
+                try:
+                    limit = max(1, min(500, int(query.get("limit", [100])[0])))
+                except ValueError:
+                    self._json(400, {"error": "invalid limit"})
+                    return
+                try:
+                    page = store.trace_page(limit, query.get("service", [None])[0],
+                                            query.get("status", [None])[0],
+                                            query.get("cursor", [None])[0],
+                                            query.get("session_id", [None])[0],
+                                            query.get("q", [None])[0],
+                                            query.get("endpoint_id", [None])[0],
+                                            query.get("include_reviews", ["1"])[0]!="0")
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+                    return
+                self._json(200, page)
+            elif path.startswith("/api/traces/") and path.endswith("/related"):
+                trace_id = path.removeprefix("/api/traces/").removesuffix("/related")
+                if not TRACE_ID.fullmatch(trace_id):
+                    self._json(400, {"error": "invalid trace_id"})
+                    return
+                self._json(200, {"related": store.related_traces(trace_id)})
+            elif path.startswith("/api/traces/") and path.endswith("/spans"):
+                trace_id = path.removeprefix("/api/traces/").removesuffix("/spans")
+                if not TRACE_ID.fullmatch(trace_id):
+                    self._json(400, {"error": "invalid trace_id"})
+                    return
+                query = parse_qs(route.query, keep_blank_values=True)
+                try:
+                    limit = max(1, min(500, int(query.get("limit", [200])[0])))
+                    page = store.span_page(trace_id, limit=limit,
+                        cursor=query.get("cursor", [None])[0],
+                        query=query.get("q", [""])[0].strip()[:200],
+                        span_filter=query.get("filter", ["all"])[0])
+                except ValueError as exc:
+                    self._json(400, {"error": str(exc)})
+                    return
+                self._json(200, page)
+            elif path.startswith("/api/traces/"):
+                trace_id = path.removeprefix("/api/traces/")
+                if not TRACE_ID.fullmatch(trace_id):
+                    self._json(400, {"error": "invalid trace_id"})
+                    return
+                query = parse_qs(route.query, keep_blank_values=True)
+                if "span_limit" in query:
+                    try:
+                        limit = max(1, min(500, int(query.get("span_limit", [200])[0])))
+                        result = store.trace_overview(trace_id)
+                        span_page = store.span_page(trace_id, limit=limit,
+                            query=query.get("q", [""])[0].strip()[:200],
+                            span_filter=query.get("filter", ["all"])[0])
+                    except ValueError as exc:
+                        self._json(400, {"error": str(exc)})
+                        return
+                    result["spans"] = span_page["spans"]
+                    result["span_page"] = {key: span_page[key] for key in
+                                            ("total", "trace_total", "next_cursor", "start_unix_nano", "end_unix_nano")}
+                else:
+                    result = store.trace(trace_id)
+                self._json(200 if result["summary"] or result["progress"] or result["logs"] or result["outcome"] else 404, result)
+            else:
+                self._json(404, {"error": "not found"})
+
+        def do_POST(self):
+            route = self._route()
+            if route is None:
+                return
+            try:
+                size = int(self.headers.get("Content-Length", "0"))
+                if size <= 0 or size > MAX_BODY:
+                    self._json(413, {"error": "body size must be 1 to 8 MiB"})
+                    return
+                raw = self.rfile.read(size)
+                if len(raw) != size:
+                    raise ValueError("truncated request body")
+                encoding = self.headers.get("Content-Encoding", "identity").lower()
+                if encoding == "gzip":
+                    with gzip.GzipFile(fileobj=io.BytesIO(raw)) as stream:
+                        raw = stream.read(MAX_BODY + 1)
+                    if len(raw) > MAX_BODY:
+                        self._json(413, {"error": "decompressed body exceeds 8 MiB"})
+                        return
+                elif encoding != "identity":
+                    self._json(415, {"error": "unsupported content encoding"})
+                    return
+                content_type = self.headers.get("Content-Type", "").split(";")[0].strip()
+                if route.path in ("/v1/traces", "/v1/logs", "/v1/metrics"):
+                    if content_type == "application/x-protobuf":
+                        if route.path == "/v1/traces":
+                            store.ingest(decode_trace_request(raw))
+                        elif route.path == "/v1/logs":
+                            store.ingest_logs(decode_log_request(raw))
+                        else:
+                            store.ingest_metrics(decode_metric_request(raw))
+                        self._protobuf_ok()
+                        return
+                    if content_type != "application/json":
+                        self._json(415, {"error": "OTLP requires application/json or application/x-protobuf"})
+                        return
+                body = json.loads(raw)
+                if route.path == "/api/spans":
+                    raw_spans = body if isinstance(body, list) else body.get("spans", [])
+                    if not isinstance(raw_spans, list):
+                        raise ValueError("spans must be an array")
+                    service = body.get("service", "agent-harness") if isinstance(body, dict) else "agent-harness"
+                    count = store.ingest([normalize_native(s, service) for s in raw_spans])
+                    self._json(200, {"accepted": count})
+                elif route.path == "/v1/traces":
+                    count = store.ingest(normalize_otlp(body))
+                    self._json(200, {"partialSuccess": {"rejectedSpans": 0}, "accepted": count})
+                elif route.path == "/v1/logs":
+                    count = store.ingest_logs(normalize_otlp_logs(body))
+                    self._json(200, {"partialSuccess": {"rejectedLogRecords": 0}, "accepted": count})
+                elif route.path == "/v1/metrics":
+                    count = store.ingest_metrics(normalize_otlp_metrics(body))
+                    self._json(200, {"partialSuccess": {"rejectedDataPoints": 0}, "accepted": count})
+                elif route.path == "/api/progress":
+                    store.add_progress(body["trace_id"], body["stage"], body.get("message", ""),
+                                       body.get("percent"), body.get("session_id"), body.get("service"))
+                    self._json(200, {"accepted": 1})
+                elif route.path == "/api/connections":
+                    store.register_connection(body)
+                    self._json(200, {"accepted": 1})
+                elif route.path == "/api/outcomes":
+                    records = body if isinstance(body, list) else body.get("results", [body])
+                    count = store.ingest_outcomes(records, source="api")
+                    self._json(200, {"accepted": count})
+                else:
+                    self._json(404, {"error": "not found"})
+            except (ValueError, TypeError, KeyError, AttributeError, OSError, EOFError, json.JSONDecodeError) as exc:
+                self._json(400, {"error": str(exc)})
+
+        def log_message(self, format, *args):
+            if not quiet and os.environ.get("OBSERVATORY_QUIET") != "1":
+                super().log_message(format, *args)
+
+    return Handler
+
+
+def serve(db_path="observatory.db", host="127.0.0.1", port=4318, token=None,
+          watch_jsonl=(), watch_service="agent-harness", retention_days=None, local_agents=True, metadata_only=False):
+    store = Store(db_path, async_derived_refresh=True)
+    if retention_days is not None:
+        store.prune(retention_days)
+    server = ThreadingHTTPServer((host, port), handler_for(store, token))
+    local = None
+    if local_agents and host in {"127.0.0.1", "localhost", "::1"}:
+        from .local_agents import LocalAgents
+        local = LocalAgents(store, capture_details=not metadata_only).start()
+    store.local_agent_monitor = local
+    watch = start_watchers(store, watch_jsonl, watch_service) if watch_jsonl else None
+    maintenance = _start_retention(store, retention_days) if retention_days is not None else None
+    print(f"Observatory listening at http://{host}:{server.server_port} (database: {db_path})", flush=True)
+    if local:
+        print("Watching local Codex / Claude Code sessions · " + ("metadata only" if metadata_only else "activity and bounded, redacted content"), flush=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+        if local:
+            local.close()
+        if watch:
+            watch[0].set()
+            watch[1].join(timeout=2)
+        if maintenance:
+            maintenance[0].set()
+            maintenance[1].join(timeout=2)
+        store.close()
+
+
+def _start_retention(store, retention_days, interval_seconds=3600):
+    stop = threading.Event()
+
+    def maintain():
+        while not stop.is_set():
+            stop.wait(interval_seconds)
+            if stop.is_set():
+                break
+            store.prune(retention_days)
+
+    thread = threading.Thread(target=maintain, name="observatory-retention", daemon=True)
+    thread.start()
+    return stop, thread

observatory/setup.css

@@ -0,0 +1,40 @@
+[hidden]{display:none!important}
+.header-actions{display:flex;align-items:center;gap:18px}
+.connect-button{border:1px solid #527fc2;background:#24466f;color:#eff5ff;border-radius:8px;padding:8px 14px;font-weight:600;white-space:nowrap}
+.connect-button:hover{background:#315b8b}
+.setup-panel{border:1px solid #34547b;border-radius:14px;background:linear-gradient(135deg,#182a44,#111b2c);padding:26px;margin-bottom:20px}
+.setup-heading{display:flex;justify-content:space-between;gap:20px;align-items:flex-start}
+.setup-heading h1{font-size:27px;letter-spacing:-.025em;margin:6px 0 10px}
+.setup-heading p{color:#afc0d7;max-width:720px;line-height:1.6;margin:0}
+.setup-close{border:0;background:transparent;color:#aebdd1;font-size:24px;padding:0 4px}
+.setup-fields{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:24px}
+.setup-field{display:flex;flex-direction:column;gap:7px;color:#ced9e9;font-size:12px}
+.setup-field input,.setup-field select{width:100%;padding:10px 12px;background:#0c1727;color:#e7edf7;border:1px solid #3b4e69;border-radius:7px}
+.setup-field small{color:#98abc4;line-height:1.4}
+.setup-capture{display:flex;align-items:center;gap:9px;margin:18px 0 6px;color:#d8e3f2;font-size:13px}
+.setup-capture input{accent-color:#77aaff}
+.setup-capture-note{font-size:12px;color:#98abc4;margin-left:23px;line-height:1.5}
+.setup-steps{display:grid;grid-template-columns:1fr 1.3fr;gap:14px;margin-top:24px}
+.setup-step{background:#101c2e;border:1px solid #30435d;border-radius:10px;padding:16px;min-width:0}
+.setup-step h3{margin:0 0 8px;font-size:14px;display:flex;align-items:center;gap:9px}
+.setup-step h3 span{display:inline-flex;align-items:center;justify-content:center;border:1px solid #4c6c94;border-radius:50%;height:24px;width:24px;font-size:12px;color:#a9ceff}
+.setup-step p{font-size:12px;color:#a7b8d0;line-height:1.6;margin:0 0 12px}
+.setup-code{position:relative;border:1px solid #2d405a;border-radius:7px;background:#091321;padding:12px;overflow:auto}
+.setup-code pre{margin:0;padding-right:54px;white-space:pre-wrap;overflow-wrap:anywhere;color:#c4ddff;font:12px/1.7 ui-monospace,SFMono-Regular,monospace}
+.setup-copy{position:absolute;right:7px;top:8px;border:1px solid #3d5676;border-radius:5px;background:#1b2e48;color:#c8dbf5;font-size:11px;padding:4px 7px}
+.setup-hint{font-size:12px;color:#a7b8d0;line-height:1.6;margin:18px 0 0}
+.setup-support{display:flex;gap:7px;flex-wrap:wrap;margin-top:14px}
+.setup-support span{border:1px solid #355374;border-radius:20px;padding:5px 9px;font-size:11px;color:#bbd3f0}
+.source-strip{margin-bottom:16px;display:flex;gap:8px;align-items:center;flex-wrap:wrap}
+.receiver-state{font-size:12px;color:#a8d9c0;display:inline-flex;align-items:center;gap:7px}
+.receiver-state::before{content:'';width:7px;height:7px;border-radius:50%;background:#78d4a4}
+.connected-source{border:1px solid #354b68;background:#15243a;border-radius:8px;padding:9px 12px;display:flex;flex-direction:column;gap:5px;font-size:12px}
+.connected-source small{color:#a5b8d3;font-size:11px}
+.connected-source.receiving{border-color:#37745c}
+.connected-source.offline{opacity:.65}
+.waiting-card{border:1px dashed #34506f;background:#101b2b;border-radius:12px;text-align:center;padding:44px 24px}
+.waiting-card h2{font-size:19px;margin:0 0 9px;color:#e0ebfa}
+.waiting-card p{line-height:1.6;max-width:580px;margin:0 auto;color:#a4b6cf}
+.setup-feedback{font-size:12px;color:#acdcbe;min-height:17px;margin-top:9px}
+@media(max-width:900px){.setup-steps{grid-template-columns:1fr}.setup-panel{padding:20px}.header-actions{gap:8px}header small{display:none}}
+@media(max-width:600px){.setup-fields{grid-template-columns:1fr}.setup-heading h1{font-size:23px}.connect-button{font-size:12px;padding:7px 9px}.setup-panel{padding:16px}}

observatory/setup.js

@@ -0,0 +1,145 @@
+let setupConfig = null;
+let setupOpened = false;
+let setupDismissed = false;
+window.observatoryHasData = false;
+const setupElement = id => document.getElementById(id);
+const shellQuote = value => "'" + String(value).replace(/'/g, "'\\''") + "'";
+
+function openAgentSetup() {
+  setupOpened = true;
+  setupDismissed = false;
+  setupElement('agent-setup').hidden = false;
+  setupElement('agent-setup').scrollIntoView({behavior:'smooth',block:'start'});
+}
+
+function updateSetupCommands() {
+  const python = setupElement('setup-runtime').value === 'python';
+  const endpoint = setupElement('setup-endpoint').value.trim() || location.origin;
+  const service = setupElement('setup-service').value.trim() || 'my-agent';
+  const target = setupElement('setup-target').value.trim() || 'agent.py';
+  setupElement('setup-install-step').hidden = !python;
+  setupElement('setup-launch-number').textContent = python ? '2' : '1';
+  setupElement('setup-target-field').hidden = !python;
+  setupElement('setup-capture-options').hidden = !python;
+  setupElement('setup-launch-title').textContent = python ? 'Start your agent with automatic capture' : 'Configure your exporter';
+  setupElement('setup-launch-help').textContent = python
+    ? 'Use your agent’s Python environment. Replace its usual “python agent.py” command with this command; its arguments go at the end.'
+    : 'Use these settings in an app that already exports OpenTelemetry. Choose OTLP over HTTP, then restart the app.';
+  let command;
+  if (python) {
+    command = 'python -m observatory run --endpoint ' + shellQuote(endpoint) + ' --service ' + shellQuote(service);
+    if (setupElement('setup-capture').checked) command += ' --capture-content';
+    if (setupElement('setup-module').checked) command += ' --module';
+    command += ' ' + shellQuote(target);
+  } else {
+    command = 'export OTEL_EXPORTER_OTLP_ENDPOINT=' + shellQuote(endpoint) + '\n'
+      + 'export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\n'
+      + 'export OTEL_SERVICE_NAME=' + shellQuote(service);
+  }
+  setupElement('setup-launch-code').textContent = command;
+  setupElement('setup-install-code').textContent = setupConfig?.install_command
+    || 'Download the installer to get your install command.';
+  setupElement('setup-runtime-note').textContent = python
+    ? 'Captures OpenAI and Anthropic SDK calls, plus LangChain / LangGraph activity. OpenAI-compatible local servers work when called through the OpenAI Python SDK. Restart existing agents through this launcher.'
+    : 'Your app needs an OpenTelemetry SDK and exporter. These settings send its existing traces, logs, and metrics to this receiver.';
+}
+
+async function downloadSetupPackage() {
+  const button = setupElement('download-agent-package');
+  button.disabled = true;
+  try {
+    if (!setupConfig) {
+      setupConfig = await get('/api/setup');
+      updateSetupCommands();
+    }
+    const response = await authorizedFetch('/api/package');
+    if (!response.ok) throw new Error('HTTP '+response.status);
+    const blob = await response.blob();
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = setupConfig?.package_filename || 'agent-observatory.tar.gz';
+    document.body.append(link);
+    link.click();
+    link.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 10000);
+    setupElement('setup-feedback').textContent = 'Downloaded. Run the install command from your download folder, in your agent’s Python environment.';
+  } catch (error) {
+    setupElement('setup-feedback').textContent = 'Download failed: '+error.message+'. Refresh the page and retry.';
+  } finally {
+    button.disabled = false;
+  }
+}
+
+async function copySetupCommand(id, button) {
+  const text = setupElement(id).textContent;
+  try {
+    await navigator.clipboard.writeText(text);
+    button.textContent = 'Copied';
+    setupElement('setup-feedback').textContent = 'Command copied. Paste it into your agent’s terminal.';
+    setTimeout(() => { button.textContent = 'Copy'; }, 1600);
+  } catch {
+    const selection = window.getSelection();
+    const range = document.createRange();
+    range.selectNodeContents(setupElement(id));
+    selection.removeAllRanges();
+    selection.addRange(range);
+    setupElement('setup-feedback').textContent = 'Select and copy the highlighted command.';
+  }
+}
+
+async function refreshAgentConnections(stats) {
+  if (!setupConfig) {
+    setupConfig = await get('/api/setup');
+    setupElement('setup-auth-hint').hidden = !setupConfig.auth_required;
+    updateSetupCommands();
+  }
+  const data = await get('/api/connections');
+  const sources = data.connections;
+  window.observatoryHasData = Boolean(stats.spans || stats.logs || stats.metric_points || stats.runs);
+  setupElement('agent-setup').hidden = setupDismissed || (window.observatoryHasData && !setupOpened);
+  setupElement('investigation').hidden = !window.observatoryHasData;
+  setupElement('waiting-first-call').hidden = window.observatoryHasData;
+  const active = sources.filter(source => source.state === 'running');
+  setupElement('receiver-state').textContent = active.length
+    ? 'Receiver listening · '+active.length+' agent'+(active.length === 1 ? '' : 's')+' connected'
+    : 'Receiver listening · '+location.host;
+  setupElement('waiting-title').textContent = active.length ? 'Agent connected. Waiting for a model call.' : 'Waiting for your first agent';
+  setupElement('waiting-help').textContent = active.length
+    ? 'Use your agent normally. Finished model calls appear here with their model, duration, token usage, and recorded errors.'
+    : 'Install automatic capture in your agent’s environment, start it with the command above, and make a model call. This page updates automatically.';
+  const host = setupElement('connected-agents');
+  host.replaceChildren();
+  for (const source of sources.slice(0,8)) {
+    const card = document.createElement('div');
+    card.className = 'connected-source' + (source.span_count ? ' receiving' : '') + (source.state === 'offline' ? ' offline' : '');
+    const title = document.createElement('strong');
+    title.textContent = source.service;
+    const status = document.createElement('small');
+    const local = source.integrations.includes('local-session-log');
+    const state = local ? (source.state === 'running' ? 'Recent session activity' : 'Idle / last observed') : source.state === 'running' ? (source.span_count ? 'Receiving telemetry' : 'Connected · monitoring enabled')
+      : source.state === 'stopped' ? 'Finished' : 'Disconnected';
+    status.textContent = state+' · '+source.span_count+' spans received';
+    const details = document.createElement('small');
+    details.textContent = source.integrations.join(', ') + (source.capture_content ? ' · content included' : ' · metadata only');
+    card.append(title,status,details);
+    host.append(card);
+  }
+}
+
+setupElement('connect-agent').onclick = openAgentSetup;
+setupElement('download-agent-package').onclick = downloadSetupPackage;
+setupElement('close-agent-setup').onclick = () => {
+  setupDismissed = true;
+  setupOpened = false;
+  setupElement('agent-setup').hidden = true;
+};
+setupElement('setup-endpoint').value = location.origin;
+for (const id of ['setup-runtime','setup-endpoint','setup-service','setup-target','setup-capture','setup-module']) {
+  setupElement(id).addEventListener('input', updateSetupCommands);
+  setupElement(id).addEventListener('change', updateSetupCommands);
+}
+for (const button of document.querySelectorAll('[data-copy-command]')) {
+  button.onclick = () => copySetupCommand(button.dataset.copyCommand, button);
+}
+updateSetupCommands();