te.js 2.2.1 → 2.3.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://tejas-documentation.vercel.app/tejas-logo.svg" alt="Tejas Logo" width="200">
+  <img src="https://usetejas.com/tejas-logo.svg" alt="Tejas Logo" width="200">
 </p>
 
 <h1 align="center">Tejas</h1>
@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <a href="https://tejas-documentation.vercel.app">Documentation</a> •
+  <a href="https://usetejas.com">Documentation</a> •
   <a href="#ai-assisted-setup-mcp">AI Setup (MCP)</a> •
   <a href="#quick-start">Quick Start</a> •
   <a href="#features">Features</a> •
@@ -163,7 +163,7 @@ app.takeoff();
 
 ## Documentation
 
-For comprehensive documentation, see the [docs folder](./docs) or visit [tejas-documentation.vercel.app](https://tejas-documentation.vercel.app).
+For comprehensive documentation, see the [docs folder](./docs) or visit [tejas-documentation.vercel.app](https://usetejas.com).
 
 - [Getting Started](./docs/getting-started.md) — Installation and quick start
 - [Configuration](./docs/configuration.md) — All configuration options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "te.js",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "AI Native Node.js Framework",
   "type": "module",
   "main": "te.js",

package/radar/index.js

@@ -7,6 +7,8 @@ import { promisify } from 'node:util';
 const gzipAsync = promisify(gzip);
 import { AsyncLocalStorage } from 'node:async_hooks';
 import TejLogger from 'tej-logger';
+import { getErrorsLlmConfig } from '../utils/errors-llm-config.js';
+import { createSpanContext, buildSpanEvent } from './spans.js';
 
 const logger = new TejLogger('Tejas.Radar');
 
@@ -95,6 +97,22 @@ function parseJsonSafe(raw) {
   }
 }
 
+const MAX_JSON_BLOB = 8 * 1024;
+
+/**
+ * Return `value` if its JSON-serialised size fits within the collector's
+ * per-field blob limit, otherwise `null`.  Prevents oversized request/response
+ * bodies from causing 422 rejections that drop the entire batch.
+ */
+function capJsonBlob(value) {
+  if (value == null) return null;
+  try {
+    return JSON.stringify(value).length <= MAX_JSON_BLOB ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Factory that returns a te.js-compatible `(ammo, next)` middleware which
  * captures HTTP request metrics and forwards them to the Tejas Radar collector.
@@ -108,12 +126,18 @@ function parseJsonSafe(raw) {
  * @param {Function} [config.transport]      Custom transport `(events) => Promise<{ok, status}>`.
  *                                            Defaults to gzip-compressed HTTP POST to the collector.
  * @param {string[]} [config.ignore]         Request paths to skip (default ['/health']).
+ * @param {string} [config.collectorUrl]     Radar collector URL. Falls back to RADAR_COLLECTOR_URL env, then "https://collector.usetejas.com".
+ *                                            A future release will support self-hosted Radar collectors.
  * @param {Object}  [config.capture]         Controls what additional data is captured beyond metrics.
  * @param {boolean} [config.capture.request]          Capture and send request body (default false).
  * @param {boolean} [config.capture.response]         Capture and send response body (default false).
  * @param {boolean|string[]} [config.capture.headers] Capture request headers. `true` sends all headers;
  *                                                     a `string[]` sends only the named headers (allowlist);
  *                                                     `false` (default) sends nothing.
+ * @param {boolean} [config.capture.logs=false]        Forward TejLogger calls to the collector as app-level
+ *                                                     log events. Off by default.
+ * @param {string[]} [config.capture.logLevels]        When `capture.logs` is true, only forward these levels
+ *                                                     (e.g. `['warn', 'error']`). Defaults to all levels.
  * @param {Object}   [config.mask]           Client-side masking applied before data is sent.
  * @param {string[]} [config.mask.fields]    Extra field names to mask in request/response bodies.
  *                                            These are merged with the collector's server-side GDPR blocklist.
@@ -122,11 +146,10 @@ function parseJsonSafe(raw) {
  * @returns {Promise<Function>} Middleware function `(ammo, next)`
  */
 async function radarMiddleware(config = {}) {
-  // RADAR_COLLECTOR_URL is an undocumented internal escape hatch used only
-  // during local development. In production, telemetry always goes to the
-  // hosted collector and this env var should not be set.
   const collectorUrl =
-    process.env.RADAR_COLLECTOR_URL ?? 'http://localhost:3100';
+    config.collectorUrl ??
+    process.env.RADAR_COLLECTOR_URL ??
+    'https://collector.usetejas.com';
 
   const apiKey = config.apiKey ?? process.env.RADAR_API_KEY ?? null;
 
@@ -145,6 +168,8 @@ async function radarMiddleware(config = {}) {
     request: config.capture?.request === true,
     response: config.capture?.response === true,
     headers: config.capture?.headers ?? false,
+    logs: config.capture?.logs === true,
+    logLevels: config.capture?.logLevels ?? null,
   });
 
   // Build the client-side field blocklist from developer-supplied extra fields.
@@ -275,9 +300,40 @@ async function radarMiddleware(config = {}) {
   const timer = setInterval(flush, flushInterval);
   if (timer.unref) timer.unref();
 
+  const captureLevels = capture.logLevels ? new Set(capture.logLevels) : null;
+
+  if (capture.logs) {
+    TejLogger.addHook(({ level, identifier, message, metadata }) => {
+      if (captureLevels && !captureLevels.has(level)) return;
+
+      const store = traceStore.getStore();
+      const traceId = store?.traceId ?? null;
+
+      const metaJson =
+        metadata != null
+          ? JSON.stringify(metadata).slice(0, MAX_JSON_BLOB)
+          : null;
+
+      const event = {
+        type: 'app_log',
+        projectName,
+        level,
+        message: `[${identifier}] ${String(message).slice(0, 4096)}`,
+        traceId,
+        timestamp: Date.now(),
+        metadata: metaJson,
+      };
+
+      if (batch.length >= maxQueueSize) batch.splice(0, 1);
+      batch.push(event);
+      if (batch.length >= batchSize) flush();
+    });
+  }
+
   function radarCapture(ammo, next) {
     const startTime = Date.now();
     const traceId = randomUUID().replace(/-/g, '');
+    const spanCtx = createSpanContext(traceId);
 
     ammo.res.on('finish', () => {
       const path = ammo.endpoint ?? ammo.path ?? '/';
@@ -294,12 +350,14 @@ async function radarMiddleware(config = {}) {
       const responseSize = Buffer.byteLength(ammo.dispatchedData ?? '', 'utf8');
       const ip = ammo.ip ?? null;
       const userAgent = ammo.headers?.['user-agent'] ?? null;
-      const headers = buildHeaders(ammo.headers, capture.headers);
+      const headers = capJsonBlob(buildHeaders(ammo.headers, capture.headers));
       const requestBody = capture.request
-        ? deepMask(ammo.payload ?? null, clientMaskBlocklist)
+        ? capJsonBlob(deepMask(ammo.payload ?? null, clientMaskBlocklist))
         : null;
       const responseBody = capture.response
-        ? deepMask(parseJsonSafe(ammo.dispatchedData), clientMaskBlocklist)
+        ? capJsonBlob(
+            deepMask(parseJsonSafe(ammo.dispatchedData), clientMaskBlocklist),
+          )
         : null;
 
       function pushEvents() {
@@ -311,10 +369,26 @@ async function radarMiddleware(config = {}) {
             message: errorInfo.message ?? null,
             type: errorInfo.type ?? null,
             devInsight: errorInfo.devInsight ?? null,
+            llmEnabled: getErrorsLlmConfig().enabled,
           });
         }
 
-        const incoming = status >= 400 ? 2 : 1;
+        // Finalize root span — added last so middleware spans already
+        // reference rootSpanId as their parentId.
+        spanCtx.addSpan(
+          `${ammo.method} ${path}`,
+          'handler',
+          null,
+          startTime,
+          duration,
+          status,
+        );
+
+        const spanEvents = spanCtx.spans.map((s) =>
+          buildSpanEvent(projectName, spanCtx, s),
+        );
+
+        const incoming = (status >= 400 ? 2 : 1) + spanEvents.length;
         if (batch.length + incoming > maxQueueSize) {
           const overflow = batch.length + incoming - maxQueueSize;
           batch.splice(0, overflow);
@@ -356,6 +430,10 @@ async function radarMiddleware(config = {}) {
           });
         }
 
+        for (const spanEvent of spanEvents) {
+          batch.push(spanEvent);
+        }
+
         if (batch.length >= batchSize) flush();
       }
 
@@ -372,7 +450,7 @@ async function radarMiddleware(config = {}) {
       }
     });
 
-    traceStore.run({ traceId }, () => next());
+    traceStore.run({ traceId, spanCtx }, () => next());
   }
 
   radarCapture._radarStatus = radarStatus;

package/radar/spans.js

@@ -0,0 +1,104 @@
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Generate a 16-character hex span ID (matches OpenTelemetry span ID length).
+ *
+ * @returns {string} 16-char lowercase hex string.
+ */
+export function createSpanId() {
+  return randomBytes(8).toString('hex');
+}
+
+/**
+ * @typedef {Object} CollectedSpan
+ * @property {string}        spanId     Unique span identifier.
+ * @property {string}        name       Human-readable span name (e.g. "middleware:auth").
+ * @property {string}        type       Span type: "middleware", "handler", or "other".
+ * @property {string|null}   parentId   Parent span ID, or null for root spans.
+ * @property {number}        startMs    Unix epoch milliseconds when the span started.
+ * @property {number}        durationMs Span duration in milliseconds.
+ * @property {number}        status     HTTP status code (or 0 if unavailable).
+ * @property {Object|null}   metadata   Optional key-value metadata.
+ */
+
+/**
+ * @typedef {Object} SpanContext
+ * @property {string}           traceId     Trace identifier (shared across all spans in a request).
+ * @property {string}           rootSpanId  Span ID of the root span (the request itself).
+ * @property {CollectedSpan[]}  spans       Accumulated spans for this request.
+ * @property {function(string, string, string|null, number, number, number, Object=): void} addSpan
+ */
+
+/**
+ * Create a span collection context to be stored in AsyncLocalStorage alongside
+ * the traceId.  Middleware and handler instrumentation pushes spans here; the
+ * radar middleware reads them at response finish time.
+ *
+ * @param {string} traceId  The trace identifier for this request.
+ * @returns {SpanContext}
+ */
+export function createSpanContext(traceId) {
+  const rootSpanId = createSpanId();
+
+  /** @type {CollectedSpan[]} */
+  const spans = [];
+
+  /**
+   * Record a completed span.
+   *
+   * @param {string}      name       Human-readable span name.
+   * @param {string}      type       Span type ("middleware", "handler", "other").
+   * @param {string|null} parentId   Parent span ID, or null for root.
+   * @param {number}      startMs    Start time (Unix epoch ms).
+   * @param {number}      durationMs Duration in milliseconds.
+   * @param {number}      status     HTTP status code.
+   * @param {Object}      [metadata] Optional metadata object.
+   */
+  function addSpan(
+    name,
+    type,
+    parentId,
+    startMs,
+    durationMs,
+    status,
+    metadata,
+  ) {
+    spans.push({
+      spanId: createSpanId(),
+      name,
+      type,
+      parentId: parentId ?? null,
+      startMs,
+      durationMs,
+      status,
+      metadata: metadata ?? null,
+    });
+  }
+
+  return { traceId, rootSpanId, spans, addSpan };
+}
+
+/**
+ * Convert a collected span into the event shape expected by the Radar
+ * collector's `SpanEvent` (Rust serde struct).
+ *
+ * @param {string}        projectName  Project identifier sent with every event.
+ * @param {SpanContext}    ctx          The span context holding the traceId.
+ * @param {CollectedSpan}  span        The span to convert.
+ * @returns {Object} Collector-compatible span event object.
+ */
+export function buildSpanEvent(projectName, ctx, span) {
+  return {
+    type: 'span',
+    projectName,
+    traceId: ctx.traceId,
+    spanId: span.spanId,
+    parentId: span.parentId,
+    name: span.name,
+    spanType: span.type,
+    startMs: span.startMs,
+    duration_ms: span.durationMs,
+    status: span.status,
+    metadata: span.metadata,
+  };
+}

package/radar/spans.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { createSpanId, createSpanContext, buildSpanEvent } from './spans.js';
+
+describe('createSpanId', () => {
+  it('should return a 16-character hex string', () => {
+    const id = createSpanId();
+    expect(typeof id).toBe('string');
+    expect(id).toHaveLength(16);
+    expect(id).toMatch(/^[0-9a-f]{16}$/);
+  });
+
+  it('should produce unique IDs', () => {
+    const ids = new Set(Array.from({ length: 100 }, () => createSpanId()));
+    expect(ids.size).toBe(100);
+  });
+});
+
+describe('createSpanContext', () => {
+  it('should create a context with traceId and rootSpanId', () => {
+    const ctx = createSpanContext('abc123');
+    expect(ctx.traceId).toBe('abc123');
+    expect(typeof ctx.rootSpanId).toBe('string');
+    expect(ctx.rootSpanId).toHaveLength(16);
+    expect(ctx.spans).toEqual([]);
+  });
+
+  it('should accumulate spans via addSpan', () => {
+    const ctx = createSpanContext('trace1');
+    ctx.addSpan('middleware:auth', 'middleware', ctx.rootSpanId, 1000, 5, 200);
+    ctx.addSpan('handler:GET /users', 'handler', ctx.rootSpanId, 1005, 20, 200);
+
+    expect(ctx.spans).toHaveLength(2);
+    expect(ctx.spans[0].name).toBe('middleware:auth');
+    expect(ctx.spans[0].type).toBe('middleware');
+    expect(ctx.spans[0].parentId).toBe(ctx.rootSpanId);
+    expect(ctx.spans[0].startMs).toBe(1000);
+    expect(ctx.spans[0].durationMs).toBe(5);
+    expect(ctx.spans[0].status).toBe(200);
+    expect(ctx.spans[0].metadata).toBeNull();
+  });
+
+  it('should assign unique spanIds to each span', () => {
+    const ctx = createSpanContext('trace2');
+    ctx.addSpan('a', 'middleware', null, 0, 1, 200);
+    ctx.addSpan('b', 'middleware', null, 1, 1, 200);
+    expect(ctx.spans[0].spanId).not.toBe(ctx.spans[1].spanId);
+  });
+
+  it('should accept optional metadata', () => {
+    const ctx = createSpanContext('trace3');
+    ctx.addSpan('db:query', 'other', null, 0, 10, 200, { query: 'SELECT 1' });
+    expect(ctx.spans[0].metadata).toEqual({ query: 'SELECT 1' });
+  });
+
+  it('should default parentId to null when not provided', () => {
+    const ctx = createSpanContext('trace4');
+    ctx.addSpan('root', 'handler', null, 0, 100, 200);
+    expect(ctx.spans[0].parentId).toBeNull();
+  });
+});
+
+describe('buildSpanEvent', () => {
+  it('should produce a collector-compatible event object', () => {
+    const ctx = createSpanContext('trace-build');
+    ctx.addSpan('middleware:cors', 'middleware', ctx.rootSpanId, 5000, 2, 200);
+    const span = ctx.spans[0];
+
+    const event = buildSpanEvent('my-api', ctx, span);
+
+    expect(event.type).toBe('span');
+    expect(event.projectName).toBe('my-api');
+    expect(event.traceId).toBe('trace-build');
+    expect(event.spanId).toBe(span.spanId);
+    expect(event.parentId).toBe(ctx.rootSpanId);
+    expect(event.name).toBe('middleware:cors');
+    expect(event.spanType).toBe('middleware');
+    expect(event.startMs).toBe(5000);
+    expect(event.duration_ms).toBe(2);
+    expect(event.status).toBe(200);
+    expect(event.metadata).toBeNull();
+  });
+
+  it('should include metadata when present', () => {
+    const ctx = createSpanContext('trace-meta');
+    ctx.addSpan('db', 'other', null, 0, 10, 200, { table: 'users' });
+    const event = buildSpanEvent('app', ctx, ctx.spans[0]);
+    expect(event.metadata).toEqual({ table: 'users' });
+  });
+});

package/server/ammo.js

@@ -34,6 +34,112 @@ function isThrowOptions(v) {
   return hasUseLlm || hasMessageType === true;
 }
 
+/**
+ * Synchronously resolve throw() arguments into a status code, message, error
+ * metadata, and an `explicit` flag that tells the LLM whether it may override
+ * the resolved code/message.
+ *
+ * @param {unknown[]} args  The throw() arguments (after throwOpts have been popped)
+ * @returns {{ statusCode: number, message: string, errorType: string|null, stack: string|null, originalError: unknown, explicit: boolean }}
+ */
+function resolveThrowArgs(args) {
+  if (args.length === 0) {
+    return {
+      statusCode: 500,
+      message: 'Internal Server Error',
+      errorType: null,
+      stack: null,
+      originalError: undefined,
+      explicit: true,
+    };
+  }
+
+  if (isStatusCode(args[0])) {
+    return {
+      statusCode: args[0],
+      message: args[1] || toStatusMessage(args[0]),
+      errorType: null,
+      stack: null,
+      originalError: undefined,
+      explicit: true,
+    };
+  }
+
+  if (
+    typeof args[0]?.statusCode === 'number' &&
+    typeof args[0]?.code === 'string'
+  ) {
+    const err = args[0];
+    return {
+      statusCode: err.statusCode,
+      message: err.message,
+      errorType: err.constructor?.name ?? 'TejError',
+      stack: err.stack ?? null,
+      originalError: err,
+      explicit: true,
+    };
+  }
+
+  if (
+    args[0] != null &&
+    typeof args[0].message === 'string' &&
+    typeof args[0].stack === 'string'
+  ) {
+    const err = args[0];
+    if (!isNaN(parseInt(err.message))) {
+      const code = parseInt(err.message);
+      return {
+        statusCode: code,
+        message: toStatusMessage(code) || toStatusMessage(500),
+        errorType: err.constructor.name,
+        stack: err.stack,
+        originalError: err,
+        explicit: false,
+      };
+    }
+    const code = toStatusCode(err.message);
+    if (code) {
+      return {
+        statusCode: code,
+        message: err.message,
+        errorType: err.constructor.name,
+        stack: err.stack,
+        originalError: err,
+        explicit: false,
+      };
+    }
+    return {
+      statusCode: 500,
+      message: err.message,
+      errorType: err.constructor.name,
+      stack: err.stack,
+      originalError: err,
+      explicit: false,
+    };
+  }
+
+  const val = args[0];
+  const code = toStatusCode(val);
+  if (code) {
+    return {
+      statusCode: code,
+      message: toStatusMessage(code),
+      errorType: null,
+      stack: null,
+      originalError: undefined,
+      explicit: true,
+    };
+  }
+  return {
+    statusCode: 500,
+    message: val.toString(),
+    errorType: null,
+    stack: null,
+    originalError: undefined,
+    explicit: true,
+  };
+}
+
 /**
  * Ammo class for handling HTTP requests and responses.
  *
@@ -339,25 +445,28 @@ class Ammo {
    * 4. Error object: Extracts status code and message from the error
    * 5. String: Treats as error message with 500 status code
    *
-   * When errors.llm.enabled is true and no explicit code/message is given (no args,
-   * Error, or string/other), an LLM infers statusCode and message from context.
-   * In that case throw() returns a Promise; otherwise it returns undefined.
+   * When errors.llm is enabled (via `withLLMErrors()`), every throw() call is
+   * enriched by the LLM with a `devInsight` field for Radar.  Explicit status
+   * codes and messages are always preserved — the LLM only adds diagnostic
+   * context, never overrides the developer's chosen code/message.  For bare
+   * Error objects the LLM may also infer a more appropriate status code and
+   * message.  When the LLM path is active, throw() returns a Promise.
    *
-   * Per-call options (last argument, only when no explicit status code): pass an object
-   * with `useLlm` (boolean) and/or `messageType` ('endUser' | 'developer'). Use
-   * `useLlm: false` to skip the LLM for this call; use `messageType` to override
-   * errors.llm.messageType for this call (end-user-friendly vs developer-friendly message).
+   * Per-call options (last argument): pass an object with `useLlm` (boolean)
+   * and/or `messageType` ('endUser' | 'developer').  Use `useLlm: false` to
+   * skip the LLM for this specific call; use `messageType` to override
+   * errors.llm.messageType for this call.
    *
    * @example
    * // Throw a 404 Not Found error
    * ammo.throw(404);
    *
    * @example
-   * // Throw a 404 Not Found error with custom message
+   * // Throw a 404 with custom message — LLM adds devInsight only
    * ammo.throw(404, 'Resource not found');
    *
    * @example
-   * // Throw an error from an Error object
+   * // Error object — LLM infers code + message + devInsight
    * ammo.throw(new Error('Something went wrong'));
    *
    * @example
@@ -365,8 +474,8 @@ class Ammo {
    * ammo.throw('Something went wrong');
    *
    * @example
-   * // Skip LLM for this call; use default 500
-   * ammo.throw(err, { useLlm: false });
+   * // Skip LLM for this specific call
+   * ammo.throw(502, 'Known upstream issue', { useLlm: false });
    *
    * @example
    * // Force developer-friendly message for this call
@@ -378,129 +487,65 @@ class Ammo {
     let args = Array.from(arguments);
     const { enabled: llmEnabled } = getErrorsLlmConfig();
 
-    // Per-call options: last arg can be { useLlm?, messageType? } when call is LLM-eligible (no explicit code).
-    const llmEligible =
-      args.length === 0 ||
-      (!isStatusCode(args[0]) &&
-        !(
-          typeof args[0]?.statusCode === 'number' &&
-          typeof args[0]?.code === 'string'
-        ));
+    // Per-call options: last arg can be { useLlm?, messageType? }.
     let throwOpts =
       /** @type {{ useLlm?: boolean, messageType?: 'endUser'|'developer' } | null} */ (
         null
       );
-    if (
-      llmEligible &&
-      args.length > 0 &&
-      isThrowOptions(args[args.length - 1])
-    ) {
+    if (args.length > 0 && isThrowOptions(args[args.length - 1])) {
       throwOpts =
         /** @type {{ useLlm?: boolean, messageType?: 'endUser'|'developer' } } */ (
           args.pop()
         );
     }
 
-    const useLlm = llmEnabled && llmEligible && throwOpts?.useLlm !== false;
-
-    if (useLlm) {
-      // Capture the stack string SYNCHRONOUSLY before any async work or fire() call,
-      // because the call stack unwinds as soon as we await or respond.
-      const stack =
-        args[0] != null && typeof args[0].stack === 'string'
-          ? args[0].stack
-          : new Error().stack;
-      const originalError =
-        args[0] !== undefined && args[0] !== null ? args[0] : undefined;
-
-      const { mode, channel, logFile } = getErrorsLlmConfig();
-
-      if (mode === 'async') {
-        // Respond immediately with a generic 500, then run LLM in the background.
-        this.fire(500, 'Internal Server Error');
-
-        // Stash basic error info synchronously so radar can read it on res.finish
-        // even before LLM completes. LLM result will update _errorInfo when ready.
-        const errorType =
-          originalError != null &&
-          typeof originalError.constructor?.name === 'string'
-            ? originalError.constructor.name
-            : originalError !== undefined
-              ? typeof originalError
-              : null;
-        this._errorInfo = {
-          message: 'Internal Server Error',
-          type: errorType,
-          devInsight: null,
-          stack: stack ?? null,
-          codeContext: null,
-        };
+    // ── Phase 1: resolve statusCode, message, metadata from args ──────
+    const resolved = resolveThrowArgs(args);
+    const { statusCode, message, errorType, originalError } = resolved;
+    // For LLM code-context capture we always need a stack trace, even when
+    // the developer passed a bare status code like throw(502).
+    const stack = resolved.stack ?? new Error().stack;
 
-        // Run LLM in the background; expose the promise so the Radar middleware
-        // can await it before flushing events (ensures LLM data is captured).
-        const method = this.method;
-        const path = this.path;
-        const self = this;
-        this._llmPromise = captureCodeContext(stack)
-          .then((codeContext) => {
-            // Update _errorInfo with captured code context
-            if (self._errorInfo) self._errorInfo.codeContext = codeContext;
-            const context = {
-              codeContext,
-              method,
-              path,
-              // Always request devInsight in async mode — it goes to the channel, not the HTTP response.
-              includeDevInsight: true,
-              forceDevInsight: true,
-              ...(throwOpts?.messageType && {
-                messageType: throwOpts.messageType,
-              }),
-            };
-            if (originalError !== undefined) context.error = originalError;
-            return inferErrorFromContext(context).then((result) => ({
-              result,
-              codeContext,
-            }));
-          })
-          .then(({ result, codeContext }) => {
-            // Update _errorInfo with full LLM result
-            if (self._errorInfo) {
-              self._errorInfo.message = result.message;
-              self._errorInfo.devInsight = result.devInsight ?? null;
-            }
-            const channels = getChannels(channel, logFile);
-            const payload = buildPayload({
-              method,
-              path,
-              originalError,
-              codeContext,
-              statusCode: result.statusCode,
-              message: result.message,
-              devInsight: result.devInsight,
-              cached: result.cached,
-              rateLimited: result.rateLimited,
-            });
-            return dispatchToChannels(channels, payload);
-          })
-          .catch((err) => {
-            // Background LLM failed after HTTP response already sent — log the failure
-            // but do not attempt to respond again.
-            logger.warn(
-              `Background LLM dispatch failed: ${err?.message ?? err}`,
-            );
-          });
+    // ── Phase 2: decide fire strategy ─────────────────────────────────
+    const useLlm = llmEnabled && throwOpts?.useLlm !== false;
+
+    if (!useLlm) {
+      this._errorInfo = {
+        message,
+        type: errorType,
+        devInsight: null,
+        stack: resolved.stack,
+        codeContext: null,
+      };
+      this.fire(statusCode, message);
+      return;
+    }
+
+    const { mode, channel, logFile } = getErrorsLlmConfig();
 
-        return;
-      }
+    if (mode === 'async') {
+      // Fire immediately with the resolved code/message.
+      this.fire(statusCode, message);
+      this._errorInfo = {
+        message,
+        type: errorType,
+        devInsight: null,
+        stack: stack ?? null,
+        codeContext: null,
+      };
 
-      // Sync mode (default): block until LLM responds, then fire.
-      return captureCodeContext(stack)
+      const method = this.method;
+      const path = this.path;
+      const self = this;
+      this._llmPromise = captureCodeContext(stack)
         .then((codeContext) => {
+          if (self._errorInfo) self._errorInfo.codeContext = codeContext;
           const context = {
             codeContext,
-            method: this.method,
-            path: this.path,
+            method,
+            path,
             includeDevInsight: true,
+            forceDevInsight: true,
             ...(throwOpts?.messageType && {
               messageType: throwOpts.messageType,
             }),
@@ -512,142 +557,76 @@ class Ammo {
           }));
         })
         .then(({ result, codeContext }) => {
-          const { statusCode, message, devInsight } = result;
-          const errorType =
-            originalError != null &&
-            typeof originalError.constructor?.name === 'string'
-              ? originalError.constructor.name
-              : originalError !== undefined
-                ? typeof originalError
-                : null;
-          this._errorInfo = {
-            message,
-            type: errorType,
-            devInsight: devInsight ?? null,
-            stack: stack ?? null,
-            codeContext: codeContext ?? null,
-          };
-          const isProduction = process.env.NODE_ENV === 'production';
-          const data =
-            !isProduction && devInsight
-              ? { message, _dev: devInsight }
-              : message;
-          this.fire(statusCode, data);
+          if (self._errorInfo) {
+            if (!resolved.explicit) self._errorInfo.message = result.message;
+            self._errorInfo.devInsight = result.devInsight ?? null;
+          }
+          const channels = getChannels(channel, logFile);
+          const payload = buildPayload({
+            method,
+            path,
+            originalError,
+            codeContext,
+            statusCode: resolved.explicit ? statusCode : result.statusCode,
+            message: resolved.explicit ? message : result.message,
+            devInsight: result.devInsight,
+            cached: result.cached,
+            rateLimited: result.rateLimited,
+          });
+          return dispatchToChannels(channels, payload);
         })
         .catch((err) => {
-          // LLM call failed (network error, timeout, etc.) — fall back to generic 500
-          // so the client always gets a response and we don't trigger an infinite retry loop.
-          logger.warn(`LLM error inference failed: ${err?.message ?? err}`);
-          this.fire(500, 'Internal Server Error');
+          logger.warn(`Background LLM dispatch failed: ${err?.message ?? err}`);
         });
-    }
 
-    // Sync path: explicit code/message or useLlm: false
-    if (args.length === 0) {
-      this._errorInfo = {
-        message: 'Internal Server Error',
-        type: null,
-        devInsight: null,
-        stack: null,
-        codeContext: null,
-      };
-      this.fire(500, 'Internal Server Error');
       return;
     }
 
-    if (isStatusCode(args[0])) {
-      const statusCode = args[0];
-      const message = args[1] || toStatusMessage(statusCode);
-      this._errorInfo = {
-        message,
-        type: null,
-        devInsight: null,
-        stack: null,
-        codeContext: null,
-      };
-      this.fire(statusCode, message);
-      return;
-    }
-
-    if (
-      typeof args[0]?.statusCode === 'number' &&
-      typeof args[0]?.code === 'string'
-    ) {
-      const error = args[0];
-      this._errorInfo = {
-        message: error.message,
-        type: error.constructor?.name ?? 'TejError',
-        devInsight: null,
-        stack: error.stack ?? null,
-        codeContext: null,
-      };
-      this.fire(error.statusCode, error.message);
-      return;
-    }
-
-    if (
-      args[0] != null &&
-      typeof args[0].message === 'string' &&
-      typeof args[0].stack === 'string'
-    ) {
-      const error = args[0];
-      if (!isNaN(parseInt(error.message))) {
-        const statusCode = parseInt(error.message);
-        const message = toStatusMessage(statusCode) || toStatusMessage(500);
+    // Sync mode (default): run LLM, then fire.
+    return captureCodeContext(stack)
+      .then((codeContext) => {
+        const context = {
+          codeContext,
+          method: this.method,
+          path: this.path,
+          includeDevInsight: true,
+          ...(throwOpts?.messageType && { messageType: throwOpts.messageType }),
+        };
+        if (originalError !== undefined) context.error = originalError;
+        return inferErrorFromContext(context).then((result) => ({
+          result,
+          codeContext,
+        }));
+      })
+      .then(({ result, codeContext }) => {
+        const devInsight = result.devInsight ?? null;
+        const finalStatus = resolved.explicit ? statusCode : result.statusCode;
+        const finalMessage = resolved.explicit ? message : result.message;
         this._errorInfo = {
-          message,
-          type: error.constructor.name,
-          devInsight: null,
-          stack: error.stack ?? null,
-          codeContext: null,
+          message: finalMessage,
+          type: errorType,
+          devInsight,
+          stack: stack ?? null,
+          codeContext: codeContext ?? null,
         };
-        this.fire(statusCode, message);
-        return;
-      }
-      const statusCode = toStatusCode(error.message);
-      if (statusCode) {
+        const isProduction = process.env.NODE_ENV === 'production';
+        const data =
+          !isProduction && devInsight
+            ? { message: finalMessage, _dev: devInsight }
+            : finalMessage;
+        this.fire(finalStatus, data);
+      })
+      .catch((err) => {
+        logger.warn(`LLM error inference failed: ${err?.message ?? err}`);
         this._errorInfo = {
-          message: error.message,
-          type: error.constructor.name,
+          message,
+          type: errorType,
           devInsight: null,
-          stack: error.stack ?? null,
+          stack: resolved.stack,
           codeContext: null,
         };
-        this.fire(statusCode, error.message);
-        return;
-      }
-      this._errorInfo = {
-        message: error.message,
-        type: error.constructor.name,
-        devInsight: null,
-        stack: error.stack ?? null,
-        codeContext: null,
-      };
-      this.fire(500, error.message);
-      return;
-    }
-
-    const errorValue = args[0];
-    const statusCode = toStatusCode(errorValue);
-    if (statusCode) {
-      this._errorInfo = {
-        message: toStatusMessage(statusCode),
-        type: null,
-        devInsight: null,
-        stack: null,
-        codeContext: null,
-      };
-      this.fire(statusCode, toStatusMessage(statusCode));
-      return;
-    }
-    this._errorInfo = {
-      message: errorValue.toString(),
-      type: null,
-      devInsight: null,
-      stack: null,
-      codeContext: null,
-    };
-    this.fire(500, errorValue.toString());
+        this.fire(statusCode, message);
+      });
   }
 }
 

package/server/errors/llm-error-service.js

@@ -16,6 +16,63 @@ import { getCache } from './llm-cache.js';
 const DEFAULT_STATUS = 500;
 const DEFAULT_MESSAGE = 'Internal Server Error';
 
+const MASKED_FIELDS = new Set([
+  'password',
+  'passwd',
+  'secret',
+  'token',
+  'api_key',
+  'apikey',
+  'authorization',
+  'auth',
+  'credit_card',
+  'card_number',
+  'cvv',
+  'ssn',
+  'email',
+  'phone',
+  'mobile',
+  'otp',
+  'pin',
+  'dob',
+  'date_of_birth',
+  'address',
+]);
+
+/**
+ * Recursively mask sensitive fields in an object before it reaches the LLM.
+ * Returns a new object; the original is never mutated.
+ */
+function maskForLlm(value) {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(maskForLlm);
+
+  const result = {};
+  for (const [k, v] of Object.entries(value)) {
+    result[k] = MASKED_FIELDS.has(k.toLowerCase()) ? '[MASKED]' : maskForLlm(v);
+  }
+  return result;
+}
+
+/**
+ * Sanitise an error before including it in the LLM prompt.
+ * If the error is an object with properties that match the GDPR blocklist,
+ * those values are replaced with [MASKED]. If it's a raw string or an Error
+ * with only a message, the message is passed through (it's developer-authored
+ * code-level text, not user-submitted data).
+ */
+function sanitiseErrorForPrompt(error) {
+  if (error === null || error === undefined) return error;
+  if (typeof error === 'string') return error;
+  if (error instanceof Error) {
+    const sanitised = new Error(error.message);
+    sanitised.name = error.name;
+    return sanitised;
+  }
+  return maskForLlm(error);
+}
+
 /**
  * Build prompt text from code context (and optional error) for the LLM.
  * @param {object} context
@@ -153,7 +210,7 @@ export async function inferErrorFromContext(context) {
     path: context.path,
     includeDevInsight,
     messageType,
-    error: context.error,
+    error: sanitiseErrorForPrompt(context.error),
   });
 
   const { content } = await provider.analyze(prompt);

package/server/handler.js

@@ -5,6 +5,7 @@ import logHttpRequest from '../utils/request-logger.js';
 import Ammo from './ammo.js';
 import TejError from './error.js';
 import targetRegistry from './targets/registry.js';
+import { traceStore } from '../radar/index.js';
 
 const errorLogger = new TejLogger('Tejas.Exception');
 const logger = new TejLogger('Tejas');
@@ -61,14 +62,35 @@ const executeChain = async (target, ammo) => {
     }
 
     const middleware = chain[i];
+    const currentIndex = i;
     i++;
 
+    // Span instrumentation — only active when radar tracing has set up a spanCtx.
+    const spanCtx = traceStore.getStore()?.spanCtx;
+    const spanStartMs = spanCtx ? Date.now() : 0;
+    const isHandler = currentIndex === chain.length - 1;
+    const spanName = isHandler
+      ? `handler:${ammo.endpoint ?? ammo.path ?? '/'}`
+      : `middleware:${middleware.name || 'anonymous'}`;
+    const spanType = isHandler ? 'handler' : 'middleware';
+
     const args =
       middleware.length === 3 ? [ammo.req, ammo.res, next] : [ammo, next];
 
     try {
       const result = await middleware(...args);
 
+      if (spanCtx) {
+        spanCtx.addSpan(
+          spanName,
+          spanType,
+          spanCtx.rootSpanId,
+          spanStartMs,
+          Date.now() - spanStartMs,
+          ammo.res.statusCode || 200,
+        );
+      }
+
       // Check again after middleware execution (passport might have redirected)
       if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
         return;
@@ -87,6 +109,17 @@ const executeChain = async (target, ammo) => {
         }
       }
     } catch (err) {
+      if (spanCtx) {
+        spanCtx.addSpan(
+          spanName,
+          spanType,
+          spanCtx.rootSpanId,
+          spanStartMs,
+          Date.now() - spanStartMs,
+          500,
+        );
+      }
+
       // Only handle error if response hasn't been sent
       if (
         !ammo.res.headersSent &&

package/te.js

@@ -275,7 +275,7 @@ class Tejas {
    * @param {string} [config.model] - Model name (e.g. gpt-4o-mini)
    * @param {'endUser'|'developer'} [config.messageType] - Default message tone
    * @param {'sync'|'async'} [config.mode] - 'sync' blocks the response until LLM returns (default); 'async' responds immediately with 500 and dispatches LLM result to a channel
-   * @param {number} [config.timeout] - LLM fetch timeout in milliseconds (default 10000)
+   * @param {number} [config.timeout] - LLM fetch timeout in milliseconds (default 20000)
    * @param {'console'|'log'|'both'} [config.channel] - Output channel for async mode results (default 'console')
    * @param {string} [config.logFile] - Path to JSONL log file used by 'log' and 'both' channels (default './errors.llm.log')
    * @param {number} [config.rateLimit] - Max LLM calls per minute across all requests (default 10)
@@ -381,7 +381,8 @@ class Tejas {
    * The project name is auto-detected from `package.json` if not supplied.
    *
    * @param {Object} [config] - Radar configuration
-   * @param {string} [config.collectorUrl]  Collector base URL (default: RADAR_COLLECTOR_URL env or http://localhost:3100)
+   * @param {string} [config.collectorUrl]  Collector base URL (default: RADAR_COLLECTOR_URL env or https://collector.usetejas.com).
+   *                                         A future release will support self-hosted Radar collectors.
    * @param {string} [config.apiKey]        Bearer token `rdr_xxx` (default: RADAR_API_KEY env)
    * @param {string} [config.projectName]   Project identifier (default: RADAR_PROJECT_NAME env → package.json name → "tejas-app")
    * @param {number} [config.flushInterval] Milliseconds between periodic flushes (default: 2000)
@@ -405,6 +406,13 @@ class Tejas {
    *   allowlist of specific header names to send (e.g. `['content-type', 'x-request-id']`).
    *   The collector always strips sensitive headers (`authorization`, `cookie`,
    *   `set-cookie`, `x-api-key`, etc.) server-side regardless of what is sent.
+   * @param {boolean} [config.capture.logs=false]
+   *   Forward TejLogger calls to the Radar collector as application-level log
+   *   events. Logs are automatically correlated with the current trace when
+   *   emitted inside a request context.
+   * @param {string[]} [config.capture.logLevels]
+   *   When `capture.logs` is true, only forward these levels to the collector
+   *   (e.g. `['warn', 'error']`). Defaults to all levels when omitted.
    *
    * @param {Object}   [config.mask]        Client-side masking applied to request/response bodies
    *                                         before data is sent to the collector.

package/utils/errors-llm-config.js

@@ -107,7 +107,7 @@ export function getErrorsLlmConfig() {
   const timeoutRaw = env('ERRORS_LLM_TIMEOUT') ?? env('LLM_TIMEOUT') ?? '';
   const timeoutNum = Number(timeoutRaw);
   const timeout =
-    !timeoutRaw || isNaN(timeoutNum) || timeoutNum <= 0 ? 10000 : timeoutNum;
+    !timeoutRaw || isNaN(timeoutNum) || timeoutNum <= 0 ? 20000 : timeoutNum;
 
   const channelRaw = env('ERRORS_LLM_CHANNEL') ?? env('LLM_CHANNEL') ?? '';