te.js 2.1.4 → 2.1.6

package/docs/configuration.md

@@ -110,15 +110,22 @@ These options configure the `tejas generate:docs` CLI command and the auto-docum
 
 ### Error handling (LLM-inferred errors)
 
-When [LLM-inferred error codes and messages](./error-handling.md#llm-inferred-errors) are enabled, the **`errors.llm`** block configures the LLM used for inferring status code and message when you call `ammo.throw()` without explicit code or message. Unset values fall back to `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL`. You can also enable (and optionally set connection options) by calling **`app.withLLMErrors(config?)`** before `takeoff()` — e.g. `app.withLLMErrors()` to use env/config for baseURL, apiKey, model, or `app.withLLMErrors({ baseURL, apiKey, model, messageType })` to override in code.
-
-| Config Key               | Env Variable                                     | Type                         | Default                       | Description                                                                                                                                  |
-| ------------------------ | ------------------------------------------------ | ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `errors.llm.enabled`     | `ERRORS_LLM_ENABLED` or `LLM_*` (for connection) | boolean                      | `false`                       | Enable LLM-inferred error code and message for `ammo.throw()`                                                                                |
-| `errors.llm.baseURL`     | `ERRORS_LLM_BASE_URL` or `LLM_BASE_URL`          | string                       | `"https://api.openai.com/v1"` | LLM provider endpoint for error inference                                                                                                    |
-| `errors.llm.apiKey`      | `ERRORS_LLM_API_KEY` or `LLM_API_KEY`            | string                       | —                             | LLM provider API key for error inference                                                                                                     |
-| `errors.llm.model`       | `ERRORS_LLM_MODEL` or `LLM_MODEL`                | string                       | `"gpt-4o-mini"`               | LLM model for error inference                                                                                                                |
-| `errors.llm.messageType` | `ERRORS_LLM_MESSAGE_TYPE` or `LLM_MESSAGE_TYPE`  | `"endUser"` \| `"developer"` | `"endUser"`                   | Default tone for LLM-generated message: `endUser` (safe for clients) or `developer` (technical detail). Overridable per `ammo.throw()` call. |
+When [LLM-inferred error codes and messages](./error-handling.md#llm-inferred-errors) are enabled, the **`errors.llm`** block configures the LLM used for inferring status code and message when you call `ammo.throw()` without explicit code or message. Unset values fall back to `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL`. You can also enable (and optionally set connection options) by calling **`app.withLLMErrors(config?)`** before `takeoff()` — e.g. `app.withLLMErrors()` to use env/config for baseURL, apiKey, model, or `app.withLLMErrors({ baseURL, apiKey, model, messageType, mode, ... })` to override in code.
+
+| Config Key               | Env Variable                                    | Type                               | Default              | Description                                                                                                                                                                                                          |
+| ------------------------ | ----------------------------------------------- | ---------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `errors.llm.enabled`     | `ERRORS_LLM_ENABLED`                            | boolean                            | `false`              | Enable LLM-inferred error code and message for `ammo.throw()` and framework-caught errors.                                                                                                                           |
+| `errors.llm.baseURL`     | `ERRORS_LLM_BASE_URL` or `LLM_BASE_URL`         | string                             | —                    | LLM provider endpoint (e.g. `https://api.openai.com/v1`). Required when enabled.                                                                                                                                     |
+| `errors.llm.apiKey`      | `ERRORS_LLM_API_KEY` or `LLM_API_KEY`           | string                             | —                    | LLM provider API key. Required when enabled.                                                                                                                                                                         |
+| `errors.llm.model`       | `ERRORS_LLM_MODEL` or `LLM_MODEL`               | string                             | —                    | LLM model name (e.g. `gpt-4o-mini`). Required when enabled.                                                                                                                                                          |
+| `errors.llm.messageType` | `ERRORS_LLM_MESSAGE_TYPE` or `LLM_MESSAGE_TYPE` | `"endUser"` \| `"developer"`       | `"endUser"`          | Default tone for LLM-generated messages. `endUser` is safe for clients; `developer` includes technical detail. Overridable per `ammo.throw()` call.                                                                  |
+| `errors.llm.mode`        | `ERRORS_LLM_MODE` or `LLM_MODE`                 | `"sync"` \| `"async"`              | `"sync"`             | `sync` blocks the HTTP response until the LLM returns. `async` sends an immediate 500 and runs the LLM in the background, dispatching the result to the configured channel.                                          |
+| `errors.llm.timeout`     | `ERRORS_LLM_TIMEOUT` or `LLM_TIMEOUT`           | number (ms)                        | `10000`              | Maximum time in milliseconds to wait for an LLM response before aborting with a timeout error.                                                                                                                       |
+| `errors.llm.channel`     | `ERRORS_LLM_CHANNEL` or `LLM_CHANNEL`           | `"console"` \| `"log"` \| `"both"` | `"console"`          | Output channel for async mode results. `console` pretty-prints to the terminal; `log` appends JSONL to the log file; `both` does both. Only applies when `mode` is `async`.                                          |
+| `errors.llm.logFile`     | `ERRORS_LLM_LOG_FILE`                           | string (path)                      | `"./errors.llm.log"` | Path for the JSONL log file used by the `log` and `both` channels.                                                                                                                                                   |
+| `errors.llm.rateLimit`   | `ERRORS_LLM_RATE_LIMIT` or `LLM_RATE_LIMIT`     | number                             | `10`                 | Maximum number of LLM calls allowed per minute across all requests. When exceeded, a generic 500 is returned (sync) or dispatched with a `rateLimited` flag (async). Cached results do not count against this limit. |
+| `errors.llm.cache`       | `ERRORS_LLM_CACHE`                              | boolean                            | `true`               | Cache LLM results by throw site (file + line) and error message. Repeated errors at the same location reuse the cached result without making another LLM call.                                                       |
+| `errors.llm.cacheTTL`    | `ERRORS_LLM_CACHE_TTL`                          | number (ms)                        | `3600000`            | How long cached results are reused (default 1 hour). After expiry the same error will trigger a fresh LLM call.                                                                                                      |
 
 When enabled, the same behaviour applies whether you call `ammo.throw()` or the framework calls it when it catches an error — one mechanism, no separate config.
 
@@ -162,7 +169,14 @@ Create a `tejas.config.json` in your project root:
       "enabled": true,
       "baseURL": "https://api.openai.com/v1",
       "model": "gpt-4o-mini",
-      "messageType": "endUser"
+      "messageType": "endUser",
+      "mode": "async",
+      "timeout": 10000,
+      "channel": "both",
+      "logFile": "./errors.llm.log",
+      "rateLimit": 10,
+      "cache": true,
+      "cacheTTL": 3600000
     }
   }
 }

package/docs/error-handling.md

@@ -15,8 +15,8 @@ Tejas wraps all middleware and route handlers with built-in error catching. Any
 ```javascript
 // ✅ No try-catch needed — Tejas handles errors automatically
 target.register('/users/:id', async (ammo) => {
-  const user = await database.findUser(ammo.payload.id);  // If this throws, Tejas catches it
-  const posts = await database.getUserPosts(user.id);      // Same here
+  const user = await database.findUser(ammo.payload.id); // If this throws, Tejas catches it
+  const posts = await database.getUserPosts(user.id); // Same here
   ammo.fire({ user, posts });
 });
 ```
@@ -30,8 +30,8 @@ app.get('/users/:id', async (req, res) => {
     const user = await database.findUser(req.params.id);
     res.json(user);
   } catch (error) {
-    console.error(error);           // 1. log
-    res.status(500).json({ error: 'Internal Server Error' });  // 2. send response
+    console.error(error); // 1. log
+    res.status(500).json({ error: 'Internal Server Error' }); // 2. send response
   }
 });
 ```
@@ -47,8 +47,8 @@ To see caught exceptions in your logs, enable exception logging:
 ```javascript
 const app = new Tejas({
   log: {
-    exceptions: true  // Log all caught exceptions
-  }
+    exceptions: true, // Log all caught exceptions
+  },
 });
 ```
 
@@ -89,6 +89,87 @@ ammo.throw({ messageType: 'developer' });
 ammo.throw(caughtErr, { useLlm: false });
 ```
 
+### Async mode
+
+By default (`errors.llm.mode: 'sync'`), `ammo.throw()` blocks the HTTP response until the LLM returns. This adds LLM latency (typically 1–3 seconds) to every error response.
+
+Set `errors.llm.mode` to `'async'` to respond immediately with a generic `500 Internal Server Error` and run the LLM inference in the background. The result is dispatched to the configured **channel** once ready — the client never waits.
+
+```bash
+# .env
+ERRORS_LLM_MODE=async
+ERRORS_LLM_CHANNEL=both   # console + log file
+```
+
+```javascript
+// tejas.config.json
+{
+  "errors": {
+    "llm": {
+      "enabled": true,
+      "mode": "async",
+      "channel": "both"
+    }
+  }
+}
+```
+
+In async mode:
+
+- The HTTP response is always `500 Internal Server Error` regardless of what the LLM would infer. The LLM-inferred status and message are only visible in the channel.
+- Developer insight (`devInsight`) is **always** included in the channel output, even in production — it never reaches the HTTP response.
+- If the LLM call fails or times out in the background, it is silently swallowed. The HTTP response has already been sent.
+
+### Output channels (async mode)
+
+When `mode` is `async`, the LLM result is sent to the configured channel after the response. Set `errors.llm.channel`:
+
+| Channel               | Output                                                                                                                                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"console"` (default) | Pretty-printed colored block in the terminal: timestamp, method+path, inferred status, message, dev insight. Shows `[CACHED]` or `[RATE LIMITED]` flags.                                                                        |
+| `"log"`               | Appends a JSON line to `errors.llm.logFile` (default `./errors.llm.log`). Each entry contains all fields: timestamp, method, path, statusCode, message, devInsight, original error, code context snippets, cached, rateLimited. |
+| `"both"`              | Both console and log file.                                                                                                                                                                                                      |
+
+The log file uses **JSONL format** (one JSON object per line), so it can be read by log analysis tools or Radar.
+
+```bash
+ERRORS_LLM_CHANNEL=log
+ERRORS_LLM_LOG_FILE=./logs/llm-errors.log
+```
+
+### Rate limiting
+
+Set `errors.llm.rateLimit` (default `10`) to cap the number of LLM calls per minute across all requests. This prevents a burst of errors from exhausting your API quota.
+
+```bash
+ERRORS_LLM_RATE_LIMIT=20
+```
+
+When the rate limit is exceeded:
+
+- **Sync mode**: responds immediately with `500 Internal Server Error` (no LLM call).
+- **Async mode**: the channel still receives a dispatch with `rateLimited: true` so the error occurrence is recorded even though LLM enhancement was skipped.
+
+Cached results do **not** count against the rate limit.
+
+### Error caching
+
+By default (`errors.llm.cache: true`), Tejas caches LLM results by throw site and error message. If the same error is thrown at the same file and line, the cached result is reused without making another LLM call.
+
+```bash
+ERRORS_LLM_CACHE=true
+ERRORS_LLM_CACHE_TTL=3600000   # 1 hour (default)
+```
+
+The cache key is: `file:line:errorMessage`. After the TTL expires, the next occurrence triggers a fresh LLM call.
+
+To effectively **only enhance new errors**, keep caching enabled with a long TTL. To re-evaluate errors more frequently, reduce the TTL.
+
+```javascript
+// Only enhance errors once per 24 hours
+app.withLLMErrors({ cache: true, cacheTTL: 86400000 });
+```
+
 ---
 
 ## TejError Class
@@ -113,6 +194,7 @@ throw new TejError(404, 'Resource not found');
 ```
 
 **Response:**
+
 ```
 HTTP/1.1 404 Not Found
 Content-Type: text/plain
@@ -148,7 +230,7 @@ ammo.throw(new TejError(400, 'Bad request'));
 // When errors.llm.enabled: LLM infers code and message from context
 ammo.throw(new Error('Something went wrong'));
 ammo.throw('Validation failed');
-ammo.throw();  // context still used when available
+ammo.throw(); // context still used when available
 ```
 
 See [Ammo — throw()](./ammo.md#throw--send-error-response) for all signatures and the LLM-inferred row.
@@ -160,13 +242,13 @@ See [Ammo — throw()](./ammo.md#throw--send-error-response) for all signatures
 ```javascript
 target.register('/users/:id', async (ammo) => {
   const { id } = ammo.payload;
-  
+
   const user = await findUser(id);
-  
+
   if (!user) {
     throw new TejError(404, 'User not found');
   }
-  
+
   ammo.fire(user);
 });
 ```
@@ -194,8 +276,8 @@ Errors are automatically caught by Tejas's handler. Enable logging:
 ```javascript
 const app = new Tejas({
   log: {
-    exceptions: true // Log all exceptions
-  }
+    exceptions: true, // Log all exceptions
+  },
 });
 ```
 
@@ -207,18 +289,18 @@ Create middleware to customize error handling:
 // middleware/error-handler.js
 export const errorHandler = (ammo, next) => {
   const originalThrow = ammo.throw.bind(ammo);
-  
+
   ammo.throw = (...args) => {
     // Log errors
     console.error('Error:', args);
-    
+
     // Send to error tracking service
     errorTracker.capture(args[0]);
-    
+
     // Call original throw
     originalThrow(...args);
   };
-  
+
   next();
 };
 
@@ -234,12 +316,12 @@ For APIs, return structured error objects:
 // middleware/api-errors.js
 export const apiErrorHandler = (ammo, next) => {
   const originalThrow = ammo.throw.bind(ammo);
-  
+
   ammo.throw = (statusOrError, message) => {
     let status = 500;
     let errorMessage = 'Internal Server Error';
     let errorCode = 'INTERNAL_ERROR';
-    
+
     if (typeof statusOrError === 'number') {
       status = statusOrError;
       errorMessage = message || getDefaultMessage(status);
@@ -249,16 +331,16 @@ export const apiErrorHandler = (ammo, next) => {
       errorMessage = statusOrError.message;
       errorCode = getErrorCode(status);
     }
-    
+
     ammo.fire(status, {
       error: {
         code: errorCode,
         message: errorMessage,
-        status
-      }
+        status,
+      },
     });
   };
-  
+
   next();
 };
 
@@ -270,7 +352,7 @@ function getDefaultMessage(status) {
     404: 'Not Found',
     405: 'Method Not Allowed',
     429: 'Too Many Requests',
-    500: 'Internal Server Error'
+    500: 'Internal Server Error',
   };
   return messages[status] || 'Unknown Error';
 }
@@ -283,13 +365,14 @@ function getErrorCode(status) {
     404: 'NOT_FOUND',
     405: 'METHOD_NOT_ALLOWED',
     429: 'RATE_LIMITED',
-    500: 'INTERNAL_ERROR'
+    500: 'INTERNAL_ERROR',
   };
   return codes[status] || 'UNKNOWN_ERROR';
 }
 ```
 
 **Response:**
+
 ```json
 {
   "error": {
@@ -307,10 +390,10 @@ For input validation, return detailed errors:
 ```javascript
 target.register('/users', (ammo) => {
   if (!ammo.POST) return ammo.notAllowed();
-  
+
   const { name, email, age } = ammo.payload;
   const errors = [];
-  
+
   if (!name) errors.push({ field: 'name', message: 'Name is required' });
   if (!email) errors.push({ field: 'email', message: 'Email is required' });
   if (email && !isValidEmail(email)) {
@@ -319,17 +402,17 @@ target.register('/users', (ammo) => {
   if (age && (isNaN(age) || age < 0)) {
     errors.push({ field: 'age', message: 'Age must be a positive number' });
   }
-  
+
   if (errors.length > 0) {
     return ammo.fire(400, {
       error: {
         code: 'VALIDATION_ERROR',
         message: 'Validation failed',
-        details: errors
-      }
+        details: errors,
+      },
     });
   }
-  
+
   // Process valid data...
 });
 ```
@@ -380,16 +463,17 @@ While Tejas catches all errors automatically, you may want try-catch for:
 
 `BodyParserError` is a subclass of `TejError` thrown automatically during request body parsing. You do not need to handle these yourself — they are caught by the framework and converted to appropriate HTTP responses.
 
-| Status | Condition |
-|--------|-----------|
+| Status  | Condition                                                                  |
+| ------- | -------------------------------------------------------------------------- |
 | **400** | Malformed JSON, invalid URL-encoded data, or corrupted multipart form data |
-| **408** | Body parsing timed out (exceeds `body.timeout`, default 30 seconds) |
-| **413** | Request body exceeds `body.max_size` (default 10 MB) |
-| **415** | Unsupported content type (not JSON, URL-encoded, or multipart) |
+| **408** | Body parsing timed out (exceeds `body.timeout`, default 30 seconds)        |
+| **413** | Request body exceeds `body.max_size` (default 10 MB)                       |
+| **415** | Unsupported content type (not JSON, URL-encoded, or multipart)             |
 
 These limits are configured via [Configuration](./configuration.md) (`body.max_size`, `body.timeout`).
 
 Supported content types:
+
 - `application/json`
 - `application/x-www-form-urlencoded`
 - `multipart/form-data`
@@ -410,21 +494,21 @@ Once a response has been sent (`res.headersSent` is true), no further middleware
 
 ## Error Codes Reference
 
-| Status | Name | When to Use |
-|--------|------|-------------|
-| 400 | Bad Request | Invalid input, malformed request |
-| 401 | Unauthorized | Missing or invalid authentication |
-| 403 | Forbidden | Authenticated but not authorized |
-| 404 | Not Found | Resource doesn't exist |
-| 405 | Method Not Allowed | HTTP method not supported |
-| 409 | Conflict | Resource conflict (duplicate) |
-| 413 | Payload Too Large | Request body too large |
-| 422 | Unprocessable Entity | Valid syntax but semantic errors |
-| 429 | Too Many Requests | Rate limit exceeded |
-| 500 | Internal Server Error | Unexpected server errors |
-| 502 | Bad Gateway | Upstream server error |
-| 503 | Service Unavailable | Server temporarily unavailable |
-| 504 | Gateway Timeout | Upstream server timeout |
+| Status | Name                  | When to Use                       |
+| ------ | --------------------- | --------------------------------- |
+| 400    | Bad Request           | Invalid input, malformed request  |
+| 401    | Unauthorized          | Missing or invalid authentication |
+| 403    | Forbidden             | Authenticated but not authorized  |
+| 404    | Not Found             | Resource doesn't exist            |
+| 405    | Method Not Allowed    | HTTP method not supported         |
+| 409    | Conflict              | Resource conflict (duplicate)     |
+| 413    | Payload Too Large     | Request body too large            |
+| 422    | Unprocessable Entity  | Valid syntax but semantic errors  |
+| 429    | Too Many Requests     | Rate limit exceeded               |
+| 500    | Internal Server Error | Unexpected server errors          |
+| 502    | Bad Gateway           | Upstream server error             |
+| 503    | Service Unavailable   | Server temporarily unavailable    |
+| 504    | Gateway Timeout       | Upstream server timeout           |
 
 ## Best Practices
 

package/lib/llm/client.js

@@ -6,6 +6,7 @@
 
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
 const DEFAULT_MODEL = 'gpt-4o-mini';
+const DEFAULT_TIMEOUT = 10000;
 
 /**
  * OpenAI-compatible LLM provider. Exposes only constructor and analyze(prompt).
@@ -15,11 +16,16 @@ class LLMProvider {
     this.baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, '');
     this.model = options.model ?? DEFAULT_MODEL;
     this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+    this.timeout =
+      typeof options.timeout === 'number' && options.timeout > 0
+        ? options.timeout
+        : DEFAULT_TIMEOUT;
     this.options = options;
   }
 
   /**
    * Send a prompt to the LLM and return the raw text response and usage.
+   * Aborts after this.timeout milliseconds and throws a clean error.
    * @param {string} prompt
    * @returns {Promise<{ content: string, usage: { prompt_tokens: number, completion_tokens: number, total_tokens: number } }>}
    */
@@ -34,25 +40,44 @@ class LLMProvider {
       messages: [{ role: 'user', content: prompt }],
     };
 
-    const res = await fetch(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(body),
-    });
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    let res;
+    try {
+      res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        throw new Error(`LLM request timed out after ${this.timeout}ms`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutId);
+    }
 
     if (!res.ok) {
       const text = await res.text();
-      throw new Error(`LLM request failed (${res.status}): ${text.slice(0, 300)}`);
+      throw new Error(
+        `LLM request failed (${res.status}): ${text.slice(0, 300)}`,
+      );
     }
 
     const data = await res.json();
     const content = data.choices?.[0]?.message?.content ?? '';
-    const text = typeof content === 'string' ? content : JSON.stringify(content);
+    const text =
+      typeof content === 'string' ? content : JSON.stringify(content);
     const rawUsage = data.usage;
     const usage = {
       prompt_tokens: rawUsage?.prompt_tokens ?? 0,
       completion_tokens: rawUsage?.completion_tokens ?? 0,
-      total_tokens: rawUsage?.total_tokens ?? (rawUsage?.prompt_tokens ?? 0) + (rawUsage?.completion_tokens ?? 0),
+      total_tokens:
+        rawUsage?.total_tokens ??
+        (rawUsage?.prompt_tokens ?? 0) + (rawUsage?.completion_tokens ?? 0),
     };
     return { content: text, usage };
   }
@@ -60,7 +85,7 @@ class LLMProvider {
 
 /**
  * Create an LLM provider from config.
- * @param {object} config - { baseURL?, apiKey?, model? }
+ * @param {object} config - { baseURL?, apiKey?, model?, timeout? }
  * @returns {LLMProvider}
  */
 function createProvider(config) {

package/package.json

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

package/server/ammo.js

@@ -10,6 +10,11 @@ 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';
+import {
+  getChannels,
+  buildPayload,
+  dispatchToChannels,
+} from './errors/channels/index.js';
 
 /**
  * Detect if the value is a throw() options object (per-call overrides).
@@ -367,22 +372,84 @@ class Ammo {
     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());
+    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;
+    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.
+      // 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] instanceof Error && args[0].stack
           ? 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');
+
+        // Fire-and-forget: capture context, call LLM, dispatch to channel.
+        const method = this.method;
+        const path = this.path;
+        captureCodeContext(stack)
+          .then((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 }) => {
+            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(() => {
+            // Swallow background errors — the HTTP response has already been sent.
+          });
+
+        return;
+      }
+
+      // Sync mode (default): block until LLM responds, then fire.
       return captureCodeContext(stack)
         .then((codeContext) => {
           const context = {
@@ -390,9 +457,11 @@ class Ammo {
             method: this.method,
             path: this.path,
             includeDevInsight: true,
-            ...(throwOpts?.messageType && { messageType: throwOpts.messageType }),
+            ...(throwOpts?.messageType && {
+              messageType: throwOpts.messageType,
+            }),
           };
-          if (args[0] !== undefined && args[0] !== null) context.error = args[0];
+          if (originalError !== undefined) context.error = originalError;
           return inferErrorFromContext(context);
         })
         .then(({ statusCode, message, devInsight }) => {
@@ -402,6 +471,11 @@ class Ammo {
               ? { message, _dev: devInsight }
               : message;
           this.fire(statusCode, data);
+        })
+        .catch(() => {
+          // 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.
+          this.fire(500, 'Internal Server Error');
         });
     }
 

package/server/errors/channels/base.js

@@ -0,0 +1,31 @@
+/**
+ * Base class for LLM error output channels.
+ * Subclasses implement dispatch() to send the LLM result wherever needed.
+ */
+
+/**
+ * @typedef {object} ChannelPayload
+ * @property {string} timestamp - ISO 8601 timestamp of when the error occurred
+ * @property {string} method - HTTP method (e.g. GET, POST)
+ * @property {string} path - Request path
+ * @property {number} statusCode - LLM-inferred HTTP status code
+ * @property {string} message - LLM-inferred message
+ * @property {string} [devInsight] - Developer insight from LLM (always included in async mode)
+ * @property {{ type: string, message: string } | null} error - Original error summary
+ * @property {{ snippets: Array<{ file: string, line: number, snippet: string }> }} codeContext - Source context
+ * @property {boolean} [cached] - Whether this result came from the cache
+ * @property {boolean} [rateLimited] - Whether LLM was skipped due to rate limiting
+ */
+
+export class ErrorChannel {
+  /**
+   * Dispatch an LLM error result to this channel.
+   * @param {ChannelPayload} payload
+   * @returns {Promise<void>}
+   */
+  async dispatch(payload) {
+    throw new Error(
+      `dispatch() must be implemented by ${this.constructor.name}`,
+    );
+  }
+}