@mtharrison/loupe 1.4.0 → 1.6.0

package/README.md

@@ -40,16 +40,18 @@ npm install @mtharrison/loupe
 
 ### Requirements
 
-- Node.js 18 or newer
+- Node.js 20 or newer
 
 ## Quick Start
 
-Enable tracing:
+Enable tracing explicitly:
 
 ```bash
 export LLM_TRACE_ENABLED=1
 ```
 
+Or just run your app with `NODE_ENV=development`. Loupe enables tracing implicitly in development and eagerly starts the dashboard when the tracer is first created, opening it automatically in an interactive local terminal.
+
 If your app already uses a higher-level model interface or the official OpenAI client, Loupe can wrap that directly instead of requiring manual `record*` calls.
 
 ### `wrapOpenAIClient(client, getContext, config?)`
@@ -87,7 +89,7 @@ for await (const chunk of stream) {
 }
 ```
 
-If you do not call `startServer()` yourself, the dashboard starts lazily on the first recorded trace.
+In `NODE_ENV=development`, you do not need to call `startServer()` explicitly. Creating the tracer is enough to start the dashboard.
 
 When the server starts, Loupe prints the local URL:
 
@@ -95,6 +97,8 @@ When the server starts, Loupe prints the local URL:
 [llm-trace] dashboard: http://127.0.0.1:4319
 ```
 
+In `NODE_ENV=development`, Loupe also opens that URL in your browser automatically unless `CI` is set, the terminal is non-interactive, or `LOUPE_OPEN_BROWSER=0`.
+
 If `4319` is already in use and you did not explicitly configure a port, Loupe falls back to another free local port and prints that URL instead.
 
 `wrapOpenAIClient()` is structurally typed, so Loupe's runtime API does not require the OpenAI SDK for normal library usage. The repo includes `openai` as a dev dependency for the bundled demo; if your own app instantiates `new OpenAI()` or runs the published example from a consumer install, install `openai` there too.
@@ -144,6 +148,25 @@ export LLM_TRACE_ENABLED=1
 node examples/nested-tool-call.js
 ```
 
+### Runnable Fully Featured Demo
+
+`examples/fully-featured.js` is a credential-free demo that combines the main local tracing features in one session:
+
+- a top-level input guardrail span recorded with the low-level lifecycle API
+- a wrapped `invoke()` call with a nested stage span and child actor span
+- a handled child-span error so the dashboard shows both success and failure states
+- a wrapped `stream()` call with reconstructed output and usage
+
+Run it with:
+
+```bash
+npm install
+export LLM_TRACE_ENABLED=1
+node examples/fully-featured.js
+```
+
+Supported demo environment variables: `LLM_TRACE_PORT`, `LOUPE_OPEN_BROWSER`.
+
 ## Low-Level Lifecycle API
 
 If you need full control over trace boundaries, Loupe exposes a lower-level span lifecycle API modeled on OpenTelemetry concepts: start a span, add events, end it, and record exceptions.
@@ -345,11 +368,12 @@ Environment variables:
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `LLM_TRACE_ENABLED` | `false` | Enables Loupe. |
+| `LLM_TRACE_ENABLED` | `true` when `NODE_ENV=development`, otherwise `false` | Enables Loupe. |
 | `LLM_TRACE_HOST` | `127.0.0.1` | Host for the local dashboard server. |
 | `LLM_TRACE_PORT` | `4319` | Port for the local dashboard server. If unset, Loupe tries `4319` first and falls back to a free local port if it is already in use. |
 | `LLM_TRACE_MAX_TRACES` | `1000` | Maximum number of traces kept in memory. |
 | `LLM_TRACE_UI_HOT_RELOAD` | auto in local interactive dev | Enables UI rebuild + reload while developing the dashboard itself. |
+| `LOUPE_OPEN_BROWSER` | `enabled` in local `NODE_ENV=development` sessions | Opens the dashboard in your browser on first server start. Set `0` to suppress it. |
 
 Programmatic configuration is also available through `getLocalLLMTracer(config)`.
 

package/dist/client/app.css

@@ -29,22 +29,26 @@
 }
 :root[data-theme=dark] {
   color-scheme: dark;
-  --background: #111b29;
-  --background-strong: #09111c;
-  --panel: rgba(22, 32, 47, 0.96);
-  --panel-strong: rgba(28, 40, 59, 0.98);
-  --panel-soft: rgba(115, 170, 255, 0.16);
-  --foreground: #f3f7ff;
-  --muted-foreground: #b6c5d9;
-  --line: rgba(140, 164, 197, 0.24);
-  --line-strong: rgba(145, 193, 255, 0.52);
-  --primary: #9dc8ff;
-  --primary-strong: #f4f8ff;
-  --secondary: rgba(120, 155, 212, 0.18);
-  --warning: #f2bf67;
-  --danger: #f39bac;
-  --success: #7ad1aa;
-  --shadow: 0 30px 90px rgba(1, 8, 20, 0.56);
+  --background: #0b1523;
+  --background-strong: #040913;
+  --panel: rgba(16, 27, 41, 0.9);
+  --panel-strong: rgba(12, 22, 35, 0.94);
+  --panel-soft: rgba(91, 186, 255, 0.14);
+  --surface-elevated: rgba(20, 34, 52, 0.96);
+  --surface-overlay: rgba(15, 25, 39, 0.94);
+  --surface-highlight: rgba(33, 57, 87, 0.98);
+  --surface-code: rgba(7, 13, 23, 0.96);
+  --foreground: #ecf4ff;
+  --muted-foreground: #9bb0c8;
+  --line: rgba(117, 146, 180, 0.24);
+  --line-strong: rgba(126, 196, 255, 0.5);
+  --primary: #88d0ff;
+  --primary-strong: #f5fbff;
+  --secondary: rgba(91, 138, 200, 0.18);
+  --warning: #ffc57b;
+  --danger: #ff9eae;
+  --success: #72ddb7;
+  --shadow: 0 34px 96px rgba(1, 8, 20, 0.62);
 }
 * {
   box-sizing: border-box;
@@ -90,18 +94,22 @@ body {
 :root[data-theme=dark] body {
   background:
     radial-gradient(
-      circle at top left,
-      rgba(108, 158, 235, 0.2),
-      transparent 34rem),
+      circle at 12% 0%,
+      rgba(86, 166, 255, 0.28),
+      transparent 30rem),
     radial-gradient(
-      circle at top right,
-      rgba(138, 164, 207, 0.12),
-      transparent 28rem),
+      circle at 88% 8%,
+      rgba(52, 197, 182, 0.14),
+      transparent 26rem),
+    radial-gradient(
+      circle at 50% 115%,
+      rgba(33, 86, 146, 0.4),
+      transparent 38rem),
     linear-gradient(
       180deg,
-      #1a2638 0%,
-      #101a28 45%,
-      #09111c 100%);
+      #162436 0%,
+      #0a1320 46%,
+      #030811 100%);
 }
 button,
 input,
@@ -1183,6 +1191,12 @@ pre {
   overflow: auto;
   padding-right: 0.2rem;
 }
+.hierarchy-timeline-empty-state {
+  padding: 0.8rem 0.55rem 0.4rem;
+  color: var(--muted-foreground);
+  font-size: 0.78rem;
+  line-height: 1.45;
+}
 .hierarchy-timeline-row {
   --timeline-time-column: 4.75rem;
   --timeline-column-gap: 0.45rem;
@@ -1295,6 +1309,13 @@ pre {
 .hierarchy-timeline-row.is-guardrail {
   --timeline-row-color: rgba(184, 129, 44, 0.92);
 }
+.hierarchy-timeline-row.is-guardrail-trace {
+  --timeline-row-color: rgba(184, 129, 44, 0.92);
+}
+.hierarchy-timeline-row.is-guardrail-group::before {
+  border-color: color-mix(in srgb, var(--timeline-row-color) 18%, rgba(84, 100, 125, 0.08));
+  background: color-mix(in srgb, var(--timeline-row-color) 10%, rgba(255, 255, 255, 0.72));
+}
 .hierarchy-timeline-row.is-trace {
   --timeline-row-color: rgba(92, 121, 171, 0.9);
 }
@@ -1396,6 +1417,20 @@ pre {
   min-width: 0;
   flex-wrap: wrap;
 }
+.hierarchy-timeline-row-toggle-label {
+  display: inline-flex;
+  align-items: center;
+  min-height: 1.3rem;
+  padding: 0.12rem 0.46rem;
+  border-radius: 999px;
+  border: 1px solid rgba(184, 129, 44, 0.16);
+  background: rgba(184, 129, 44, 0.08);
+  color: #865815;
+  font-size: 0.67rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
 .hierarchy-timeline-row-flag {
   display: inline-flex;
   align-items: center;
@@ -1499,6 +1534,25 @@ pre {
   text-align: right;
   white-space: nowrap;
 }
+.hierarchy-timeline-row.is-guardrail-group .hierarchy-timeline-row-labels,
+.hierarchy-timeline-row.is-guardrail-compact .hierarchy-timeline-row-labels {
+  gap: 0.14rem;
+  padding-top: 0.42rem;
+  padding-bottom: 0.42rem;
+}
+.hierarchy-timeline-row.is-guardrail-group .hierarchy-timeline-row-bars,
+.hierarchy-timeline-row.is-guardrail-compact .hierarchy-timeline-row-bars {
+  padding-top: 0.42rem;
+  padding-bottom: 0.42rem;
+}
+.hierarchy-timeline-row.is-guardrail-group .hierarchy-timeline-row-title-text,
+.hierarchy-timeline-row.is-guardrail-compact .hierarchy-timeline-row-title-text {
+  font-size: 0.84rem;
+}
+.hierarchy-timeline-row.is-guardrail-group .hierarchy-timeline-row-meta,
+.hierarchy-timeline-row.is-guardrail-compact .hierarchy-timeline-row-meta {
+  font-size: 0.73rem;
+}
 .trace-detail-header {
   display: flex;
   align-items: flex-start;
@@ -1917,6 +1971,19 @@ pre {
 .session-tree-timeline-shell {
   padding: 0.08rem 0.1rem 0.24rem 0.5rem;
 }
+.session-tree-timeline-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.65rem;
+  padding: 0.1rem 0.2rem 0.45rem 0.08rem;
+}
+.session-tree-timeline-toolbar-copy {
+  color: var(--muted-foreground);
+  font-size: 0.72rem;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
 .session-tree-timeline-list {
   display: flex;
   flex-direction: column;
@@ -1977,6 +2044,23 @@ pre {
   min-height: 0;
   padding-top: 2.05rem;
 }
+.session-tree-timeline-list .hierarchy-timeline-row.is-guardrail-group .hierarchy-timeline-row-labels,
+.session-tree-timeline-list .hierarchy-timeline-row.is-guardrail-compact .hierarchy-timeline-row-labels {
+  padding-top: 0.62rem;
+  padding-bottom: 0.62rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-row.is-guardrail-group .hierarchy-timeline-row-title,
+.session-tree-timeline-list .hierarchy-timeline-row.is-guardrail-compact .hierarchy-timeline-row-title {
+  padding-top: 1.7rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-row.is-guardrail-group .hierarchy-timeline-row-bars,
+.session-tree-timeline-list .hierarchy-timeline-row.is-guardrail-compact .hierarchy-timeline-row-bars {
+  top: 0.62rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-row.has-semantic-indent .hierarchy-timeline-row-ancestor,
+.session-tree-timeline-list .hierarchy-timeline-row.has-semantic-indent .hierarchy-timeline-row-connector {
+  display: none;
+}
 .session-tree-timeline-list .hierarchy-timeline-row-title-text,
 .session-tree-timeline-list .hierarchy-timeline-row-meta {
   overflow: hidden;
@@ -2479,86 +2563,11 @@ pre {
   padding: 0.9rem 1rem;
   box-shadow: inset 3px 0 0 var(--message-accent), inset 0 1px 0 rgba(255, 255, 255, 0.72);
 }
-.message-insight-banner {
-  display: flex;
-  flex-direction: column;
-  gap: 0.55rem;
-  margin-bottom: 0.85rem;
-}
-.message-insight-card {
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
-  padding: 0.7rem 0.8rem;
-  border: 1px solid rgba(184, 129, 44, 0.16);
-  border-radius: 12px;
-  background: rgba(255, 248, 236, 0.9);
-}
-.message-insight-card.is-highlight {
-  border-color: rgba(86, 107, 147, 0.16);
-  background: rgba(241, 246, 255, 0.88);
-}
-.message-insight-card-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 0.5rem;
-  flex-wrap: wrap;
-}
-.message-insight-card-tags,
 .structured-markup-tags {
   display: flex;
   flex-wrap: wrap;
   gap: 0.35rem;
 }
-.message-insight-card-copy {
-  color: var(--foreground);
-  font-size: 0.82rem;
-  line-height: 1.45;
-}
-.trace-insights-content {
-  display: flex;
-  flex-direction: column;
-  gap: 0.7rem;
-}
-.trace-insight-item {
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
-  padding: 0.78rem 0.85rem;
-  border: 1px solid rgba(86, 107, 147, 0.14);
-  border-radius: 12px;
-  background: rgba(243, 247, 255, 0.84);
-}
-.trace-insight-item.is-structured {
-  border-color: rgba(34, 154, 161, 0.16);
-  background: rgba(240, 252, 252, 0.9);
-}
-.trace-insight-item-header,
-.trace-insight-item-tags {
-  display: flex;
-  align-items: center;
-  gap: 0.45rem;
-  flex-wrap: wrap;
-}
-.trace-insight-item-header {
-  justify-content: space-between;
-}
-.trace-insight-item-source {
-  color: var(--muted-foreground);
-  font-size: 0.74rem;
-  font-family:
-    ui-monospace,
-    SFMono-Regular,
-    Menlo,
-    Consolas,
-    monospace;
-}
-.trace-insight-item-copy {
-  color: var(--foreground);
-  font-size: 0.83rem;
-  line-height: 1.5;
-}
 .structured-markup-block {
   display: flex;
   flex-direction: column;
@@ -3234,7 +3243,6 @@ pre {
 :root[data-theme=dark] .trace-detail-subtitle,
 :root[data-theme=dark] .trace-detail-json-toggle,
 :root[data-theme=dark] .message-card-hint,
-:root[data-theme=dark] .trace-insight-item-source,
 :root[data-theme=dark] .tool-call-label,
 :root[data-theme=dark] .metadata-grid dt,
 :root[data-theme=dark] .metadata-secondary,
@@ -3476,6 +3484,10 @@ pre {
   background: rgba(36, 52, 77, 0.96);
   box-shadow: inset 3px 0 0 rgba(134, 184, 255, 0.82), 0 10px 22px rgba(2, 10, 24, 0.18);
 }
+:root[data-theme=dark] .hierarchy-timeline-row.is-guardrail-group::before {
+  border-color: color-mix(in srgb, var(--timeline-row-color) 24%, rgba(128, 153, 189, 0.12));
+  background: color-mix(in srgb, var(--timeline-row-color) 12%, rgba(20, 29, 43, 0.94));
+}
 :root[data-theme=dark] .hierarchy-timeline-row-gutter::before,
 :root[data-theme=dark] .hierarchy-timeline-row-gutter::after {
   background: color-mix(in srgb, var(--timeline-row-color) 24%, rgba(128, 153, 189, 0.14));
@@ -3497,6 +3509,11 @@ pre {
   background: rgba(184, 129, 44, 0.18);
   color: #f0c780;
 }
+:root[data-theme=dark] .hierarchy-timeline-row-toggle-label {
+  border-color: rgba(240, 199, 128, 0.18);
+  background: rgba(184, 129, 44, 0.16);
+  color: #f0c780;
+}
 :root[data-theme=dark] .trace-detail-breadcrumb {
   color: rgba(182, 197, 219, 0.74);
 }
@@ -3644,22 +3661,6 @@ pre {
 :root[data-theme=dark] .tool-call-bubble {
   --expandable-fade-color: rgba(44, 31, 16, 0.99);
 }
-:root[data-theme=dark] .message-insight-card {
-  border-color: rgba(184, 129, 44, 0.24);
-  background: rgba(61, 45, 18, 0.8);
-}
-:root[data-theme=dark] .message-insight-card.is-highlight {
-  border-color: rgba(86, 107, 147, 0.24);
-  background: rgba(27, 38, 57, 0.82);
-}
-:root[data-theme=dark] .trace-insight-item {
-  border-color: rgba(86, 107, 147, 0.24);
-  background: rgba(27, 38, 57, 0.82);
-}
-:root[data-theme=dark] .trace-insight-item.is-structured {
-  border-color: rgba(34, 154, 161, 0.22);
-  background: rgba(14, 43, 46, 0.58);
-}
 :root[data-theme=dark] .structured-markup-pre {
   border-color: rgba(34, 154, 161, 0.22);
   background: rgba(14, 43, 46, 0.58);
@@ -3967,6 +3968,10 @@ pre {
   .session-tree-timeline-meta {
     justify-content: flex-start;
   }
+  .session-tree-timeline-toolbar {
+    flex-direction: column;
+    align-items: stretch;
+  }
   .trace-detail-secondary .hierarchy-timeline-axis,
   .trace-detail-secondary .hierarchy-timeline-row {
     grid-template-columns: minmax(0, 1fr);