@mtharrison/loupe 1.4.0 → 1.6.0

package/dist/index.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTraceEnabled = isTraceEnabled;
 exports.getLocalLLMTracer = getLocalLLMTracer;
@@ -11,6 +44,7 @@ exports.__resetLocalLLMTracerForTests = __resetLocalLLMTracerForTests;
 exports.wrapChatModel = wrapChatModel;
 exports.wrapOpenAIClient = wrapOpenAIClient;
 const node_async_hooks_1 = require("node:async_hooks");
+const childProcess = __importStar(require("node:child_process"));
 const server_1 = require("./server");
 const store_1 = require("./store");
 const ui_build_1 = require("./ui-build");
@@ -19,7 +53,10 @@ let singleton = null;
 const DEFAULT_TRACE_PORT = 4319;
 const activeSpanStorage = new node_async_hooks_1.AsyncLocalStorage();
 function isTraceEnabled() {
-    return (0, utils_1.envFlag)('LLM_TRACE_ENABLED');
+    if (process.env.LLM_TRACE_ENABLED !== undefined) {
+        return (0, utils_1.envFlag)('LLM_TRACE_ENABLED');
+    }
+    return process.env.NODE_ENV === 'development';
 }
 function getLocalLLMTracer(config = {}) {
     if (!singleton) {
@@ -28,6 +65,9 @@ function getLocalLLMTracer(config = {}) {
     else if (config && Object.keys(config).length > 0) {
         singleton.configure(config);
     }
+    if (shouldEagerStartDashboard()) {
+        void singleton.startServer();
+    }
     return singleton;
 }
 function startTraceServer(config = {}) {
@@ -180,6 +220,7 @@ function wrapOpenAIClient(client, getContext, config) {
 class LocalLLMTracerImpl {
     config;
     loggedUrl;
+    openedBrowser;
     portWasExplicit;
     server;
     serverFailed;
@@ -202,6 +243,7 @@ class LocalLLMTracerImpl {
         this.serverStartPromise = null;
         this.serverFailed = false;
         this.loggedUrl = false;
+        this.openedBrowser = false;
         this.uiWatcher = null;
     }
     configure(config = {}) {
@@ -278,6 +320,10 @@ class LocalLLMTracerImpl {
                     this.loggedUrl = true;
                     process.stdout.write(`[llm-trace] dashboard: ${this.serverInfo.url}\n`);
                 }
+                if (!this.openedBrowser && this.serverInfo && shouldAutoOpenDashboard()) {
+                    this.openedBrowser = true;
+                    openBrowser(this.serverInfo.url);
+                }
                 return this.serverInfo;
             }
             catch (error) {
@@ -292,6 +338,40 @@ class LocalLLMTracerImpl {
         return this.serverStartPromise;
     }
 }
+function shouldAutoOpenDashboard() {
+    if (process.env.LOUPE_OPEN_BROWSER === '0') {
+        return false;
+    }
+    return (process.env.NODE_ENV === 'development'
+        && !process.env.CI
+        && !!process.stdout.isTTY);
+}
+function shouldEagerStartDashboard() {
+    return process.env.NODE_ENV === 'development';
+}
+function openBrowser(url) {
+    const command = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : process.platform === 'linux'
+                ? ['xdg-open', [url]]
+                : null;
+    if (!command) {
+        return;
+    }
+    try {
+        const child = childProcess.spawn(command[0], command[1], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch (_error) {
+        // Ignore browser launch failures. The dashboard URL is already printed.
+    }
+}
 function normaliseRequest(request) {
     return {
         input: (0, utils_1.safeClone)(request?.input),

package/dist/utils.js

@@ -134,7 +134,9 @@ function normalizeTraceContext(context, mode) {
     const explicitKind = normalizeKind(raw.kind);
     let kind = explicitKind || 'actor';
     if (!explicitKind) {
-        if (guardrailType || guardrailPhase) {
+        // Keep generic guardrail metadata from masking actual delegated-agent spans.
+        // Explicit guardrail spans or spans with a concrete phase still remain guardrails.
+        if (guardrailPhase || (guardrailType && !isChildActor)) {
             kind = 'guardrail';
         }
         else if (stage) {

package/examples/fully-featured.js

@@ -0,0 +1,533 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+const readline = require('node:readline/promises');
+const process = require('node:process');
+
+const {
+  addSpanEvent,
+  endSpan,
+  getLocalLLMTracer,
+  recordException,
+  startSpan,
+  wrapChatModel,
+} = require('../dist/index.js');
+
+const DEMO_TIMEOUT_MS = 15000;
+
+const GUIDE_DATA = {
+  kyoto: {
+    coffee: ['Weekenders Coffee Tominokoji', 'Kurasu Kyoto Stand'],
+    museum: 'Kyoto National Museum',
+    neighborhood: 'Gion',
+    pack: ['layers', 'comfortable walking shoes', 'a compact umbrella'],
+    walk: 'Philosopher\'s Path and Higashiyama backstreets',
+  },
+  lisbon: {
+    coffee: ['Hello, Kristof', 'The Folks'],
+    museum: 'MAAT',
+    neighborhood: 'Baixa and Chiado',
+    pack: ['layers', 'comfortable walking shoes', 'a light rain shell'],
+    walk: 'Alfama viewpoints loop',
+  },
+};
+
+async function runFullyFeaturedExample(options = {}) {
+  process.env.LLM_TRACE_ENABLED ??= '1';
+
+  const destinationKey = normalizeDestinationKey(options.destination || 'Lisbon');
+  const guide = GUIDE_DATA[destinationKey];
+  if (!guide) {
+    throw new Error(`Unsupported destination "${String(options.destination)}". Try Lisbon or Kyoto.`);
+  }
+
+  const port = getPort(options.port);
+  const destination = formatDestination(destinationKey);
+  const sessionId = options.sessionId || `fully-featured-demo-${randomUUID().slice(0, 8)}`;
+  const keepAlive = options.keepAlive !== false;
+  const openBrowserEnabled = options.openBrowser !== false;
+  const tracer = getLocalLLMTracer({ port });
+  const serverInfo = await tracer.startServer();
+
+  if (!serverInfo?.url) {
+    throw new Error('Failed to start the Loupe dashboard.');
+  }
+
+  log(`[demo] Loupe dashboard: ${serverInfo.url}`);
+  if (openBrowserEnabled) {
+    openBrowser(serverInfo.url);
+  }
+
+  log(`[demo] Session: ${sessionId}`);
+  log(`[demo] Destination: ${destination}`);
+
+  const baseTags = {
+    destination,
+    example: 'fully-featured',
+    workflow: 'weekend-planner',
+  };
+
+  const buildContext = (overrides = {}) => {
+    const { tags = {}, ...rest } = overrides;
+    return {
+      sessionId,
+      rootSessionId: sessionId,
+      rootActorId: 'travel-assistant',
+      actorId: 'travel-assistant',
+      actorType: 'assistant',
+      model: 'trip-planner-v2',
+      provider: 'mock-llm',
+      tags: {
+        ...baseTags,
+        ...tags,
+      },
+      tenantId: 'demo-travel',
+      userId: 'traveler-01',
+      ...rest,
+    };
+  };
+
+  const researchModel = wrapChatModel(
+    {
+      async invoke(input) {
+        const requestedDestination = formatDestination(normalizeDestinationKey(input?.destination || destination));
+        const selectedGuide = GUIDE_DATA[normalizeDestinationKey(requestedDestination)] || guide;
+        return {
+          message: {
+            role: 'assistant',
+            content: [
+              `Base the trip around ${selectedGuide.neighborhood}.`,
+              `Coffee: ${selectedGuide.coffee.join(' and ')}.`,
+              `Walk: ${selectedGuide.walk}.`,
+              `Museum: ${selectedGuide.museum}.`,
+            ].join(' '),
+          },
+          tool_calls: [],
+          usage: createUsage(18, 27),
+        };
+      },
+      async *stream(input) {
+        const requestedDestination = formatDestination(normalizeDestinationKey(input?.destination || destination));
+        const selectedGuide = GUIDE_DATA[normalizeDestinationKey(requestedDestination)] || guide;
+        const content = `Research highlights for ${requestedDestination}: ${selectedGuide.walk}, ${selectedGuide.museum}.`;
+        yield { type: 'begin', role: 'assistant' };
+        yield { type: 'chunk', content };
+        yield {
+          type: 'finish',
+          message: { role: 'assistant', content },
+          tool_calls: [],
+          usage: createUsage(10, 12),
+        };
+      },
+    },
+    () =>
+      buildContext({
+        actorId: 'city-researcher',
+        actorType: 'tool',
+        model: 'city-researcher-v1',
+        tags: {
+          surface: 'research',
+        },
+      }),
+    { port },
+  );
+
+  const plannerModel = wrapChatModel(
+    {
+      async invoke(input) {
+        const researchStageId = startSpan(
+          buildContext({
+            stage: 'research',
+            tags: {
+              surface: 'research-stage',
+            },
+          }),
+          {
+            mode: 'invoke',
+            name: 'workflow.research',
+            request: {
+              input: {
+                destination: input.destination,
+                interests: input.interests,
+              },
+              options: {
+                sources: ['city-guide', 'weather-notes'],
+              },
+            },
+          },
+          { port },
+        );
+
+        addSpanEvent(
+          researchStageId,
+          {
+            name: 'retrieval.hit',
+            attributes: {
+              guide: destination,
+              sources: 2,
+            },
+            payload: {
+              guide: destination,
+              sources: ['city-guide', 'weather-notes'],
+            },
+          },
+          { port },
+        );
+
+        endSpan(
+          researchStageId,
+          {
+            summary: `Loaded local guide data for ${destination}.`,
+            usage: createUsage(6, 4, 0.0000005, 0.0000008),
+          },
+          { port },
+        );
+
+        const research = await researchModel.invoke(
+          {
+            destination: input.destination,
+            interests: input.interests,
+            messages: [
+              {
+                role: 'user',
+                content: `Research a two-day ${destination} itinerary for ${input.interests.join(', ')}.`,
+              },
+            ],
+          },
+          {
+            channel: 'research',
+          },
+        );
+
+        const availabilitySpanId = startSpan(
+          buildContext({
+            actorId: 'availability-service',
+            actorType: 'service',
+            tags: {
+              surface: 'availability',
+            },
+          }),
+          {
+            mode: 'invoke',
+            name: 'tool.availability-check',
+            request: {
+              input: {
+                destination: input.destination,
+                hotel: `${destination} Riverside House`,
+              },
+              options: {
+                timeoutMs: 250,
+              },
+            },
+          },
+          { port },
+        );
+
+        try {
+          throw Object.assign(new Error('Supplier timed out during live availability lookup.'), {
+            code: 'SUPPLIER_TIMEOUT',
+            status: 504,
+          });
+        } catch (error) {
+          // Keep the demo moving while leaving one child span in the error state.
+          recordException(availabilitySpanId, error, { port });
+        }
+
+        const outputGuardrailId = startSpan(
+          buildContext({
+            guardrailType: 'output-policy',
+            tags: {
+              surface: 'output-guardrail',
+            },
+          }),
+          {
+            mode: 'invoke',
+            name: 'guardrail.output',
+            request: {
+              input: {
+                draft: research.message.content,
+              },
+              options: {
+                policy: 'travel-safe',
+              },
+            },
+          },
+          { port },
+        );
+
+        addSpanEvent(
+          outputGuardrailId,
+          {
+            name: 'guardrail.review',
+            attributes: {
+              outcome: 'pass',
+              policy: 'travel-safe',
+            },
+            payload: {
+              removedClaims: 0,
+            },
+          },
+          { port },
+        );
+
+        endSpan(
+          outputGuardrailId,
+          {
+            reason: 'Advice stays within local-demo safety rules.',
+            result: 'pass',
+          },
+          { port },
+        );
+
+        return {
+          message: {
+            role: 'assistant',
+            content: [
+              `Day 1: start in ${guide.neighborhood} with ${guide.coffee[0]}, then walk ${guide.walk}.`,
+              `Day 2: visit ${guide.museum}, then use ${guide.coffee[1]} as a reset stop.`,
+              research.message.content,
+              'One live availability lookup failed, so confirm bookings directly before you go.',
+              `Pack ${guide.pack.join(', ')}.`,
+            ].join('\n'),
+          },
+          tool_calls: [],
+          usage: createUsage(42, 68),
+        };
+      },
+      async *stream(input) {
+        const parts = [
+          `Day 1 in ${destination}: ${guide.coffee[0]}, then ${guide.walk}. `,
+          `Day 2: ${guide.museum}, followed by time around ${guide.neighborhood}. `,
+          `Pack ${guide.pack.join(', ')}.`,
+        ];
+        const finalContent = parts.join('');
+
+        yield { type: 'begin', role: 'assistant' };
+        for (const content of parts) {
+          yield { type: 'chunk', content };
+        }
+        yield {
+          type: 'finish',
+          message: { role: 'assistant', content: finalContent },
+          tool_calls: [],
+          usage: createUsage(24, 39),
+        };
+      },
+    },
+    () =>
+      buildContext({
+        tags: {
+          surface: 'planner',
+        },
+      }),
+    { port },
+  );
+
+  const invokeInput = {
+    days: 2,
+    destination,
+    interests: ['coffee', 'walking', 'museum'],
+    messages: [
+      {
+        role: 'user',
+        content: `Plan a safe two-day ${destination} trip with coffee, walking, and one museum stop.`,
+      },
+    ],
+  };
+
+  const inputGuardrailId = startSpan(
+    buildContext({
+      guardrailType: 'input-policy',
+      tags: {
+        surface: 'input-guardrail',
+      },
+    }),
+    {
+      mode: 'invoke',
+      name: 'guardrail.input',
+      request: {
+        input: invokeInput,
+        options: {
+          policy: 'travel-safe',
+        },
+      },
+    },
+    { port },
+  );
+
+  addSpanEvent(
+    inputGuardrailId,
+    {
+      name: 'guardrail.review',
+      attributes: {
+        outcome: 'pass',
+        policy: 'travel-safe',
+      },
+      payload: {
+        matchedRules: ['safe-travel'],
+      },
+    },
+    { port },
+  );
+
+  endSpan(
+    inputGuardrailId,
+    {
+      reason: 'The prompt is safe to answer.',
+      result: 'pass',
+    },
+    { port },
+  );
+
+  const invokeResponse = await plannerModel.invoke(invokeInput, {
+    channel: 'planning',
+  });
+
+  log('');
+  log('[demo] Invoke answer:');
+  log(invokeResponse.message.content);
+
+  const streamInput = {
+    ...invokeInput,
+    messages: [
+      {
+        role: 'user',
+        content: `Now stream the concise version of the ${destination} plan.`,
+      },
+    ],
+  };
+
+  const streamChunks = [];
+  for await (const chunk of plannerModel.stream(streamInput, { channel: 'handoff' })) {
+    streamChunks.push(chunk);
+  }
+
+  const streamReply = extractStreamText(streamChunks);
+  log('');
+  log('[demo] Stream answer:');
+  log(streamReply);
+
+  const traceCount = tracer.store
+    .list()
+    .items.filter((item) => item.hierarchy.sessionId === sessionId && item.tags.example === 'fully-featured').length;
+
+  log('');
+  log(`[demo] Recorded ${traceCount} traces for one session across guardrails, nested calls, errors, and streaming.`);
+
+  if (keepAlive) {
+    log(`[demo] Keep this process alive while you inspect ${serverInfo.url}`);
+    await waitForDashboardExit(serverInfo.url);
+  }
+
+  return {
+    invokeReply: invokeResponse.message.content,
+    sessionId,
+    streamReply,
+    traceCount,
+    url: serverInfo.url,
+  };
+}
+
+function createUsage(promptTokens, completionTokens, promptPrice = 0.000001, completionPrice = 0.000002) {
+  return {
+    pricing: {
+      completion: completionPrice,
+      prompt: promptPrice,
+    },
+    tokens: {
+      completion: completionTokens,
+      prompt: promptTokens,
+    },
+  };
+}
+
+function extractStreamText(chunks) {
+  return chunks
+    .filter((chunk) => chunk?.type === 'chunk' && typeof chunk.content === 'string')
+    .map((chunk) => chunk.content)
+    .join('');
+}
+
+function normalizeDestinationKey(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase();
+}
+
+function formatDestination(value) {
+  return String(value)
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function getPort(port) {
+  const explicit = Number(port ?? process.env.LLM_TRACE_PORT);
+  return Number.isFinite(explicit) && explicit > 0 ? explicit : 4319;
+}
+
+function openBrowser(url) {
+  if (!process.stdout.isTTY || process.env.CI || process.env.LOUPE_OPEN_BROWSER === '0') {
+    return;
+  }
+
+  const command =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : process.platform === 'linux'
+          ? ['xdg-open', [url]]
+          : null;
+
+  if (!command) {
+    return;
+  }
+
+  try {
+    const child = spawn(command[0], command[1], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.on('error', () => {});
+    child.unref();
+  } catch (_error) {
+    // Ignore browser launch failures. The dashboard URL is already printed.
+  }
+}
+
+async function waitForDashboardExit(url) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    log(`[demo] Non-interactive terminal detected. Leaving the dashboard up for ${Math.round(DEMO_TIMEOUT_MS / 1000)} seconds: ${url}`);
+    await new Promise((resolve) => setTimeout(resolve, DEMO_TIMEOUT_MS));
+    return;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    await rl.question('[demo] Press Enter to stop the demo and close the dashboard.\n');
+  } finally {
+    rl.close();
+  }
+}
+
+function log(message) {
+  process.stdout.write(`${message}\n`);
+}
+
+module.exports = {
+  runFullyFeaturedExample,
+};
+
+if (require.main === module) {
+  runFullyFeaturedExample().catch((error) => {
+    process.stderr.write(`[demo] ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtharrison/loupe",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Lightweight local tracing dashboard for LLM calls",
   "author": "Matt Harrison",
   "license": "MIT",
@@ -24,13 +24,14 @@
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/build-ui.mjs",
+    "lint": "tsc --noEmit -p tsconfig.json && node --check examples/fully-featured.js && node --check examples/nested-tool-call.js && node --check examples/openai-multiturn-tools.js && node --check test/index.test.js",
     "release": "npx semantic-release",
     "test": "npm run build && node --test"
   },