@mtharrison/loupe 1.2.0 → 1.4.0

package/README.md

@@ -4,6 +4,8 @@
 
 # @mtharrison/loupe
 
+
+
 Loupe is a lightweight local tracing dashboard for LLM applications and agent systems. It captures full request and response payloads with tags and hierarchy context, then serves an inspector UI on `127.0.0.1` with no database, no containers, and no persistence.
 
 This package is for local development. Traces live in memory and are cleared on restart.
@@ -125,9 +127,28 @@ Supported demo environment variables: `OPENAI_MODEL`, `LLM_TRACE_PORT`, `LOUPE_O
 
 The script tries to open the dashboard automatically and prints the local URL either way. Set `LOUPE_OPEN_BROWSER=0` if you want to suppress the browser launch.
 
+### Runnable Nested Tool-Call Demo
+
+`examples/nested-tool-call.js` is a credential-free demo that:
+
+- starts the Loupe dashboard eagerly
+- wraps a root assistant model and a nested tool model
+- invokes the nested tool model from inside the parent model call
+- shows parent/child spans linked on the same trace
+
+Run it with:
+
+```bash
+npm install
+export LLM_TRACE_ENABLED=1
+node examples/nested-tool-call.js
+```
+
 ## Low-Level Lifecycle API
 
-If you need full control over trace boundaries, Loupe also exposes the lower-level `record*` lifecycle functions.
+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.
+
+Loupe stores GenAI span attributes using the OpenTelemetry semantic convention names where they apply, including `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.system`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.conversation.id`.
 
 Start the dashboard during app startup, then instrument a model call:
 
@@ -135,9 +156,9 @@ Start the dashboard during app startup, then instrument a model call:
 import {
   getLocalLLMTracer,
   isTraceEnabled,
-  recordError,
-  recordInvokeFinish,
-  recordInvokeStart,
+  endSpan,
+  recordException,
+  startSpan,
   type TraceContext,
 } from '@mtharrison/loupe';
 
@@ -166,51 +187,63 @@ const request = {
   options: {},
 };
 
-const traceId = recordInvokeStart(context, request);
+const spanId = startSpan(context, {
+  mode: 'invoke',
+  name: 'openai.chat.completions',
+  request,
+});
 
 try {
   const response = await model.invoke(request.input, request.options);
-  recordInvokeFinish(traceId, response);
+  endSpan(spanId, response);
   return response;
 } catch (error) {
-  recordError(traceId, error);
+  recordException(spanId, error);
   throw error;
 }
 ```
 
 ### Streaming
 
-Streaming works the same way. Loupe records each chunk event, first-chunk latency, and the reconstructed final response.
+Streaming works the same way. Loupe records each span event, first-chunk latency, and the reconstructed final response.
 
 ```ts
 import {
-  recordError,
-  recordStreamChunk,
-  recordStreamFinish,
-  recordStreamStart,
+  addSpanEvent,
+  endSpan,
+  recordException,
+  startSpan,
 } from '@mtharrison/loupe';
 
-const traceId = recordStreamStart(context, request);
+const spanId = startSpan(context, {
+  mode: 'stream',
+  name: 'openai.chat.completions',
+  request,
+});
 
 try {
   for await (const chunk of model.stream(request.input, request.options)) {
     if (chunk?.type === 'finish') {
-      recordStreamFinish(traceId, chunk);
+      endSpan(spanId, chunk);
     } else {
-      recordStreamChunk(traceId, chunk);
+      addSpanEvent(spanId, {
+        name: `stream.${chunk?.type || 'event'}`,
+        attributes: chunk,
+        payload: chunk,
+      });
     }
 
     yield chunk;
   }
 } catch (error) {
-  recordError(traceId, error);
+  recordException(spanId, error);
   throw error;
 }
 ```
 
 ## Trace Context
 
-Loupe gets its hierarchy and filters from the context you pass to `recordInvokeStart()` and `recordStreamStart()`.
+Loupe gets its hierarchy and filters from the context you pass to `startSpan()`.
 
 ### Generic context fields
 
@@ -322,7 +355,7 @@ Programmatic configuration is also available through `getLocalLLMTracer(config)`
 
 ## API
 
-Loupe exposes both low-level lifecycle functions and lightweight wrappers.
+Loupe exposes both low-level span lifecycle functions and lightweight wrappers.
 
 ### `isTraceEnabled()`
 
@@ -340,29 +373,21 @@ Returns the singleton tracer instance. This is useful if you want to:
 
 Starts the local dashboard server eagerly instead of waiting for the first trace.
 
-### `recordInvokeStart(context, request, config?)`
-
-Creates an `invoke` trace and returns a `traceId`.
-
-### `recordInvokeFinish(traceId, response, config?)`
-
-Marks an `invoke` trace as complete and stores the response payload.
-
-### `recordStreamStart(context, request, config?)`
+### `startSpan(context, options?, config?)`
 
-Creates a `stream` trace and returns a `traceId`.
+Creates a span and returns its Loupe `spanId`. Pass `mode`, `name`, and `request` in `options` to describe the operation. Nested spans are linked automatically when wrapped calls invoke other wrapped calls in the same async flow.
 
-### `recordStreamChunk(traceId, chunk, config?)`
+### `addSpanEvent(spanId, event, config?)`
 
-Appends a non-final stream chunk to an existing trace.
+Appends an event to an existing span. For streaming traces, pass the raw chunk as `event.payload` to preserve chunk reconstruction in the UI.
 
-### `recordStreamFinish(traceId, chunk, config?)`
+### `endSpan(spanId, response, config?)`
 
-Stores the final stream payload and marks the trace complete.
+Marks a span as complete and stores the final response payload.
 
-### `recordError(traceId, error, config?)`
+### `recordException(spanId, error, config?)`
 
-Marks a trace as failed and stores a serialized error payload.
+Marks a span as failed and stores a serialized exception payload.
 
 All of these functions forward to the singleton tracer returned by `getLocalLLMTracer()`.
 

package/dist/client/app.css

@@ -402,7 +402,7 @@ pre {
 .workspace-grid {
   display: grid;
   flex: 1;
-  grid-template-columns: minmax(30rem, 36rem) minmax(0, 1fr);
+  grid-template-columns: clamp(34rem, 38vw, 42rem) minmax(0, 1fr);
   gap: 0.9rem;
   align-items: stretch;
   min-height: 0;
@@ -493,7 +493,7 @@ pre {
   min-height: 0;
   flex: 1;
   overflow: auto;
-  padding-right: 0.12rem;
+  padding-right: 0.4rem;
   scrollbar-gutter: stable;
 }
 .session-sidebar-empty {
@@ -1189,7 +1189,12 @@ pre {
   --timeline-indent: 1rem;
   --timeline-gutter-base: 1.25rem;
   --timeline-connector-base: 0.22rem;
+  --timeline-row-padding-x: 0.55rem;
+  --timeline-card-radius: 12px;
+  --timeline-card-inset-y: 0.14rem;
   --timeline-gutter-width: calc( var(--timeline-depth, 0) * var(--timeline-indent) + var(--timeline-gutter-base) );
+  --timeline-card-left: calc( var(--timeline-row-padding-x) + var(--timeline-time-column) + var(--timeline-column-gap) + var(--timeline-gutter-width) );
+  --timeline-card-right: var(--timeline-row-padding-x);
   --timeline-row-color: rgba(92, 121, 171, 0.9);
   --timeline-bar-stroke: color-mix(in srgb, var(--timeline-row-color) 74%, white);
   --timeline-connector-color: color-mix( in srgb, var(--timeline-row-color) 28%, rgba(84, 100, 125, 0.18) );
@@ -1201,7 +1206,7 @@ pre {
   width: 100%;
   border: 0;
   background: transparent;
-  padding: 0.12rem 0.55rem;
+  padding: 0.12rem var(--timeline-row-padding-x);
   color: inherit;
   cursor: default;
   font: inherit;
@@ -1213,11 +1218,11 @@ pre {
 .hierarchy-timeline-row::before {
   content: "";
   position: absolute;
-  top: 0.14rem;
-  right: 0.55rem;
-  bottom: 0.14rem;
-  left: calc(0.55rem + var(--timeline-time-column) + var(--timeline-column-gap) + var(--timeline-gutter-width));
-  border-radius: 12px;
+  top: var(--timeline-card-inset-y);
+  right: var(--timeline-card-right);
+  bottom: var(--timeline-card-inset-y);
+  left: var(--timeline-card-left);
+  border-radius: var(--timeline-card-radius);
   border: 1px solid transparent;
   background: rgba(255, 255, 255, 0.42);
   box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.6), 0 4px 12px rgba(32, 50, 76, 0.03);
@@ -1248,8 +1253,18 @@ pre {
   box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.6), 0 4px 12px rgba(32, 50, 76, 0.02);
 }
 .hierarchy-timeline-row:focus-visible {
-  outline: 2px solid rgba(40, 93, 168, 0.22);
-  outline-offset: 2px;
+  outline: none;
+}
+.hierarchy-timeline-row:focus-visible::after {
+  content: "";
+  position: absolute;
+  top: calc(var(--timeline-card-inset-y) - 0.08rem);
+  right: calc(var(--timeline-card-right) - 0.08rem);
+  bottom: calc(var(--timeline-card-inset-y) - 0.08rem);
+  left: calc(var(--timeline-card-left) - 0.08rem);
+  border-radius: calc(var(--timeline-card-radius) + 2px);
+  box-shadow: 0 0 0 2px rgba(40, 93, 168, 0.18);
+  pointer-events: none;
 }
 .hierarchy-timeline-row.is-in-path::before {
   background: rgba(240, 246, 255, 0.54);
@@ -1900,27 +1915,67 @@ pre {
   flex-wrap: wrap;
 }
 .session-tree-timeline-shell {
-  padding: 0 0.1rem 0.2rem 2.35rem;
+  padding: 0.08rem 0.1rem 0.24rem 0.5rem;
 }
 .session-tree-timeline-list {
   display: flex;
   flex-direction: column;
-  gap: 0.45rem;
+  gap: 0;
 }
 .session-tree-timeline-list .hierarchy-timeline-row {
-  grid-template-columns: 4rem minmax(0, 1fr) minmax(6rem, 7.25rem);
-  gap: 0.4rem;
+  --timeline-time-column: 4.8rem;
+  --timeline-column-gap: 0.4rem;
+  --timeline-indent: 0.72rem;
+  --timeline-gutter-base: 0.75rem;
+  --embedded-bars-space: clamp(10.75rem, 49%, 15.6rem);
+  --timeline-row-padding-x: 0.18rem;
+  --timeline-card-radius: 18px;
+  --timeline-card-inset-y: 0.24rem;
+  --timeline-card-left: calc( var(--timeline-row-padding-x) + var(--timeline-time-column) + var(--timeline-column-gap) + var(--timeline-gutter-width) - 0.12rem );
+  --timeline-card-right: 0.1rem;
+  display: flex;
+  gap: var(--timeline-column-gap);
+  align-items: stretch;
+  max-width: 100%;
+  overflow: visible;
+}
+.session-tree-timeline-list .hierarchy-timeline-row-time {
+  flex: 0 0 var(--timeline-time-column);
+  justify-content: flex-start;
+  text-align: left;
+  padding-right: 0;
+  padding-left: 0.08rem;
+  overflow: visible;
+  font-size: 0.74rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-row-branch {
+  flex: 1 1 0;
+  min-width: 0;
 }
 .session-tree-timeline-list .hierarchy-timeline-row-labels {
-  padding: 0.72rem 0.5rem 0.72rem 1.05rem;
+  min-width: 0;
+  gap: 0.24rem;
+  padding: 0.84rem calc(var(--embedded-bars-space) + 0.8rem) 0.84rem 0.92rem;
 }
 .session-tree-timeline-list .hierarchy-timeline-row-bars {
-  grid-template-columns: minmax(4.8rem, 1fr) auto;
-  column-gap: 0.35rem;
-  padding: 0.72rem 0.8rem 0.72rem 0.2rem;
+  position: absolute;
+  top: 0.84rem;
+  right: 0.92rem;
+  width: var(--embedded-bars-space);
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 0.36rem;
+  padding: 0;
+  overflow: hidden;
+  z-index: 2;
 }
 .session-tree-timeline-list .hierarchy-timeline-row-title {
-  flex-wrap: nowrap;
+  position: relative;
+  display: block;
+  min-height: 0;
+  padding-top: 2.05rem;
 }
 .session-tree-timeline-list .hierarchy-timeline-row-title-text,
 .session-tree-timeline-list .hierarchy-timeline-row-meta {
@@ -1929,13 +1984,53 @@ pre {
   white-space: nowrap;
 }
 .session-tree-timeline-list .hierarchy-timeline-row-title-text {
-  font-size: 0.84rem;
+  display: block;
+  font-size: 0.86rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-pill {
+  position: absolute;
+  top: 0;
+  left: 0;
+}
+.session-tree-timeline-list .hierarchy-timeline-row-flag {
+  margin-top: 0.35rem;
+  margin-right: 0.35rem;
 }
 .session-tree-timeline-list .hierarchy-timeline-row-meta,
 .session-tree-timeline-list .hierarchy-timeline-row-time,
 .session-tree-timeline-list .hierarchy-timeline-row-duration {
   font-size: 0.72rem;
 }
+.session-tree-timeline-list .hierarchy-timeline-row-track {
+  flex: 1 1 auto;
+  min-width: 0;
+  height: 1.3rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-row-track::before {
+  height: 0.4rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-row-bar {
+  width: max(0.65rem, calc(var(--timeline-span, 0.1) * 100%));
+  height: 0.65rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-row-bar::before,
+.session-tree-timeline-list .hierarchy-timeline-row-bar::after {
+  height: 0.9rem;
+}
+.session-tree-timeline-list .hierarchy-timeline-row-duration {
+  flex: 0 0 auto;
+}
+.session-tree-timeline-list .hierarchy-timeline-row.is-active::before {
+  border-color: rgba(40, 93, 168, 0.16);
+  background: rgba(236, 244, 255, 0.9);
+  box-shadow: inset 2px 0 0 rgba(40, 93, 168, 0.54), 0 8px 20px rgba(32, 50, 76, 0.06);
+}
+.session-tree-timeline-list .hierarchy-timeline-row.is-detail-trace:not(.is-active)::before {
+  box-shadow: inset 2px 0 0 rgba(40, 93, 168, 0.42), 0 6px 18px rgba(32, 50, 76, 0.05);
+}
+.session-tree-timeline-list .hierarchy-timeline-row:focus-visible::after {
+  box-shadow: 0 0 0 2px rgba(40, 93, 168, 0.14);
+}
 .session-tree-timeline {
   display: inline-flex;
   min-width: 0;