elsium-ai 0.2.2 → 0.2.3

package/dist/index.js

@@ -491,7 +491,16 @@ function envBool(name, fallback) {
   const raw = getEnvVar(name);
   if (raw !== undefined) {
     const normalized = raw.toLowerCase();
-    return normalized === "true" || normalized === "1" || normalized === "yes";
+    if (normalized === "true" || normalized === "1" || normalized === "yes")
+      return true;
+    if (normalized === "false" || normalized === "0" || normalized === "no")
+      return false;
+    throw new ElsiumError({
+      code: "CONFIG_ERROR",
+      message: `Environment variable ${name} has unrecognized boolean value: ${raw}. Expected one of: true, false, 1, 0, yes, no`,
+      retryable: false,
+      metadata: { variable: name, value: raw }
+    });
   }
   if (fallback !== undefined)
     return fallback;
@@ -630,6 +639,101 @@ function createCircuitBreaker(config) {
     }
   };
 }
+// ../core/src/shutdown.ts
+function createShutdownManager(config) {
+  const drainTimeoutMs = config?.drainTimeoutMs ?? 30000;
+  const signals = config?.signals ?? ["SIGTERM", "SIGINT"];
+  if (drainTimeoutMs < 0 || !Number.isFinite(drainTimeoutMs)) {
+    throw new ElsiumError({
+      code: "CONFIG_ERROR",
+      message: "drainTimeoutMs must be >= 0 and finite",
+      retryable: false
+    });
+  }
+  let shuttingDown = false;
+  let inFlightCount = 0;
+  let drainResolve = null;
+  let shutdownPromise = null;
+  const signalHandlers = [];
+  function checkDrained() {
+    if (inFlightCount === 0 && drainResolve) {
+      drainResolve();
+      drainResolve = null;
+    }
+  }
+  async function shutdown() {
+    if (shutdownPromise)
+      return shutdownPromise;
+    shuttingDown = true;
+    shutdownPromise = (async () => {
+      config?.onDrainStart?.();
+      if (inFlightCount === 0) {
+        config?.onDrainComplete?.();
+        return;
+      }
+      const drainPromise = new Promise((resolve) => {
+        drainResolve = resolve;
+      });
+      let drainTimer;
+      const timeoutPromise = new Promise((resolve) => {
+        drainTimer = setTimeout(() => resolve("timeout"), drainTimeoutMs);
+      });
+      const result = await Promise.race([
+        drainPromise.then(() => "drained"),
+        timeoutPromise
+      ]);
+      if (drainTimer !== undefined)
+        clearTimeout(drainTimer);
+      if (result === "timeout") {
+        config?.onForceShutdown?.();
+      } else {
+        config?.onDrainComplete?.();
+      }
+    })();
+    return shutdownPromise;
+  }
+  const manager = {
+    get inFlight() {
+      return inFlightCount;
+    },
+    get isShuttingDown() {
+      return shuttingDown;
+    },
+    async trackOperation(fn) {
+      if (shuttingDown) {
+        throw new ElsiumError({
+          code: "VALIDATION_ERROR",
+          message: "Server is shutting down, not accepting new operations",
+          retryable: true
+        });
+      }
+      inFlightCount++;
+      try {
+        return await fn();
+      } finally {
+        inFlightCount--;
+        checkDrained();
+      }
+    },
+    shutdown,
+    dispose() {
+      for (const { signal, handler } of signalHandlers) {
+        process.removeListener(signal, handler);
+      }
+      signalHandlers.length = 0;
+    }
+  };
+  if (typeof process !== "undefined" && process.on) {
+    for (const signal of signals) {
+      const handler = () => {
+        manager.shutdown();
+      };
+      signalHandlers.push({ signal, handler });
+      process.on(signal, handler);
+    }
+  }
+  return manager;
+}
 // ../gateway/src/provider.ts
 var providerRegistry = new Map;
 var metadataRegistry = new Map;
@@ -1262,7 +1366,19 @@ function createGoogleProvider(config) {
     return { role, parts };
   }
   function formatGeminiMultipartContent(msg, role) {
-    const parts = msg.content.filter((p) => p.type === "text").map((p) => ({ text: p.text }));
+    const parts = [];
+    for (const p of msg.content) {
+      if (p.type === "text") {
+        parts.push({ text: p.text });
+      } else if (p.type === "image") {
+        const img = p;
+        if (img.source.type === "base64") {
+          parts.push({ inlineData: { mimeType: img.source.mediaType, data: img.source.data } });
+        } else {
+          parts.push({ fileData: { mimeType: "image/jpeg", fileUri: img.source.url } });
+        }
+      }
+    }
     return { role, parts };
   }
   function formatMessages(messages) {
@@ -1437,7 +1553,8 @@ async function handleGoogleErrorResponse(response) {
     throw ElsiumError.authError("google");
   }
   if (response.status === 429) {
-    throw ElsiumError.rateLimit("google");
+    const retryAfter = response.headers.get("retry-after");
+    throw ElsiumError.rateLimit("google", retryAfter ? Number.parseInt(retryAfter) * 1000 : undefined);
   }
   throw ElsiumError.providerError(`Google API error ${response.status}: ${errorBody}`, {
     provider: "google",
@@ -1623,6 +1740,24 @@ function createOpenAIProvider(config) {
     }
     return openaiMsg;
   }
+  function formatUserContent(msg) {
+    if (typeof msg.content === "string")
+      return msg.content;
+    const parts = [];
+    for (const part of msg.content) {
+      if (part.type === "text") {
+        parts.push({ type: "text", text: part.text });
+      } else if (part.type === "image") {
+        if (part.source.type === "base64") {
+          const url = `data:${part.source.mediaType};base64,${part.source.data}`;
+          parts.push({ type: "image_url", image_url: { url } });
+        } else {
+          parts.push({ type: "image_url", image_url: { url: part.source.url } });
+        }
+      }
+    }
+    return parts;
+  }
   function formatMessages(messages) {
     const formatted = [];
     for (const msg of messages) {
@@ -1638,7 +1773,7 @@ function createOpenAIProvider(config) {
         formatted.push(formatAssistantMessage(msg));
         continue;
       }
-      formatted.push({ role: "user", content: extractTextContent(msg) });
+      formatted.push({ role: "user", content: formatUserContent(msg) });
     }
     return formatted;
   }
@@ -1877,7 +2012,7 @@ var PROVIDER_FACTORIES = {
 function registerProviderFactory(name, factory) {
   PROVIDER_FACTORIES[name] = factory;
 }
-function gateway(config) {
+function validateGatewayConfig(config) {
   const factory = PROVIDER_FACTORIES[config.provider];
   if (!factory) {
     throw new ElsiumError({
@@ -1886,21 +2021,92 @@ function gateway(config) {
       retryable: false
     });
   }
+  if (typeof config.apiKey !== "string" || config.apiKey.trim() === "") {
+    throw new ElsiumError({
+      code: "CONFIG_ERROR",
+      message: "apiKey must be a non-empty string",
+      retryable: false
+    });
+  }
+  if (config.timeout !== undefined && (!Number.isFinite(config.timeout) || config.timeout <= 0)) {
+    throw new ElsiumError({
+      code: "CONFIG_ERROR",
+      message: "timeout must be a positive finite number",
+      retryable: false
+    });
+  }
+  if (config.maxRetries !== undefined && (!Number.isFinite(config.maxRetries) || !Number.isInteger(config.maxRetries) || config.maxRetries < 0)) {
+    throw new ElsiumError({
+      code: "CONFIG_ERROR",
+      message: "maxRetries must be a non-negative finite integer",
+      retryable: false
+    });
+  }
+  return factory;
+}
+function autoRegisterProvider(provider) {
+  if (!provider.metadata)
+    return;
+  registerProviderMetadata(provider.name, provider.metadata);
+  if (!provider.metadata.pricing)
+    return;
+  for (const [model, pricing] of Object.entries(provider.metadata.pricing)) {
+    registerPricing(model, pricing);
+  }
+}
+function validateRequestLimits(request, maxMessages, maxInputTokens) {
+  if (request.messages.length > maxMessages) {
+    throw ElsiumError.validation(`Message count ${request.messages.length} exceeds limit of ${maxMessages}`);
+  }
+  let estimatedTokens = 0;
+  for (const msg of request.messages) {
+    const text = typeof msg.content === "string" ? msg.content : msg.content.map((p) => p.type === "text" ? p.text : "").join("");
+    estimatedTokens += Math.ceil(text.length / 4);
+  }
+  if (estimatedTokens > maxInputTokens) {
+    throw ElsiumError.validation(`Estimated input tokens (~${estimatedTokens}) exceeds limit of ${maxInputTokens}`);
+  }
+}
+function buildMiddlewareContext(req, providerName, defaultModel, metadata) {
+  return {
+    request: req,
+    provider: providerName,
+    model: req.model ?? defaultModel,
+    traceId: generateTraceId(),
+    startTime: performance.now(),
+    metadata
+  };
+}
+async function accumulateStreamEvents(stream, emit) {
+  let textContent = "";
+  let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+  let stopReason = "end_turn";
+  let id = "";
+  for await (const event of stream) {
+    emit(event);
+    if (event.type === "text_delta") {
+      textContent += event.text;
+    } else if (event.type === "message_end") {
+      usage = event.usage;
+      stopReason = event.stopReason;
+    } else if (event.type === "message_start") {
+      id = event.id;
+    }
+  }
+  return { textContent, usage, stopReason, id };
+}
+function gateway(config) {
+  const factory = validateGatewayConfig(config);
   const provider = factory({
     apiKey: config.apiKey,
     baseUrl: config.baseUrl,
     timeout: config.timeout,
     maxRetries: config.maxRetries
   });
-  if (provider.metadata) {
-    registerProviderMetadata(provider.name, provider.metadata);
-    if (provider.metadata.pricing) {
-      for (const [model, pricing] of Object.entries(provider.metadata.pricing)) {
-        registerPricing(model, pricing);
-      }
-    }
-  }
+  autoRegisterProvider(provider);
   const defaultModel = config.model ?? provider.defaultModel;
+  const maxMessages = config.maxMessages ?? 1000;
+  const maxInputTokens = config.maxInputTokens ?? 1e6;
   let xrayStore = null;
   const allMiddleware = [...config.middleware ?? []];
   if (config.xray) {
@@ -1915,14 +2121,7 @@ function gateway(config) {
     if (!composedMiddleware) {
       return provider.complete(req);
     }
-    const ctx = {
-      request: req,
-      provider: provider.name,
-      model: req.model ?? defaultModel,
-      traceId: generateTraceId(),
-      startTime: performance.now(),
-      metadata: request.metadata ?? {}
-    };
+    const ctx = buildMiddlewareContext(req, provider.name, defaultModel, request.metadata ?? {});
     return composedMiddleware(ctx, async (c) => provider.complete(c.request));
   }
   return {
@@ -1934,34 +2133,27 @@ function gateway(config) {
       return xrayStore?.callHistory(limit) ?? [];
     },
     async complete(request) {
+      validateRequestLimits(request, maxMessages, maxInputTokens);
       return executeWithMiddleware(request);
     },
     stream(request) {
+      validateRequestLimits(request, maxMessages, maxInputTokens);
       const req = { ...request, model: request.model ?? defaultModel };
       if (composedMiddleware) {
-        const ctx = {
-          request: req,
-          provider: provider.name,
-          model: req.model ?? defaultModel,
-          traceId: generateTraceId(),
-          startTime: performance.now(),
-          metadata: request.metadata ?? {}
-        };
+        const ctx = buildMiddlewareContext(req, provider.name, defaultModel, request.metadata ?? {});
         return createStream(async (emit) => {
           await composedMiddleware(ctx, async (c) => {
-            const stream = provider.stream(c.request);
-            for await (const event of stream) {
-              emit(event);
-            }
+            const result = await accumulateStreamEvents(provider.stream(c.request), emit);
+            const latencyMs = Math.round(performance.now() - ctx.startTime);
             return {
-              id: "",
-              message: { role: "assistant", content: "" },
-              usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
-              cost: { inputCost: 0, outputCost: 0, totalCost: 0, currency: "USD" },
+              id: result.id,
+              message: { role: "assistant", content: result.textContent },
+              usage: result.usage,
+              cost: calculateCost(c.model, result.usage),
               model: c.model,
               provider: provider.name,
-              stopReason: "end_turn",
-              latencyMs: 0,
+              stopReason: result.stopReason,
+              latencyMs,
               traceId: ctx.traceId
             };
           });
@@ -2300,6 +2492,12 @@ function redactResponseSecrets(response, config) {
 }
 function securityMiddleware(config) {
   return async (ctx, next) => {
+    if (ctx.request.system) {
+      const sysViolations = scanMessageForViolations(ctx.request.system, config);
+      if (sysViolations.length > 0) {
+        reportAndThrow(sysViolations, config);
+      }
+    }
     for (const message of ctx.request.messages) {
       const text = extractText(message.content);
       if (!text)
@@ -2544,7 +2742,22 @@ function createProviderMesh(config) {
       const available = sortedProviders.find((e) => isProviderAvailable(e.name));
       const entry = available ?? sortedProviders[0];
       const gw = getGateway(entry.name);
-      return gw.stream({ ...request, model: request.model ?? entry.model });
+      let resolvedStream = null;
+      callWithCircuitBreaker(entry.name, () => {
+        resolvedStream = gw.stream({ ...request, model: request.model ?? entry.model });
+        return Promise.resolve(resolvedStream);
+      }).catch(() => {});
+      if (resolvedStream === null) {
+        const err2 = new ElsiumError({
+          code: "PROVIDER_ERROR",
+          message: "Circuit breaker is open",
+          retryable: true
+        });
+        return new ElsiumStream(async function* () {
+          yield { type: "error", error: err2 };
+        }());
+      }
+      return resolvedStream;
     }
   };
 }
@@ -2709,6 +2922,18 @@ function zodToJsonSchema(schema) {
 }
 // ../tools/src/toolkit.ts
 function createToolkit(name, tools) {
+  const seen = new Set;
+  for (const tool of tools) {
+    if (seen.has(tool.name)) {
+      throw new ElsiumError({
+        code: "CONFIG_ERROR",
+        message: `Duplicate tool name "${tool.name}" in toolkit "${name}"`,
+        retryable: false,
+        metadata: { toolkit: name, tool: tool.name }
+      });
+    }
+    seen.add(tool.name);
+  }
   const toolMap = new Map(tools.map((t) => [t.name, t]));
   return {
     name,
@@ -6727,7 +6952,26 @@ var coerce = {
 };
 var NEVER = INVALID;
 // ../tools/src/builtin.ts
-var BLOCKED_HOSTS = /^(localhost|127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|192\.168\.\d+\.\d+|169\.254\.\d+\.\d+|0\.0\.0\.0|0+\.0+\.0+\.0+|\[::1\]|\[::ffff:127\.\d+\.\d+\.\d+\]|::ffff:127\.\d+\.\d+\.\d+|0177\.\d+\.\d+\.\d+|2130706433|\[fd[0-9a-f]{2}:)/i;
+var BLOCKED_HOSTS = /^(localhost|127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|192\.168\.\d+\.\d+|169\.254\.\d+\.\d+|0\.0\.0\.0|0+\.0+\.0+\.0+|\[?::1\]?|\[?::ffff:127\.\d+\.\d+\.\d+\]?|\[?::ffff:10\.\d+\.\d+\.\d+\]?|\[?::ffff:192\.168\.\d+\.\d+\]?|\[?::ffff:172\.(1[6-9]|2\d|3[01])\.\d+\.\d+\]?|::ffff:127\.\d+\.\d+\.\d+|0177\.\d+\.\d+\.\d+|2130706433|\[?::\]?|\[?f[cd][0-9a-f]{2}:|\[?fe80:)/i;
+var BLOCKED_HEADER_NAMES = new Set([
+  "cookie",
+  "set-cookie",
+  "authorization",
+  "proxy-authorization",
+  "host",
+  "x-api-key",
+  "x-forwarded-for",
+  "x-real-ip"
+]);
+function sanitizeHeaders(headers) {
+  const safe = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (!BLOCKED_HEADER_NAMES.has(key.toLowerCase())) {
+      safe[key] = value;
+    }
+  }
+  return safe;
+}
 function validateUrl(urlString) {
   const parsed = new URL(urlString);
   if (!["http:", "https:"].includes(parsed.protocol)) {
@@ -6752,8 +6996,9 @@ var httpFetchTool = defineTool({
   timeoutMs: 15000,
   handler: async ({ url, headers }, context) => {
     validateUrl(url);
+    const safeHeaders = headers ? sanitizeHeaders(headers) : undefined;
     const response = await fetch(url, {
-      headers,
+      headers: safeHeaders,
       signal: context.signal,
       redirect: "manual"
     });
@@ -7421,9 +7666,9 @@ Only respond with JSON, nothing else.`
     if (!parsed) {
       return null;
     }
-    const score = parsed.score ?? 0.5;
+    const score = typeof parsed.score === "number" ? parsed.score : 0.5;
     const threshold = config.hallucination?.threshold ?? 0.7;
-    const claims = parsed.hallucinated_claims ?? [];
+    const claims = Array.isArray(parsed.hallucinated_claims) ? parsed.hallucinated_claims : [];
     return {
       passed: score >= threshold,
       score,
@@ -7486,12 +7731,12 @@ Only respond with JSON, nothing else.`
     if (!parsed) {
       return null;
     }
-    const score = parsed.score ?? 0.5;
+    const score = typeof parsed.score === "number" ? parsed.score : 0.5;
     const threshold = config.relevance?.threshold ?? 0.5;
     return {
       passed: score >= threshold,
       score,
-      reason: parsed.reason ?? (score >= threshold ? "Output is relevant" : "Output lacks relevance")
+      reason: typeof parsed.reason === "string" ? parsed.reason : score >= threshold ? "Output is relevant" : "Output lacks relevance"
     };
   }
   function checkRelevanceHeuristic(input, output) {
@@ -7543,8 +7788,8 @@ Only respond with JSON, nothing else.`
     if (!parsed) {
       return null;
     }
-    const score = parsed.score ?? 0.5;
-    const claims = parsed.ungrounded_claims ?? [];
+    const score = typeof parsed.score === "number" ? parsed.score : 0.5;
+    const claims = Array.isArray(parsed.ungrounded_claims) ? parsed.ungrounded_claims : [];
     return {
       passed: score >= 0.7,
       score,
@@ -7605,16 +7850,23 @@ Only respond with JSON, nothing else.`
 }
 
 // ../agents/src/state-machine.ts
+async function safeHook(fn) {
+  if (!fn)
+    return;
+  try {
+    await fn();
+  } catch (_) {}
+}
 function executeStateMachine(baseConfig, stateConfig, deps, input, options) {
   return runStateMachine(baseConfig, stateConfig, deps, input, options ?? {});
 }
-function handleToolCallsAndContinue(response, toolMap, toolCallHistory, conversationMessages, signal) {
+function handleToolCallsAndContinue(response, toolMap, toolCallHistory, conversationMessages, signal, hooks, approvalGate, approvalConfig) {
   const toolCalls = response.message.toolCalls;
   if (!toolCalls?.length || response.stopReason !== "tool_use") {
     return null;
   }
   return (async () => {
-    const toolResults = await executeToolCalls(toolCalls, toolMap, toolCallHistory, signal);
+    const toolResults = await executeToolCalls(toolCalls, toolMap, toolCallHistory, signal, hooks, approvalGate, approvalConfig);
     const toolMessage = {
       role: "tool",
       content: "",
@@ -7718,6 +7970,7 @@ async function runStateMachine(baseConfig, stateConfig, deps, input, options) {
     });
   }
   const agentSecurity = baseConfig.guardrails?.security ? createAgentSecurity(baseConfig.guardrails.security) : null;
+  const approvalGate = baseConfig.guardrails?.approval ? createApprovalGate(baseConfig.guardrails.approval) : null;
   const maxTokenBudget = guardrails?.maxTokenBudget ?? 500000;
   const outputValidator = guardrails?.outputValidator ?? (() => true);
   const conversationMessages = [{ role: "user", content: input }];
@@ -7735,7 +7988,8 @@ async function runStateMachine(baseConfig, stateConfig, deps, input, options) {
     checkTokenBudget(totalInputTokens + totalOutputTokens, maxTokenBudget);
     response = applyOutputGuardrails(response, outputValidator, agentSecurity);
     conversationMessages.push(response.message);
-    const toolCallAction = handleToolCallsAndContinue(response, toolMap, toolCallHistory, conversationMessages, options.signal);
+    await safeHook(() => baseConfig.hooks?.onMessage?.(response.message));
+    const toolCallAction = handleToolCallsAndContinue(response, toolMap, toolCallHistory, conversationMessages, options.signal, baseConfig.hooks, approvalGate, baseConfig.guardrails);
     if (toolCallAction) {
       await toolCallAction;
       continue;
@@ -7756,9 +8010,30 @@ async function runStateMachine(baseConfig, stateConfig, deps, input, options) {
     metadata: { iterations, maxIterations, lastState: currentStateName }
   });
 }
-async function executeToolCalls(toolCalls, toolMap, history, signal) {
+async function executeToolCalls(toolCalls, toolMap, history, signal, hooks, approvalGate, approvalConfig) {
   const results = [];
   for (const tc of toolCalls) {
+    await safeHook(() => hooks?.onToolCall?.({ name: tc.name, arguments: tc.arguments }));
+    if (approvalGate && shouldRequireApproval(approvalConfig?.approval?.requireApprovalFor, {
+      toolName: tc.name
+    })) {
+      const decision = await approvalGate.requestApproval("tool_call", `Execute tool: ${tc.name}`, {
+        toolName: tc.name,
+        arguments: tc.arguments
+      });
+      if (!decision.approved) {
+        const deniedResult = {
+          success: false,
+          error: `Tool call denied: ${decision.reason ?? "Approval denied"}`,
+          toolCallId: tc.id,
+          durationMs: 0
+        };
+        await safeHook(() => hooks?.onToolResult?.(deniedResult));
+        history.push({ name: tc.name, arguments: tc.arguments, result: deniedResult });
+        results.push(formatToolResult(deniedResult));
+        continue;
+      }
+    }
     const tool = toolMap.get(tc.name);
     if (!tool) {
       const errorResult = {
@@ -7767,11 +8042,13 @@ async function executeToolCalls(toolCalls, toolMap, history, signal) {
         toolCallId: tc.id,
         durationMs: 0
       };
+      await safeHook(() => hooks?.onToolResult?.(errorResult));
       history.push({ name: tc.name, arguments: tc.arguments, result: errorResult });
       results.push(formatToolResult(errorResult));
       continue;
     }
     const result = await tool.execute(tc.arguments, { toolCallId: tc.id, signal });
+    await safeHook(() => hooks?.onToolResult?.(result));
     history.push({ name: tc.name, arguments: tc.arguments, result });
     results.push(formatToolResult(result));
   }
@@ -7779,7 +8056,7 @@ async function executeToolCalls(toolCalls, toolMap, history, signal) {
 }
 
 // ../agents/src/agent.ts
-async function safeHook(fn) {
+async function safeHook2(fn) {
   if (!fn)
     return;
   try {
@@ -7885,7 +8162,7 @@ function defineAgent(config, deps) {
       traceId,
       confidence
     };
-    await safeHook(() => config.hooks?.onComplete?.(agentResult));
+    await safeHook2(() => config.hooks?.onComplete?.(agentResult));
     return { action: "return", result: agentResult };
   }
   function checkBudget(totalInputTokens, totalOutputTokens) {
@@ -7943,7 +8220,7 @@ function defineAgent(config, deps) {
       totalInputTokens += response.usage.inputTokens;
       totalOutputTokens += response.usage.outputTokens;
       totalCost += response.cost.totalCost;
-      await safeHook(() => config.hooks?.onMessage?.(response.message));
+      await safeHook2(() => config.hooks?.onMessage?.(response.message));
       conversationMessages.push(response.message);
       if (!response.message.toolCalls?.length || response.stopReason !== "tool_use") {
         const result = await handleNonToolResponse(response, messages, iterations, totalInputTokens, totalOutputTokens, totalCost, toolCallHistory, traceId, conversationMessages);
@@ -7971,7 +8248,7 @@ function defineAgent(config, deps) {
   async function executeToolCalls2(toolCalls, history, options = {}) {
     const results = [];
     for (const tc of toolCalls) {
-      await safeHook(() => config.hooks?.onToolCall?.({ name: tc.name, arguments: tc.arguments }));
+      await safeHook2(() => config.hooks?.onToolCall?.({ name: tc.name, arguments: tc.arguments }));
       if (approvalGate && shouldRequireApproval(config.guardrails?.approval?.requireApprovalFor, {
         toolName: tc.name
       })) {
@@ -7983,7 +8260,7 @@ function defineAgent(config, deps) {
             toolCallId: tc.id,
             durationMs: 0
           };
-          await safeHook(() => config.hooks?.onToolResult?.(deniedResult));
+          await safeHook2(() => config.hooks?.onToolResult?.(deniedResult));
           history.push({ name: tc.name, arguments: tc.arguments, result: deniedResult });
           results.push(formatToolResult(deniedResult));
           continue;
@@ -7997,7 +8274,7 @@ function defineAgent(config, deps) {
           toolCallId: tc.id,
           durationMs: 0
         };
-        await safeHook(() => config.hooks?.onToolResult?.(errorResult));
+        await safeHook2(() => config.hooks?.onToolResult?.(errorResult));
         history.push({ name: tc.name, arguments: tc.arguments, result: errorResult });
         results.push(formatToolResult(errorResult));
         continue;
@@ -8006,7 +8283,7 @@ function defineAgent(config, deps) {
         toolCallId: tc.id,
         signal: options.signal
       });
-      await safeHook(() => config.hooks?.onToolResult?.(result));
+      await safeHook2(() => config.hooks?.onToolResult?.(result));
       history.push({ name: tc.name, arguments: tc.arguments, result });
       results.push(formatToolResult(result));
     }
@@ -9267,6 +9544,7 @@ function createCostEngine(config = {}) {
   };
 }
 // ../observe/src/tracer.ts
+import { writeFileSync } from "node:fs";
 var log3 = createLogger();
 function observe(config = {}) {
   const {
@@ -9282,7 +9560,21 @@ function observe(config = {}) {
   for (const out of output) {
     if (out === "console") {
       handlers.push(consoleHandler);
-    } else if (out === "json-file") {} else {
+    } else if (out === "json-file") {
+      exporters.push({
+        name: "json-file",
+        export(spansToExport) {
+          const filename = `.elsium/traces-${Date.now()}.json`;
+          try {
+            writeFileSync(filename, JSON.stringify(spansToExport, null, 2));
+          } catch (err2) {
+            log3.error("Failed to write trace file", {
+              error: err2 instanceof Error ? err2.message : String(err2)
+            });
+          }
+        }
+      });
+    } else {
       exporters.push(out);
     }
   }
@@ -9617,6 +9909,16 @@ function createOTLPExporter(config) {
       } else {
         startAutoFlush();
       }
+    },
+    async shutdown() {
+      if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+      }
+      if (buffer.length > 0) {
+        const batch = buffer.splice(0, buffer.length);
+        await sendBatch(batch);
+      }
     }
   };
 }
@@ -11692,7 +11994,7 @@ var Hono2 = class extends Hono {
 // ../app/src/middleware.ts
 import { timingSafeEqual } from "node:crypto";
 function corsMiddleware(config = true) {
-  const opts = typeof config === "boolean" ? { origin: [], methods: ["GET", "POST", "OPTIONS"] } : config;
+  const opts = typeof config === "boolean" ? { origin: "*", methods: ["GET", "POST", "OPTIONS"] } : config;
   return async (c, next) => {
     const requestOrigin = c.req.header("Origin") ?? "";
     let allowedOrigin;
@@ -11769,8 +12071,51 @@ function rateLimitMiddleware(config) {
     await next();
   };
 }
+function requestIdMiddleware() {
+  return async (c, next) => {
+    const raw2 = c.req.header("X-Request-ID");
+    const id = raw2 && /^[\w\-.:]{1,128}$/.test(raw2) ? raw2 : generateId("req");
+    c.set("requestId", id);
+    await next();
+    c.res.headers.set("X-Request-ID", id);
+  };
+}
+function requestLoggerMiddleware(logger) {
+  const log5 = logger ?? createLogger();
+  return async (c, next) => {
+    const start = Date.now();
+    await next();
+    const duration = Date.now() - start;
+    log5.info(`${c.req.method} ${c.req.path}`, {
+      method: c.req.method,
+      path: c.req.path,
+      status: c.res.status,
+      durationMs: duration,
+      requestId: c.get("requestId")
+    });
+  };
+}
 
 // ../app/src/routes.ts
+function parseJsonBody(raw2) {
+  try {
+    return { ok: true, data: JSON.parse(raw2) };
+  } catch {
+    return { ok: false };
+  }
+}
+function elsiumErrorResponse(c, err2, fallbackMessage) {
+  if (err2 instanceof ElsiumError) {
+    return c.json({ error: err2.message, code: err2.code }, err2.statusCode ?? 500);
+  }
+  return c.json({ error: fallbackMessage }, 500);
+}
+function resolveAgent(name, agents, defaultAgent) {
+  const agent = name ? agents.get(name) : defaultAgent;
+  if (agent)
+    return { agent };
+  return { error: name ? `Agent "${name}" not found` : "No default agent configured" };
+}
 function createRoutes(deps) {
   const app = new Hono2;
   let totalRequests = 0;
@@ -11811,17 +12156,24 @@ function createRoutes(deps) {
     if (rawText.length > MAX_BODY_SIZE) {
       return c.json({ error: "Request body too large (max 1MB)" }, 413);
     }
-    const body = JSON.parse(rawText);
+    const parsed = parseJsonBody(rawText);
+    if (!parsed.ok) {
+      return c.json({ error: "Invalid JSON in request body" }, 400);
+    }
+    const body = parsed.data;
     if (!body.message) {
       return c.json({ error: "message is required" }, 400);
     }
-    const agent = body.agent ? deps.agents.get(body.agent) : deps.defaultAgent;
-    if (!agent) {
-      return c.json({
-        error: body.agent ? `Agent "${body.agent}" not found` : "No default agent configured"
-      }, 404);
+    const resolved = resolveAgent(body.agent, deps.agents, deps.defaultAgent);
+    if ("error" in resolved) {
+      return c.json({ error: resolved.error }, 404);
+    }
+    let result;
+    try {
+      result = await resolved.agent.run(body.message);
+    } catch (err2) {
+      return elsiumErrorResponse(c, err2, "Agent execution failed");
     }
-    const result = await agent.run(body.message);
     deps.tracer?.trackLLMCall({
       model: "unknown",
       inputTokens: result.usage.totalInputTokens,
@@ -11838,7 +12190,7 @@ function createRoutes(deps) {
         totalTokens: result.usage.totalTokens,
         cost: result.usage.totalCost
       },
-      model: agent.config.model ?? "default",
+      model: resolved.agent.config.model ?? "default",
       traceId: result.traceId
     };
     return c.json(response);
@@ -11850,7 +12202,11 @@ function createRoutes(deps) {
     if (rawText.length > MAX_BODY_SIZE) {
       return c.json({ error: "Request body too large (max 1MB)" }, 413);
     }
-    const body = JSON.parse(rawText);
+    const parsed = parseJsonBody(rawText);
+    if (!parsed.ok) {
+      return c.json({ error: "Invalid JSON in request body" }, 400);
+    }
+    const body = parsed.data;
     if (!body.messages?.length) {
       return c.json({ error: "messages array is required" }, 400);
     }
@@ -11858,13 +12214,18 @@ function createRoutes(deps) {
       role: m.role,
       content: m.content
     }));
-    const response = await deps.gateway.complete({
-      messages,
-      model: body.model,
-      system: body.system,
-      maxTokens: body.maxTokens,
-      temperature: body.temperature
-    });
+    let response;
+    try {
+      response = await deps.gateway.complete({
+        messages,
+        model: body.model,
+        system: body.system,
+        maxTokens: body.maxTokens,
+        temperature: body.temperature
+      });
+    } catch (err2) {
+      return elsiumErrorResponse(c, err2, "Completion failed");
+    }
     deps.tracer?.trackLLMCall({
       model: response.model,
       inputTokens: response.usage.inputTokens,
@@ -11896,6 +12257,15 @@ function createRoutes(deps) {
 var log5 = createLogger();
 function createApp(config) {
   const app = new Hono2;
+  app.onError((err2, c) => {
+    const statusCode = err2 instanceof ElsiumError ? err2.statusCode ?? 500 : 500;
+    const code = err2 instanceof ElsiumError ? err2.code : "UNKNOWN";
+    log5.error("Unhandled error", { error: err2.message, code, path: c.req.path });
+    return c.json({ error: err2.message, code }, statusCode);
+  });
+  app.notFound((c) => {
+    return c.json({ error: "Not found" }, 404);
+  });
   const providerNames = Object.keys(config.gateway.providers);
   const primaryProvider = providerNames[0];
   const primaryConfig = config.gateway.providers[primaryProvider];
@@ -11910,6 +12280,8 @@ function createApp(config) {
     costTracking: config.observe?.costTracking ?? true
   });
   const serverConfig = config.server ?? {};
+  app.use("*", requestIdMiddleware());
+  app.use("*", requestLoggerMiddleware(log5));
   if (serverConfig.cors) {
     app.use("*", corsMiddleware(serverConfig.cors));
   }
@@ -11932,7 +12304,7 @@ function createApp(config) {
     defaultAgent,
     tracer,
     startTime: Date.now(),
-    version: "0.1.0",
+    version: config.version ?? "0.2.2",
     providers: providerNames
   });
   app.route("/", routes);
@@ -11948,13 +12320,25 @@ function createApp(config) {
         port: listenPort,
         hostname
       });
+      let shutdownManager;
+      if (serverConfig.gracefulShutdown) {
+        const drainTimeoutMs = typeof serverConfig.gracefulShutdown === "object" ? serverConfig.gracefulShutdown.drainTimeoutMs : undefined;
+        shutdownManager = createShutdownManager({
+          drainTimeoutMs,
+          onDrainStart: () => log5.info("Draining connections..."),
+          onDrainComplete: () => log5.info("Drain complete")
+        });
+      }
       log5.info("ElsiumAI server started", {
         url: `http://${hostname}:${listenPort}`,
         routes: ["POST /chat", "POST /complete", "GET /health", "GET /metrics", "GET /agents"]
       });
       return {
         port: listenPort,
-        stop: () => {
+        stop: async () => {
+          if (shutdownManager) {
+            await shutdownManager.shutdown();
+          }
           server.close();
         }
       };
@@ -12965,7 +13349,7 @@ function createPromptRegistry() {
   };
 }
 // ../testing/src/regression.ts
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname } from "node:path";
 function makeEmptyResult(name) {
   return {
@@ -13050,7 +13434,7 @@ function createRegressionSuite(name) {
         };
       }
       mkdirSync(dirname(path), { recursive: true });
-      writeFileSync(path, JSON.stringify(baseline, null, 2));
+      writeFileSync2(path, JSON.stringify(baseline, null, 2));
     },
     addCase(input, output, score) {
       if (!baseline) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "elsium-ai",
-	"version": "0.2.2",
+	"version": "0.2.3",
 	"description": "ElsiumAI — A high-performance, TypeScript-first AI framework",
 	"license": "MIT",
 	"author": "Eric Utrera <ebutrera9103@gmail.com>",
@@ -25,16 +25,16 @@
 		"build": "bun build ./src/index.ts --outdir ./dist --target node && bun x tsc -p tsconfig.build.json --emitDeclarationOnly"
 	},
 	"dependencies": {
-		"@elsium-ai/core": "^0.2.2",
-		"@elsium-ai/gateway": "^0.2.2",
-		"@elsium-ai/agents": "^0.2.2",
-		"@elsium-ai/tools": "^0.2.2",
-		"@elsium-ai/rag": "^0.2.2",
-		"@elsium-ai/workflows": "^0.2.2",
-		"@elsium-ai/observe": "^0.2.2",
-		"@elsium-ai/app": "^0.2.2",
-		"@elsium-ai/testing": "^0.2.2",
-		"@elsium-ai/mcp": "^0.2.2"
+		"@elsium-ai/core": "^0.2.3",
+		"@elsium-ai/gateway": "^0.2.3",
+		"@elsium-ai/agents": "^0.2.3",
+		"@elsium-ai/tools": "^0.2.3",
+		"@elsium-ai/rag": "^0.2.3",
+		"@elsium-ai/workflows": "^0.2.3",
+		"@elsium-ai/observe": "^0.2.3",
+		"@elsium-ai/app": "^0.2.3",
+		"@elsium-ai/testing": "^0.2.3",
+		"@elsium-ai/mcp": "^0.2.3"
 	},
 	"devDependencies": {
 		"typescript": "^5.7.0"