autotel-devtools 8.0.0 → 8.1.1

package/README.md

@@ -149,12 +149,29 @@ process — point them at the bound port, or free the original.
 - ✅ Error aggregation and grouping
 - ✅ Service map visualization
 - ✅ Resources view (derived from telemetry)
+- ✅ GenAI run summaries + narrated walkthrough
 - ✅ Search with debounce (300ms)
 - ✅ Configurable telemetry limits (env vars)
 - ✅ Widget position persistence (localStorage)
 - ✅ Export traces as JSON
 - ✅ Custom element support (`<autotel-devtools>`)
 
+### GenAI: read an agent run at a glance
+
+When your app emits OpenTelemetry GenAI spans (Vercel AI SDK, Pydantic AI, OpenAI
+Agents, Anthropic, Google GenAI, LangChain, …), the **GenAI** tab gives two extras
+on top of the per-span detail:
+
+- A **run summary strip** sits above the detail for any multi-span run — total
+  cost (table-priced; a trailing `+` marks a lower bound when some calls are
+  unpriced), input→output tokens, reasoning tokens, model calls, tool
+  executions, sub-agents, duration and errors.
+- An **Explain run** button steps through the run in chronological order with
+  plain-language narration of each step. Auto-play or step manually with the
+  arrow keys / Space (Esc exits); clicking a span jumps the tour to that step.
+  Useful for showing a teammate or a client exactly what the agent did, which
+  tools it called, and where the cost went.
+
 ## Configuration
 
 ### Environment Variables
@@ -240,6 +257,26 @@ await expect
   .toBeGreaterThan(0);
 ```
 
+These read-back calls run from Node (no `Origin` header), so they are unaffected
+by the origin guard below.
+
+## Read-surface origin guard
+
+OTLP **ingestion** (`POST /v1/{traces,logs,metrics}`), `GET /widget.js` and
+`GET /healthz` are open to any origin — browser apps on arbitrary dev origins
+must be able to send telemetry and load the embeddable widget. The **read**
+surface is not: `GET /v1/traces`, `DELETE /v1/traces` and the `/ws` WebSocket are
+origin-checked so a web page you happen to be visiting can't `fetch()` or stream
+your locally captured prompts, responses and tokens.
+
+- A non-loopback `Origin` (a cross-origin browser read) is rejected with `403`.
+- When bound to a loopback host (the default), a non-loopback `Host` (DNS
+  rebinding) is also rejected. `--host 0.0.0.0` opts into network exposure and
+  applies only the `Origin` check.
+
+The embedded widget keeps working — it connects from a loopback origin
+(`http://localhost:<your-app-port>`). Server-side reads with no `Origin` pass.
+
 ## License
 
 MIT

package/dist/cli.cjs

@@ -353,6 +353,40 @@ function appendManyWithLimit(items, incoming, limit) {
   return next.length > limit ? next.slice(next.length - limit) : next;
 }
 
+// src/server/origin-guard.ts
+var LOOPBACK_IPV6 = /* @__PURE__ */ new Set(["::1", "0:0:0:0:0:0:0:1"]);
+function isLoopbackHostname(hostname) {
+  const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  return h === "localhost" || /^127\./.test(h) || LOOPBACK_IPV6.has(h);
+}
+function hostnameFromHostHeader(host) {
+  const h = host.trim();
+  if (h.startsWith("[")) {
+    const end = h.indexOf("]");
+    return end > 0 ? h.slice(1, end) : h;
+  }
+  const colon = h.indexOf(":");
+  return colon === -1 ? h : h.slice(0, colon);
+}
+function hostHeaderIsLoopback(host) {
+  return isLoopbackHostname(hostnameFromHostHeader(host));
+}
+function originIsLoopback(origin) {
+  try {
+    return isLoopbackHostname(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+function allowSensitiveRequest(headers, loopbackOnly) {
+  const { origin, host } = headers;
+  if (origin && origin.length > 0 && !originIsLoopback(origin)) return false;
+  if (loopbackOnly && host && host.length > 0 && !hostHeaderIsLoopback(host)) {
+    return false;
+  }
+  return true;
+}
+
 // src/server/server.ts
 var DevtoolsServer = class {
   wss;
@@ -372,7 +406,12 @@ var DevtoolsServer = class {
     this._port = options.port ?? 4318;
     this.onData = options.onData;
     this.httpServer = options.server ?? http.createServer();
-    this.wss = new ws.WebSocketServer({ server: this.httpServer, path: options.path ?? "/ws" });
+    const loopbackOnly = options.host == null || hostHeaderIsLoopback(options.host);
+    this.wss = new ws.WebSocketServer({
+      server: this.httpServer,
+      path: options.path ?? "/ws",
+      verifyClient: ({ origin, req }) => allowSensitiveRequest({ origin, host: req.headers.host }, loopbackOnly)
+    });
     this.wss.on("error", (err) => {
       if (this.httpServer.listening) throw err;
     });
@@ -406,6 +445,7 @@ var DevtoolsServer = class {
   }
   addTrace(trace) {
     const existing = this.traces.find((t) => t.traceId === trace.traceId);
+    const merged = existing ?? trace;
     if (existing) {
       const existingSpanIds = new Set(existing.spans.map((s) => s.spanId));
       for (const span of trace.spans) {
@@ -417,6 +457,14 @@ var DevtoolsServer = class {
       existing.endTime = Math.max(existing.endTime, trace.endTime);
       existing.duration = existing.endTime - existing.startTime;
       if (trace.status === "ERROR") existing.status = "ERROR";
+      const root = existing.spans.find((s) => !s.parentSpanId);
+      if (root) {
+        existing.rootSpan = root;
+        const rootService = root.attributes?.["service.name"];
+        if (typeof rootService === "string" && rootService.length > 0) {
+          existing.service = rootService;
+        }
+      }
     } else {
       this.traces = appendWithLimit(
         this.traces,
@@ -425,7 +473,7 @@ var DevtoolsServer = class {
       );
     }
     this.errorAggregator.addErrorsFromTrace(trace);
-    this.broadcast({ traces: [trace], metrics: [], logs: [], errors: this.errorAggregator.getErrorGroups() });
+    this.broadcast({ traces: [merged], metrics: [], logs: [], errors: this.errorAggregator.getErrorGroups() });
   }
   addTraces(traces) {
     for (const trace of traces) this.addTrace(trace);
@@ -977,7 +1025,8 @@ function findPackageRoot() {
   }
   return dir;
 }
-var FULLPAGE_HTML = `<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>autotel-devtools</title><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;width:100%;overflow:hidden}</style></head><body><script src="/widget.js?mode=fullpage"></script></body></html>`;
+var DEVTOOLS_FAVICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="14" fill="#0f172a"/><text x="32" y="41" text-anchor="middle" font-size="32">\u{1F6F0}\uFE0F</text></svg>';
+var FULLPAGE_HTML = `<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>autotel-devtools</title><link rel="icon" href="/favicon.svg" type="image/svg+xml"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;width:100%;overflow:hidden}</style></head><body><script src="/widget.js?mode=fullpage"></script></body></html>`;
 var cachedVersion = null;
 function getVersion() {
   if (cachedVersion !== null) return cachedVersion;
@@ -1011,8 +1060,10 @@ function getWidgetJs() {
   }
   return cachedWidgetJs;
 }
-function attachDevtoolsRoutes(httpServer, devtools) {
+function attachDevtoolsRoutes(httpServer, devtools, options = {}) {
+  const loopbackOnly = options.loopbackOnly ?? true;
   httpServer.on("request", async (req, res) => {
+    if (req.headers.upgrade?.toLowerCase() === "websocket") return;
     res.setHeader("Access-Control-Allow-Origin", "*");
     res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type");
@@ -1035,6 +1086,15 @@ function attachDevtoolsRoutes(httpServer, devtools) {
       res.end(js);
       return;
     }
+    if (req.method === "GET" && (url === "/favicon.svg" || url === "/favicon.ico")) {
+      res.writeHead(200, {
+        "Content-Type": "image/svg+xml; charset=utf-8",
+        "Cache-Control": "public, max-age=86400",
+        "Content-Length": Buffer.byteLength(DEVTOOLS_FAVICON_SVG)
+      });
+      res.end(DEVTOOLS_FAVICON_SVG);
+      return;
+    }
     if (req.method === "GET" && url === "/healthz") {
       sendJson(res, 200, {
         ok: true,
@@ -1045,11 +1105,19 @@ function attachDevtoolsRoutes(httpServer, devtools) {
       return;
     }
     if (req.method === "GET" && url === "/v1/traces") {
+      if (!allowSensitiveRequest(req.headers, loopbackOnly)) {
+        sendJson(res, 403, { error: "Forbidden" });
+        return;
+      }
       const data = devtools.getCurrentData();
       sendJson(res, 200, { traces: data.traces, count: data.traces.length });
       return;
     }
     if (req.method === "DELETE" && url === "/v1/traces") {
+      if (!allowSensitiveRequest(req.headers, loopbackOnly)) {
+        sendJson(res, 403, { error: "Forbidden" });
+        return;
+      }
       devtools.clearData();
       sendJson(res, 200, { cleared: true });
       return;
@@ -1290,13 +1358,14 @@ async function main() {
     process.exit(0);
   }
   const httpServer = http.createServer();
-  const wsServer = new DevtoolsServer({ server: httpServer, verbose: true });
-  attachDevtoolsRoutes(httpServer, wsServer);
+  const loopbackOnly = hostHeaderIsLoopback(options.host);
+  const wsServer = new DevtoolsServer({ server: httpServer, host: options.host, verbose: true });
+  attachDevtoolsRoutes(httpServer, wsServer, { loopbackOnly });
   const listeners = listenLoopbackDualStack({
     primary: httpServer,
     port: options.port,
     host: options.host,
-    attachSecondary: (s) => attachDevtoolsRoutes(s, wsServer)
+    attachSecondary: (s) => attachDevtoolsRoutes(s, wsServer, { loopbackOnly })
   });
   const { addresses, warnings, port: boundPort } = await listeners.ready;
   if (boundPort !== options.port) {