te.js 2.0.3 → 2.1.0

package/server/ammo.js

@@ -7,6 +7,24 @@ import {
 import html from '../utils/tejas-entrypoint-html.js';
 import ammoEnhancer from './ammo/enhancer.js';
 import TejError from './error.js';
+import { getErrorsLlmConfig } from '../utils/errors-llm-config.js';
+import { inferErrorFromContext } from './errors/llm-error-service.js';
+import { captureCodeContext } from './errors/code-context.js';
+
+/**
+ * Detect if the value is a throw() options object (per-call overrides).
+ * @param {unknown} v
+ * @returns {v is { useLlm?: boolean, messageType?: 'endUser'|'developer' }}
+ */
+function isThrowOptions(v) {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return false;
+  const o = /** @type {Record<string, unknown>} */ (v);
+  const hasUseLlm = 'useLlm' in o;
+  const hasMessageType =
+    'messageType' in o &&
+    (o.messageType === 'endUser' || o.messageType === 'developer');
+  return hasUseLlm || hasMessageType === true;
+}
 
 /**
  * Ammo class for handling HTTP requests and responses.
@@ -255,8 +273,8 @@ class Ammo {
   /**
    * Throws an error response with appropriate status code and message.
    *
-   * @param {number|Error|string} [arg1] - Status code, Error object, or error message
-   * @param {string} [arg2] - Error message (only used when arg1 is a status code)
+   * @param {number|Error|string|object} [arg1] - Status code, Error object, error message, or (when no code) options
+   * @param {string|object} [arg2] - Error message (when arg1 is status code) or options (when arg1 is error/empty)
    *
    * @description
    * The throw method is flexible and can handle different argument patterns:
@@ -267,8 +285,14 @@ class Ammo {
    * 4. Error object: Extracts status code and message from the error
    * 5. String: Treats as error message with 500 status code
    *
-   * The key difference between throw() and fire() is that throw() can accept an Error instance
-   * and has special handling for it. Internally, throw() still calls fire() to send the response.
+   * 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.
+   *
+   * 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).
    *
    * @example
    * // Throw a 404 Not Found error
@@ -285,18 +309,69 @@ class Ammo {
    * @example
    * // Throw an error with a custom message
    * ammo.throw('Something went wrong');
+   *
+   * @example
+   * // Skip LLM for this call; use default 500
+   * ammo.throw(err, { useLlm: false });
+   *
+   * @example
+   * // Force developer-friendly message for this call
+   * ammo.throw(err, { messageType: 'developer' });
+   *
+   * @returns {Promise<void>|void} Promise when LLM path is used; otherwise void
    */
   throw() {
-    // Handle different argument patterns
-    const args = Array.from(arguments);
+    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]) && !(args[0] instanceof TejError));
+    let throwOpts = /** @type {{ useLlm?: boolean, messageType?: 'endUser'|'developer' } | null} */ (null);
+    if (llmEligible && 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) {
+      // Use stack from thrown error when available (e.g. handler caught and called ammo.throw(err)) so we capture user code; else current call site.
+      const stack =
+        args[0] instanceof Error && args[0].stack
+          ? args[0].stack
+          : new Error().stack;
+      return captureCodeContext(stack)
+        .then((codeContext) => {
+          const context = {
+            codeContext,
+            method: this.method,
+            path: this.path,
+            includeDevInsight: true,
+            ...(throwOpts?.messageType && { messageType: throwOpts.messageType }),
+          };
+          if (args[0] !== undefined && args[0] !== null) context.error = args[0];
+          return inferErrorFromContext(context);
+        })
+        .then(({ statusCode, message, devInsight }) => {
+          const isProduction = process.env.NODE_ENV === 'production';
+          const data =
+            !isProduction && devInsight
+              ? { message, _dev: devInsight }
+              : message;
+          this.fire(statusCode, data);
+        });
+    }
 
-    // Case 1: No arguments provided
+    // Sync path: explicit code/message or useLlm: false
     if (args.length === 0) {
       this.fire(500, 'Internal Server Error');
       return;
     }
 
-    // Case 2: First argument is a status code
     if (isStatusCode(args[0])) {
       const statusCode = args[0];
       const message = args[1] || toStatusMessage(statusCode);
@@ -304,51 +379,35 @@ class Ammo {
       return;
     }
 
-    // Case 3.1: First argument is an instance of TejError
     if (args[0] instanceof TejError) {
       const error = args[0];
-      const statusCode = error.code;
-      const message = error.message;
-
-      this.fire(statusCode, message);
+      this.fire(error.code, error.message);
       return;
     }
 
-    // Case 3.2: First argument is an Error object
     if (args[0] instanceof Error) {
       const error = args[0];
-
-      // Check if error message is a numeric status code
       if (!isNaN(parseInt(error.message))) {
         const statusCode = parseInt(error.message);
         const message = toStatusMessage(statusCode) || toStatusMessage(500);
         this.fire(statusCode, message);
         return;
       }
-
-      // Use error message as status code if it's a valid status code string
       const statusCode = toStatusCode(error.message);
       if (statusCode) {
         this.fire(statusCode, error.message);
         return;
       }
-
-      // Default error handling
       this.fire(500, error.message);
       return;
     }
 
-    // Case 4: First argument is a string or other value
     const errorValue = args[0];
-
-    // Check if the string represents a status code
     const statusCode = toStatusCode(errorValue);
     if (statusCode) {
       this.fire(statusCode, toStatusMessage(statusCode));
       return;
     }
-
-    // Default case: treat as error message
     this.fire(500, errorValue.toString());
   }
 }

package/server/errors/code-context.js

@@ -0,0 +1,125 @@
+/**
+ * Capture code context from the call stack: surrounding source with line numbers,
+ * including upstream callers and downstream code. Used by LLM error inference.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+/** Path segments that identify te.js internals (excluded from "user" stack frames). */
+const INTERNAL_PATTERNS = [
+  'server/ammo.js',
+  'server/handler.js',
+  'server/errors/llm-error-service.js',
+  'server/errors/code-context.js',
+  'node_modules',
+];
+
+const LINES_ABOVE = 25;
+const LINES_BELOW = 25;
+const MAX_FRAMES = 6;
+
+/**
+ * Parse a single stack frame line to extract file path, line, and column.
+ * Handles "at fn (file:///path:line:col)" and "at file:///path:line:col" and "at /path:line:col".
+ * @param {string} line
+ * @returns {{ filePath: string, line: number, column: number } | null}
+ */
+function parseStackFrame(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('at ')) return null;
+  // Last occurrence of :number:number is line:column (path may contain colons on Windows/file URL)
+  const match = trimmed.match(/:(\d+):(\d+)\s*\)?\s*$/);
+  if (!match) return null;
+  const lineNum = parseInt(match[1], 10);
+  const colNum = parseInt(match[2], 10);
+  const before = trimmed.slice(0, trimmed.lastIndexOf(':' + match[1] + ':' + match[2]));
+  // Strip "at ... (" or "at " prefix to get path
+  let filePath = before.replace(/^\s*at\s+(?:.*?\s+\()?/, '').replace(/\)?\s*$/, '').trim();
+  if (filePath.startsWith('file://')) {
+    try {
+      filePath = fileURLToPath(filePath);
+    } catch {
+      return null;
+    }
+  }
+  if (!filePath || lineNum <= 0) return null;
+  return { filePath, line: lineNum, column: colNum };
+}
+
+/**
+ * Return true if this file path is internal (te.js / node_modules) and should be skipped for user context.
+ * @param {string} filePath - Absolute or relative path
+ */
+function isInternalFrame(filePath) {
+  const normalized = path.normalize(filePath).replace(/\\/g, '/');
+  return INTERNAL_PATTERNS.some((p) => normalized.includes(p));
+}
+
+/**
+ * Read source file and return lines [lineNum - LINES_ABOVE, lineNum + LINES_BELOW] with line numbers.
+ * @param {string} filePath - Absolute path
+ * @param {number} lineNum - Center line (1-based)
+ * @returns {Promise<{ file: string, line: number, snippet: string } | null>}
+ */
+async function readSnippet(filePath, lineNum) {
+  let content;
+  try {
+    content = await readFile(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+  const lines = content.split(/\r?\n/);
+  const start = Math.max(0, lineNum - 1 - LINES_ABOVE);
+  const end = Math.min(lines.length, lineNum + LINES_BELOW);
+  const snippet = lines
+    .slice(start, end)
+    .map((text, i) => {
+      const num = start + i + 1;
+      const marker = num === lineNum ? ' →' : '  ';
+      return `${String(num).padStart(4)}${marker} ${text}`;
+    })
+    .join('\n');
+
+  return {
+    file: filePath,
+    line: lineNum,
+    snippet,
+  };
+}
+
+/**
+ * Capture code context from the current call stack: parse stack, filter to user frames,
+ * and read surrounding source (with line numbers) for each frame. First frame is the
+ * throw site; remaining frames are upstream callers. Each snippet includes lines
+ * above and below (downstream in the same function).
+ *
+ * @param {string} [stack] - Stack string (e.g. new Error().stack). If omitted, captures current stack.
+ * @param {{ maxFrames?: number, linesAround?: number }} [options]
+ * @returns {Promise<{ snippets: Array<{ file: string, line: number, snippet: string }> }>}
+ */
+export async function captureCodeContext(stack, options = {}) {
+  const stackStr = typeof stack === 'string' && stack ? stack : new Error().stack;
+  if (!stackStr) return { snippets: [] };
+
+  const maxFrames = options.maxFrames ?? MAX_FRAMES;
+  const lines = stackStr.split('\n');
+  const frames = [];
+
+  for (const line of lines) {
+    const parsed = parseStackFrame(line);
+    if (!parsed) continue;
+    if (isInternalFrame(parsed.filePath)) continue;
+    frames.push(parsed);
+    if (frames.length >= maxFrames) break;
+  }
+
+  const snippets = [];
+  for (const { filePath, line } of frames) {
+    const one = await readSnippet(filePath, line);
+    if (one) snippets.push(one);
+  }
+
+  return { snippets };
+}

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

@@ -0,0 +1,140 @@
+/**
+ * LLM-based error inference: given code context (surrounding + upstream/downstream),
+ * returns statusCode and message (and optionally devInsight in non-production).
+ * Uses shared lib/llm with errors.llm config. Developers do not pass an error object;
+ * the LLM infers from the code where ammo.throw() was called.
+ */
+
+import { createProvider } from '../../lib/llm/index.js';
+import { extractJSON } from '../../lib/llm/parse.js';
+import { getErrorsLlmConfig } from '../../utils/errors-llm-config.js';
+
+const DEFAULT_STATUS = 500;
+const DEFAULT_MESSAGE = 'Internal Server Error';
+
+/**
+ * Build prompt text from code context (and optional error) for the LLM.
+ * @param {object} context
+ * @param {{ snippets: Array<{ file: string, line: number, snippet: string }> }} context.codeContext - Source snippets with line numbers (first = throw site, rest = upstream).
+ * @param {string} [context.method] - HTTP method.
+ * @param {string} [context.path] - Request path.
+ * @param {boolean} [context.includeDevInsight] - If true, ask for devInsight.
+ * @param {'endUser'|'developer'} [context.messageType] - Message tone.
+ * @param {string|Error|undefined} [context.error] - Optional error if one was passed (secondary signal).
+ * @returns {string}
+ */
+function buildPrompt(context) {
+  const { codeContext, method, path, includeDevInsight, messageType, error } = context;
+  const forDeveloper = messageType === 'developer';
+
+  const requestPart = [method, path].filter(Boolean).length
+    ? `Request: ${[method, path].filter(Boolean).join(' ')}`
+    : '';
+
+  let codePart = 'No code context was captured.';
+  if (codeContext?.snippets?.length) {
+    codePart = codeContext.snippets
+      .map((s, i) => {
+        const label = i === 0 ? 'Call site (where ammo.throw() was invoked)' : `Upstream caller ${i}`;
+        return `--- ${label}: ${s.file} (line ${s.line}) ---\n${s.snippet}`;
+      })
+      .join('\n\n');
+  }
+
+  let errorPart = '';
+  if (error !== undefined && error !== null) {
+    if (error instanceof Error) {
+      errorPart = `\nOptional error message (may be empty): ${error.message}`;
+    } else {
+      errorPart = `\nOptional error/message: ${String(error)}`;
+    }
+  }
+
+  const devPart = includeDevInsight
+    ? '\nAlso provide a short "devInsight" string (one or two sentences) for the developer: (a) Is this likely a bug in the code or an environment/setup issue? (b) If the developer can fix it, suggest the fix. Be concise.'
+    : '';
+
+  const messageInstruction = forDeveloper
+    ? '- "message": string (short message for developers: may include technical detail, error type, or cause; do not include raw stack traces)'
+    : '- "message": string (short, end-user-facing message: safe for clients; do not expose stack traces, internal details, or technical jargon)';
+
+  return `You are helping map an application error to an HTTP response. The developer called ammo.throw() (or an error was thrown and caught) at the call site below. Use the surrounding code with line numbers and all upstream/downstream context to infer what went wrong and choose an appropriate HTTP status and message.
+
+Consider:
+- The code BEFORE the throw (upstream in the same function and in callers) — what led to this point.
+- The code AFTER the throw line (downstream) — what would have run next; this shows intent and expected flow.
+- The first snippet is the call site (line marked with →); later snippets are upstream callers.
+
+${requestPart ? requestPart + '\n\n' : ''}Code context (with line numbers; → marks the throw line):
+
+${codePart}${errorPart}
+${devPart ? '\n' + devPart : ''}
+
+Respond with only valid JSON, no markdown or explanation. Use this shape:
+- "statusCode": number (HTTP status, typically 4xx or 5xx; use 500 for generic/server errors)
+${messageInstruction}
+${includeDevInsight ? '- "devInsight": string (brief note for the developer only)' : ''}
+
+JSON:`;
+}
+
+/**
+ * Infer HTTP statusCode and message (and optionally devInsight) from code context using the LLM.
+ * Uses errors.llm config (getErrorsLlmConfig). Call only when errors.llm.enabled is true and config is valid.
+ * The primary input is codeContext (surrounding + upstream/downstream snippets); error is optional.
+ *
+ * @param {object} context - Context for the prompt.
+ * @param {{ snippets: Array<{ file: string, line: number, snippet: string }> }} context.codeContext - Source snippets with line numbers (from captureCodeContext).
+ * @param {string} [context.method] - HTTP method.
+ * @param {string} [context.path] - Request path.
+ * @param {boolean} [context.includeDevInsight] - In non-production, dev insight is included by default; set to false to disable.
+ * @param {'endUser'|'developer'} [context.messageType] - Override config: 'endUser' or 'developer'. Default from errors.llm.messageType.
+ * @param {string|Error|undefined} [context.error] - Optional error if the caller passed one (secondary signal).
+ * @returns {Promise<{ statusCode: number, message: string, devInsight?: string }>}
+ */
+export async function inferErrorFromContext(context) {
+  const config = getErrorsLlmConfig();
+  const { baseURL, apiKey, model, messageType: configMessageType } = config;
+  const provider = createProvider({ baseURL, apiKey, model });
+
+  const isProduction = process.env.NODE_ENV === 'production';
+  const includeDevInsight = !isProduction && context.includeDevInsight !== false;
+  const messageType = context.messageType ?? configMessageType;
+
+  const prompt = buildPrompt({
+    codeContext: context.codeContext,
+    method: context.method,
+    path: context.path,
+    includeDevInsight,
+    messageType,
+    error: context.error,
+  });
+
+  const { content } = await provider.analyze(prompt);
+  const parsed = extractJSON(content);
+
+  if (!parsed || typeof parsed !== 'object') {
+    return {
+      statusCode: DEFAULT_STATUS,
+      message: DEFAULT_MESSAGE,
+      ...(includeDevInsight && { devInsight: 'Could not parse LLM response.' }),
+    };
+  }
+
+  let statusCode = Number(parsed.statusCode);
+  if (Number.isNaN(statusCode) || statusCode < 100 || statusCode > 599) {
+    statusCode = DEFAULT_STATUS;
+  }
+
+  const message =
+    typeof parsed.message === 'string' && parsed.message.trim()
+      ? parsed.message.trim()
+      : DEFAULT_MESSAGE;
+
+  const result = { statusCode, message };
+  if (includeDevInsight && typeof parsed.devInsight === 'string' && parsed.devInsight.trim()) {
+    result.devInsight = parsed.devInsight.trim();
+  }
+
+  return result;
+}

package/server/handler.js

@@ -54,7 +54,7 @@ const executeChain = async (target, ammo) => {
     } catch (err) {
       // Only handle error if response hasn't been sent
       if (!ammo.res.headersSent && !ammo.res.writableEnded && !ammo.res.finished) {
-        errorHandler(ammo, err);
+        await errorHandler(ammo, err);
       }
     }
   };
@@ -63,16 +63,22 @@ const executeChain = async (target, ammo) => {
 };
 
 /**
- * Handles errors by logging them and sending an appropriate response.
+ * Handles errors: optional logging (log.exceptions) and sending the response via ammo.throw(err).
+ * One mechanism — ammo.throw — takes care of everything (no separate "log then send").
+ * When errors.llm.enabled, framework-caught errors get the same LLM-inferred response as explicit ammo.throw().
+ * When ammo.throw() returns a Promise (LLM path), waits for it to complete.
  *
  * @param {Ammo} ammo - The Ammo instance containing request and response objects.
  * @param {Error} err - The error object to handle.
+ * @returns {Promise<void>}
  */
-const errorHandler = (ammo, err) => {
+const errorHandler = async (ammo, err) => {
   if (env('LOG_EXCEPTIONS')) errorLogger.error(err);
 
-  if (err instanceof TejError) return ammo.throw(err);
-  return ammo.throw(err);
+  const result = ammo.throw(err);
+  if (result != null && typeof result.then === 'function') {
+    await result;
+  }
 };
 
 /**
@@ -102,11 +108,11 @@ const handler = async (req, res) => {
       if (req.url === '/') {
         ammo.defaultEntry();
       } else {
-        errorHandler(ammo, new TejError(404, `URL not found: ${url}`));
+        await errorHandler(ammo, new TejError(404, `URL not found: ${url}`));
       }
     }
   } catch (err) {
-    errorHandler(ammo, err);
+    await errorHandler(ammo, err);
   }
 };
 

package/te.js

@@ -9,6 +9,7 @@ import dbManager from './database/index.js';
 import { loadConfigFile, standardizeObj } from './utils/configuration.js';
 
 import targetHandler from './server/handler.js';
+import { getErrorsLlmConfig, validateErrorsLlmAtTakeoff } from './utils/errors-llm-config.js';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
@@ -190,6 +191,13 @@ class Tejas {
    * app.takeoff(); // Server starts on default port 1403
    */
   takeoff({ withRedis, withMongo } = {}) {
+    validateErrorsLlmAtTakeoff();
+    const errorsLlm = getErrorsLlmConfig();
+    if (errorsLlm.enabled) {
+      logger.info(
+        `errors.llm enabled successfully — baseURL: ${errorsLlm.baseURL}, model: ${errorsLlm.model}, messageType: ${errorsLlm.messageType}, apiKey: ${errorsLlm.apiKey ? '***' : '(missing)'}`,
+      );
+    }
     this.engine = createServer(targetHandler);
     this.engine.listen(env('PORT'), async () => {
       logger.info(`Took off from port ${env('PORT')}`);
@@ -294,6 +302,37 @@ class Tejas {
     return this;
   }
 
+  /**
+   * Enables LLM-inferred error codes and messages for ammo.throw() and framework-caught errors.
+   * Call before takeoff(). Remaining options (baseURL, apiKey, model, messageType) can come from
+   * config, or from env/tejas.config.json (LLM_* / ERRORS_LLM_*). Validation runs at takeoff.
+   *
+   * @param {Object} [config] - Optional errors.llm overrides
+   * @param {string} [config.baseURL] - LLM provider endpoint (e.g. https://api.openai.com/v1)
+   * @param {string} [config.apiKey] - LLM provider API key
+   * @param {string} [config.model] - Model name (e.g. gpt-4o-mini)
+   * @param {'endUser'|'developer'} [config.messageType] - Default message tone
+   * @returns {Tejas} The Tejas instance for chaining
+   *
+   * @example
+   * app.withLLMErrors();
+   * app.takeoff();
+   *
+   * @example
+   * app.withLLMErrors({ baseURL: 'https://api.openai.com/v1', apiKey: process.env.OPENAI_KEY, model: 'gpt-4o-mini' });
+   * app.takeoff();
+   */
+  withLLMErrors(config) {
+    setEnv('ERRORS_LLM_ENABLED', true);
+    if (config && typeof config === 'object') {
+      if (config.baseURL != null) setEnv('ERRORS_LLM_BASE_URL', config.baseURL);
+      if (config.apiKey != null) setEnv('ERRORS_LLM_API_KEY', config.apiKey);
+      if (config.model != null) setEnv('ERRORS_LLM_MODEL', config.model);
+      if (config.messageType != null) setEnv('ERRORS_LLM_MESSAGE_TYPE', config.messageType);
+    }
+    return this;
+  }
+
   /**
    * Adds global rate limiting to all endpoints
    *

package/utils/errors-llm-config.js

@@ -0,0 +1,84 @@
+/**
+ * Resolve and validate errors.llm configuration (LLM-inferred error codes/messages).
+ * Uses ERRORS_LLM_* env vars with fallback to LLM_*.
+ * Config file keys (e.g. errors.llm.baseURL) are standardized to ERRORS_LLM_BASEURL etc.
+ */
+
+import { env } from 'tej-env';
+
+const MESSAGE_TYPES = /** @type {const} */ (['endUser', 'developer']);
+
+/**
+ * Normalize messageType to 'endUser' | 'developer'.
+ * @param {string} v
+ * @returns {'endUser'|'developer'}
+ */
+function normalizeMessageType(v) {
+  const s = String(v ?? '').trim().toLowerCase();
+  if (s === 'developer' || s === 'dev') return 'developer';
+  return 'endUser'; // endUser, end_user, default
+}
+
+/**
+ * Resolve errors.llm config from env (feature-specific then LLM_ fallback).
+ * @returns {{ enabled: boolean, baseURL: string, apiKey: string, model: string, messageType: 'endUser'|'developer' }}
+ */
+export function getErrorsLlmConfig() {
+  const enabledRaw = env('ERRORS_LLM_ENABLED') ?? '';
+  const enabled =
+    enabledRaw === true ||
+    enabledRaw === 'true' ||
+    enabledRaw === '1' ||
+    enabledRaw === 1;
+
+  const baseURL =
+    env('ERRORS_LLM_BASE_URL') ??
+    env('ERRORS_LLM_BASEURL') ??
+    env('LLM_BASE_URL') ??
+    env('LLM_BASEURL') ??
+    '';
+
+  const apiKey =
+    env('ERRORS_LLM_API_KEY') ??
+    env('ERRORS_LLM_APIKEY') ??
+    env('LLM_API_KEY') ??
+    env('LLM_APIKEY') ??
+    '';
+
+  const model =
+    env('ERRORS_LLM_MODEL') ?? env('LLM_MODEL') ?? '';
+
+  const messageTypeRaw =
+    env('ERRORS_LLM_MESSAGE_TYPE') ?? env('ERRORS_LLM_MESSAGETYPE') ?? env('LLM_MESSAGE_TYPE') ?? env('LLM_MESSAGETYPE') ?? '';
+
+  return {
+    enabled: Boolean(enabled),
+    baseURL: String(baseURL ?? '').trim(),
+    apiKey: String(apiKey ?? '').trim(),
+    model: String(model ?? '').trim(),
+    messageType: normalizeMessageType(messageTypeRaw || 'endUser'),
+  };
+}
+
+export { MESSAGE_TYPES };
+
+/**
+ * Validate errors.llm when enabled: require baseURL, apiKey, and model (after LLM_ fallback).
+ * Call at takeoff. Throws if enabled but config is invalid; no-op otherwise.
+ * @throws {Error} If errors.llm.enabled is true but any of baseURL, apiKey, or model is missing
+ */
+export function validateErrorsLlmAtTakeoff() {
+  const { enabled, baseURL, apiKey, model } = getErrorsLlmConfig();
+  if (!enabled) return;
+
+  const missing = [];
+  if (!baseURL) missing.push('baseURL (ERRORS_LLM_BASE_URL or LLM_BASE_URL)');
+  if (!apiKey) missing.push('apiKey (ERRORS_LLM_API_KEY or LLM_API_KEY)');
+  if (!model) missing.push('model (ERRORS_LLM_MODEL or LLM_MODEL)');
+
+  if (missing.length > 0) {
+    throw new Error(
+      `errors.llm is enabled but required config is missing: ${missing.join(', ')}. Set these env vars or disable errors.llm.enabled.`,
+    );
+  }
+}

package/auto-docs/llm/index.js

@@ -1,6 +0,0 @@
-/**
- * LLM provider for auto-documentation.
- * Single OpenAI-compatible setup: use createProvider(config) with baseURL, apiKey, model.
- */
-
-export { LLMProvider, createProvider, extractJSON, extractJSONArray } from './provider.js';