avantgate 2.2.0 → 2.4.0

package/dist/index.mjs

@@ -9,15 +9,22 @@ import {
   defineWorkflow,
   executeWorkflow,
   isWorkflowAbortSignal
-} from "./chunk-AH5XXSS4.mjs";
+} from "./chunk-KEJ4VNSN.mjs";
 import {
   sanitizePII
-} from "./chunk-W27A25DK.mjs";
+} from "./chunk-B22KKIQQ.mjs";
 import {
   __require
 } from "./chunk-Y6FXYEAI.mjs";
 
 // src/types.ts
+import { z } from "zod";
+var ChatRoleSchema = z.enum(["system", "user", "assistant", "tool"]);
+var ChatMessageSchema = z.object({
+  role: ChatRoleSchema,
+  content: z.string().min(1, "Message content cannot be empty")
+}).strict();
+var ChatMessagesArraySchema = z.array(ChatMessageSchema);
 var ConfigurationError = class extends Error {
   constructor(message) {
     super(message);
@@ -30,6 +37,22 @@ var BudgetExceededError = class extends Error {
     this.name = "BudgetExceededError";
   }
 };
+var ProviderTTFTTimeoutError = class extends Error {
+  ttftTimeoutMs;
+  constructor(message, ttftTimeoutMs) {
+    super(message);
+    this.name = "ProviderTTFTTimeoutError";
+    this.ttftTimeoutMs = ttftTimeoutMs;
+  }
+};
+var ProviderIdleTimeoutError = class extends Error {
+  idleTimeoutMs;
+  constructor(message, idleTimeoutMs) {
+    super(message);
+    this.name = "ProviderIdleTimeoutError";
+    this.idleTimeoutMs = idleTimeoutMs;
+  }
+};
 var SecretLeakBlockedError = class extends Error {
   detections;
   constructor(message, detections) {
@@ -488,11 +511,15 @@ var HttpProviderClient = class {
   baseUrl;
   apiKey;
   providerType;
+  ttftTimeoutMs;
+  idleTimeoutMs;
   constructor(config) {
     this.providerType = config.provider;
     this.name = `${config.provider}-http`;
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl || DEFAULT_BASE_URLS[config.provider] || "https://api.openai.com/v1";
+    this.ttftTimeoutMs = config.ttftTimeoutMs ?? 15e3;
+    this.idleTimeoutMs = config.idleTimeoutMs ?? 5e3;
   }
   resolveEndpoint = () => {
     const trimmed = this.baseUrl.replace(/\/+$/, "");
@@ -514,7 +541,7 @@ var HttpProviderClient = class {
     }
     return headers;
   };
-  buildPayload = (options, model) => {
+  buildPayload = (options, model, stream = false) => {
     return {
       model,
       messages: options.messages.map((m) => ({
@@ -522,6 +549,7 @@ var HttpProviderClient = class {
         content: m.content
       })),
       temperature: options.temperature ?? 0.2,
+      stream,
       ...options.responseFormat ? { response_format: options.responseFormat } : {}
     };
   };
@@ -536,22 +564,101 @@ var HttpProviderClient = class {
       promptCacheHitTokens: usageData.prompt_tokens_details?.cached_tokens
     };
   };
+  readStreamWithHeartbeat = async (reader, controller) => {
+    const decoder = new TextDecoder();
+    let accumulatedText = "";
+    let isFirstTokenReceived = false;
+    let activeTimer = setTimeout(() => {
+      controller.abort();
+    }, this.ttftTimeoutMs);
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (controller.signal.aborted) {
+          throw new Error("Aborted");
+        }
+        if (done) {
+          if (activeTimer) clearTimeout(activeTimer);
+          break;
+        }
+        if (value && value.length > 0) {
+          if (activeTimer) clearTimeout(activeTimer);
+          if (!isFirstTokenReceived) {
+            isFirstTokenReceived = true;
+          }
+          activeTimer = setTimeout(() => {
+            controller.abort();
+            reader.cancel().catch(() => {
+            });
+          }, this.idleTimeoutMs);
+          accumulatedText += decoder.decode(value, { stream: true });
+        }
+      }
+    } catch (err) {
+      if (controller.signal.aborted) {
+        if (!isFirstTokenReceived) {
+          throw new ProviderTTFTTimeoutError(
+            `[AvantGate HTTP Provider ${this.providerType}] Time-to-First-Token (TTFT) timeout of ${this.ttftTimeoutMs}ms exceeded without receiving initial response bytes.`,
+            this.ttftTimeoutMs
+          );
+        }
+        throw new ProviderIdleTimeoutError(
+          `[AvantGate HTTP Provider ${this.providerType}] Idle read timeout of ${this.idleTimeoutMs}ms exceeded during stream generation.`,
+          this.idleTimeoutMs
+        );
+      }
+      throw err;
+    } finally {
+      if (activeTimer) clearTimeout(activeTimer);
+    }
+    return accumulatedText;
+  };
   complete = async (options) => {
     const endpoint = this.resolveEndpoint();
     const model = options.model ?? "default";
     const headers = this.buildHeaders();
     const body = JSON.stringify(this.buildPayload(options, model));
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers,
-      body
-    });
+    const abortController = new AbortController();
+    const ttftTimer = setTimeout(() => {
+      abortController.abort();
+    }, this.ttftTimeoutMs);
+    let response;
+    try {
+      response = await fetch(endpoint, {
+        method: "POST",
+        headers,
+        body,
+        signal: abortController.signal
+      });
+    } catch (err) {
+      if (abortController.signal.aborted) {
+        throw new ProviderTTFTTimeoutError(
+          `[AvantGate HTTP Provider ${this.providerType}] Time-to-First-Token (TTFT) timeout of ${this.ttftTimeoutMs}ms exceeded before receiving headers.`,
+          this.ttftTimeoutMs
+        );
+      }
+      throw err;
+    } finally {
+      clearTimeout(ttftTimer);
+    }
     if (!response.ok) {
       const errorText = await response.text();
       throw new Error(
         `[AvantGate HTTP Provider ${this.providerType}] HTTP ${response.status} ${response.statusText}: ${errorText}`
       );
     }
+    if (response.body) {
+      const reader = response.body.getReader();
+      const rawText = await this.readStreamWithHeartbeat(reader, abortController);
+      try {
+        const data2 = JSON.parse(rawText);
+        const text2 = data2.choices?.[0]?.message?.content ?? "";
+        const usage2 = this.extractUsage(data2.usage);
+        return { text: text2, usage: usage2 };
+      } catch {
+        return { text: rawText };
+      }
+    }
     const data = await response.json();
     const text = data.choices?.[0]?.message?.content ?? "";
     const usage = this.extractUsage(data.usage);
@@ -736,10 +843,168 @@ var applyOutputGuards = (rawOutput, options) => {
   };
 };
 
+// src/utils/immutability.ts
+var deepFreeze = (target, options, currentDepth = 0, visited = /* @__PURE__ */ new WeakSet()) => {
+  if (target === null || typeof target !== "object") {
+    return target;
+  }
+  if (visited.has(target)) {
+    return target;
+  }
+  const maxDepth = options?.maxDepth ?? 10;
+  if (Object.isFrozen(target) || currentDepth >= maxDepth) {
+    return target;
+  }
+  if (target instanceof Date || target instanceof RegExp || target instanceof Promise) {
+    return Object.freeze(target);
+  }
+  visited.add(target);
+  const values = Array.isArray(target) ? target : Object.values(target);
+  for (const value of values) {
+    if (value && typeof value === "object") {
+      deepFreeze(value, options, currentDepth + 1, visited);
+    }
+  }
+  return Object.freeze(target);
+};
+
+// src/errors.ts
+var MiddlewareTimeoutError = class extends Error {
+  middlewareName;
+  timeoutMs;
+  phase;
+  constructor(middlewareName, phase, timeoutMs) {
+    super(`Middleware "${middlewareName}" execution timed out during ${phase} after ${timeoutMs}ms.`);
+    this.name = "MiddlewareTimeoutError";
+    this.middlewareName = middlewareName;
+    this.phase = phase;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var InvalidMessageSchemaError = class extends Error {
+  middlewareName;
+  validationErrors;
+  constructor(middlewareName, validationErrors) {
+    super(`Middleware "${middlewareName}" returned an invalid messages payload failing ChatMessageSchema validation.`);
+    this.name = "InvalidMessageSchemaError";
+    this.middlewareName = middlewareName;
+    this.validationErrors = validationErrors;
+  }
+};
+var PromptInjectionError = class extends Error {
+  reason;
+  constructor(reason) {
+    super(`[AvantGate Security Guard] Request blocked: ${reason}`);
+    this.name = "PromptInjectionError";
+    this.reason = reason;
+  }
+};
+
+// src/middleware.ts
+var executeWithTimeout = async (action, timeoutMs, middlewareName, phase) => {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new MiddlewareTimeoutError(middlewareName, phase, timeoutMs));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([Promise.resolve(action()), timeoutPromise]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+};
+var validateReturnedMessages = (messages, middlewareName) => {
+  if (!messages) return;
+  const parseResult = ChatMessagesArraySchema.safeParse(messages);
+  if (!parseResult.success) {
+    throw new InvalidMessageSchemaError(middlewareName, parseResult.error.format());
+  }
+};
+var applySingleBeforeMiddleware = async (middleware, current, model, temperature, timeoutMs = 5e3) => {
+  if (!middleware.beforeRequest) return current;
+  const frozenMessages = deepFreeze([...current.messages]);
+  const frozenMetadata = current.metadata ? deepFreeze({ ...current.metadata }) : void 0;
+  const result = await executeWithTimeout(
+    () => middleware.beforeRequest({
+      messages: frozenMessages,
+      model,
+      temperature,
+      metadata: frozenMetadata
+    }),
+    timeoutMs,
+    middleware.name,
+    "beforeRequest"
+  );
+  if (!result) return current;
+  validateReturnedMessages(result.messages, middleware.name);
+  return {
+    messages: result.messages ?? current.messages,
+    shortCircuit: result.shortCircuit,
+    metadata: current.metadata
+  };
+};
+var executeBeforeRequestHooks = async (middlewares, context, timeoutMs = 5e3) => {
+  if (!middlewares || middlewares.length === 0) {
+    return { messages: context.messages, metadata: context.metadata };
+  }
+  let current = {
+    messages: context.messages,
+    metadata: context.metadata
+  };
+  for (const middleware of middlewares) {
+    current = await applySingleBeforeMiddleware(
+      middleware,
+      current,
+      context.model,
+      context.temperature,
+      timeoutMs
+    );
+    if (current.shortCircuit) return current;
+  }
+  return current;
+};
+var applySingleAfterMiddleware = async (middleware, current, baseContext, timeoutMs = 5e3) => {
+  if (!middleware.afterResponse) return current;
+  const frozenMetadata = current.metadata ? deepFreeze({ ...current.metadata }) : void 0;
+  const result = await executeWithTimeout(
+    () => middleware.afterResponse({
+      ...baseContext,
+      responseText: current.responseText,
+      metadata: frozenMetadata
+    }),
+    timeoutMs,
+    middleware.name,
+    "afterResponse"
+  );
+  if (!result) return current;
+  return {
+    responseText: result.responseText ?? current.responseText,
+    metadata: result.metadata ?? current.metadata
+  };
+};
+var executeAfterResponseHooks = async (middlewares, context, timeoutMs = 5e3) => {
+  if (!middlewares || middlewares.length === 0) {
+    return { responseText: context.responseText, metadata: context.metadata };
+  }
+  let current = {
+    responseText: context.responseText,
+    metadata: context.metadata
+  };
+  for (const middleware of middlewares) {
+    current = await applySingleAfterMiddleware(middleware, current, context, timeoutMs);
+  }
+  return current;
+};
+
 // src/control-layer.ts
 var AvantGateControlLayer = class {
   config;
   cachedPricingAdapter;
+  reservations = /* @__PURE__ */ new Map();
+  cachedProviderChain;
   constructor(config) {
     this.config = {
       ...config,
@@ -747,6 +1012,11 @@ var AvantGateControlLayer = class {
       fallback: this.resolveProviderConfig(config.fallback),
       emergencyFallback: this.resolveProviderConfig(config.emergencyFallback)
     };
+    this.cachedProviderChain = [
+      this.config.primary,
+      this.config.fallback,
+      this.config.emergencyFallback
+    ].filter((provider) => Boolean(provider?.client));
     if (config.pricingAdapter) {
       this.cachedPricingAdapter = new CachedPricingAdapter(
         config.pricingAdapter,
@@ -754,6 +1024,12 @@ var AvantGateControlLayer = class {
       );
     }
   }
+  getReservation = (id) => {
+    return this.reservations.get(id);
+  };
+  getAllReservations = () => {
+    return Array.from(this.reservations.values());
+  };
   resolveProviderConfig = (provider) => {
     if (!provider) return void 0;
     if (provider.client) return provider;
@@ -766,16 +1042,15 @@ var AvantGateControlLayer = class {
     return provider;
   };
   findProviderConfig = (provider, model) => {
-    const list = [this.config.primary, this.config.fallback, this.config.emergencyFallback].filter(
-      (p) => Boolean(p)
-    );
     if (provider) {
-      const matchProvider = list.find((p) => p.provider === provider);
-      if (matchProvider) return matchProvider;
+      if (this.config.primary.provider === provider) return this.config.primary;
+      if (this.config.fallback?.provider === provider) return this.config.fallback;
+      if (this.config.emergencyFallback?.provider === provider) return this.config.emergencyFallback;
     }
     if (model) {
-      const matchModel = list.find((p) => p.model === model);
-      if (matchModel) return matchModel;
+      if (this.config.primary.model === model) return this.config.primary;
+      if (this.config.fallback?.model === model) return this.config.fallback;
+      if (this.config.emergencyFallback?.model === model) return this.config.emergencyFallback;
     }
     return this.config.primary;
   };
@@ -794,7 +1069,7 @@ var AvantGateControlLayer = class {
       maxLength: this.config.security?.maxInputLength
     });
     if (!guard.valid) {
-      throw new Error(`[AvantGate Security Guard] Request blocked: ${guard.blockedReason}`);
+      throw new PromptInjectionError(guard.blockedReason ?? "Prompt injection detected");
     }
     let processed = userQuery;
     if (this.config.security?.customRedactionTerms && this.config.security.customRedactionTerms.length > 0) {
@@ -805,6 +1080,21 @@ var AvantGateControlLayer = class {
     }
     return processed;
   };
+  reScanMessagesAfterHooks = (originalMessages, updatedMessages) => {
+    if (this.config.reScanIngressAfterHooks === false || originalMessages === updatedMessages) {
+      return updatedMessages;
+    }
+    return updatedMessages.map((msg, idx) => {
+      const orig = originalMessages[idx];
+      if (orig && (orig === msg || orig.role === msg.role && orig.content === msg.content)) {
+        return msg;
+      }
+      return {
+        ...msg,
+        content: this.applySecurityGuards(msg.content)
+      };
+    });
+  };
   applyOutputSecurityGuards = (rawOutput) => {
     const isDlpEnabled = this.config.security?.outputDLP ?? this.config.security?.maskPII ?? false;
     const shouldCheckSecrets = this.config.security?.blockSecretLeaks ?? true;
@@ -820,33 +1110,79 @@ var AvantGateControlLayer = class {
     });
     return guardResult.text;
   };
-  checkPreflightBudget = async (estimatedPromptTokens, targetModel, provider) => {
-    if (this.config.maxTokenBudget !== void 0 && estimatedPromptTokens > this.config.maxTokenBudget) {
+  validateTokenBudget = (estimatedTokens) => {
+    if (this.config.maxTokenBudget !== void 0 && estimatedTokens > this.config.maxTokenBudget) {
       throw new BudgetExceededError(
-        `[AvantGate Budget Guard] Pre-flight token budget exceeded: estimated prompt (${estimatedPromptTokens} tokens) exceeds maxTokenBudget (${this.config.maxTokenBudget}).`
+        `[AvantGate Budget Guard] Pre-flight token budget exceeded: estimated prompt (${estimatedTokens} tokens) exceeds maxTokenBudget (${this.config.maxTokenBudget}).`
       );
     }
-    if (this.config.maxCostUSD !== void 0) {
-      const isLocalFree = provider === "ollama" || targetModel.toLowerCase().includes("ollama");
-      const providerCfg = this.findProviderConfig(provider, targetModel);
-      const price = await resolveModelPriceAsync(targetModel, {
-        provider: provider ?? providerCfg?.provider,
-        providerPricing: providerCfg?.pricing,
-        customPricing: this.config.customPricing,
-        adapter: this.cachedPricingAdapter
-      });
-      if (!isLocalFree && !price) {
-        throw new ConfigurationError(
-          `[AvantGate Configuration Error] 'maxCostUSD' was set to $${this.config.maxCostUSD}, but no pricing was configured for model '${targetModel}'. Please define pricing in ProviderConfig, customPricing, or via PricingAdapter.`
-        );
-      }
-      const estimatedPromptCost = this.calculateCost(targetModel, estimatedPromptTokens, 0, 0, provider);
-      if (estimatedPromptCost > this.config.maxCostUSD) {
-        throw new BudgetExceededError(
-          `[AvantGate Budget Guard] Pre-flight cost budget exceeded: estimated prompt cost ($${estimatedPromptCost.toFixed(6)}) exceeds maxCostUSD ($${this.config.maxCostUSD}).`
-        );
+  };
+  validatePricingConfigured = async (targetModel, provider) => {
+    const isLocalFree = provider === "ollama" || targetModel.toLowerCase().includes("ollama");
+    if (isLocalFree) return;
+    const providerCfg = this.findProviderConfig(provider, targetModel);
+    const price = await resolveModelPriceAsync(targetModel, {
+      provider: provider ?? providerCfg?.provider,
+      providerPricing: providerCfg?.pricing,
+      customPricing: this.config.customPricing,
+      adapter: this.cachedPricingAdapter
+    });
+    if (!price) {
+      throw new ConfigurationError(
+        `[AvantGate Configuration Error] 'maxCostUSD' was set to $${this.config.maxCostUSD}, but no pricing was configured for model '${targetModel}'. Please define pricing in ProviderConfig, customPricing, or via PricingAdapter.`
+      );
+    }
+  };
+  evaluatePessimisticSolvency = (estimatedPromptCost, parentRunId) => {
+    if (!parentRunId || this.config.maxCostUSD === void 0) return;
+    let hasUnconfirmed = false;
+    let settledSpend = 0;
+    for (const r of this.reservations.values()) {
+      if (r.parentRunId !== parentRunId) continue;
+      if (r.status === "UNCONFIRMED_TIMEOUT") hasUnconfirmed = true;
+      if (r.status === "SETTLED") {
+        settledSpend += r.settledCostUsd ?? r.estimatedCostUsd;
       }
     }
+    if (!hasUnconfirmed) return;
+    const totalWorstCaseCost = settledSpend + 2 * estimatedPromptCost;
+    if (totalWorstCaseCost > this.config.maxCostUSD) {
+      throw new BudgetExceededError(
+        `[AvantGate FinOps Guard] Retry rejected: worst-case cumulative spend ($${totalWorstCaseCost.toFixed(4)}) exceeds max budget ($${this.config.maxCostUSD.toFixed(4)}).`
+      );
+    }
+  };
+  createBudgetReservation = (estimatedCostUsd, parentRunId) => {
+    const reservationId = `res_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+    const reservation = {
+      id: reservationId,
+      parentRunId,
+      estimatedCostUsd,
+      status: "RESERVED",
+      createdAt: Date.now(),
+      updatedAt: Date.now()
+    };
+    if (this.reservations.size >= 1e4) {
+      const oldestKey = this.reservations.keys().next().value;
+      if (oldestKey) this.reservations.delete(oldestKey);
+    }
+    this.reservations.set(reservationId, reservation);
+    return reservation;
+  };
+  checkPreflightBudget = async (estimatedPromptTokens, targetModel, provider, parentRunId) => {
+    this.validateTokenBudget(estimatedPromptTokens);
+    if (this.config.maxCostUSD === void 0) {
+      return void 0;
+    }
+    await this.validatePricingConfigured(targetModel, provider);
+    const estimatedPromptCost = this.calculateCost(targetModel, estimatedPromptTokens, 0, 0, provider);
+    this.evaluatePessimisticSolvency(estimatedPromptCost, parentRunId);
+    if (estimatedPromptCost > this.config.maxCostUSD) {
+      throw new BudgetExceededError(
+        `[AvantGate Budget Guard] Pre-flight cost budget exceeded: estimated prompt cost ($${estimatedPromptCost.toFixed(6)}) exceeds maxCostUSD ($${this.config.maxCostUSD}).`
+      );
+    }
+    return this.createBudgetReservation(estimatedPromptCost, parentRunId);
   };
   checkPostExecutionBudget = (tokensTotal, costUSD) => {
     if (this.config.maxTokenBudget !== void 0 && tokensTotal > this.config.maxTokenBudget) {
@@ -880,11 +1216,7 @@ var AvantGateControlLayer = class {
     };
   };
   getProviderChain = () => {
-    return [
-      this.config.primary,
-      this.config.fallback,
-      this.config.emergencyFallback
-    ].filter((provider) => Boolean(provider?.client));
+    return this.cachedProviderChain;
   };
   executeSimulation = (query, systemPrompt, modelOverride) => {
     const targetModel = modelOverride ?? this.config.primary.model;
@@ -979,28 +1311,140 @@ var AvantGateControlLayer = class {
       attempts: result.attempts
     });
   };
-  execute = async (options) => {
-    const sanitizedQuery = this.applySecurityGuards(options.userQuery);
-    const messages = this.buildMessages(options.systemPrompt, sanitizedQuery);
-    const promptLength = (options.systemPrompt?.length ?? 0) + sanitizedQuery.length;
-    const estimatedPromptTokens = Math.ceil(promptLength / 4);
-    await this.checkPreflightBudget(estimatedPromptTokens, this.config.primary.model, this.config.primary.provider);
-    if (!options.providerOverride && this.getProviderChain().length === 0) {
+  prepareInputMessages = (options) => {
+    if (options.messages && options.messages.length > 0) {
+      return this.sanitizeIncomingMessages(options.messages);
+    }
+    if (options.userQuery !== void 0) {
+      const sanitizedQuery = this.applySecurityGuards(options.userQuery);
+      return this.buildMessages(options.systemPrompt, sanitizedQuery);
+    }
+    throw new ConfigurationError("[AvantGate Input Guard] Either 'userQuery' or 'messages' must be provided.");
+  };
+  handleShortCircuit = async (shortCircuit, targetModel) => {
+    const sanitizedText = this.applyOutputSecurityGuards(shortCircuit.text);
+    const result = {
+      text: sanitizedText,
+      tokens: {
+        prompt: shortCircuit.tokens?.promptTokens ?? 0,
+        completion: shortCircuit.tokens?.completionTokens ?? 0,
+        total: shortCircuit.tokens?.totalTokens ?? 0
+      },
+      costUSD: shortCircuit.costUSD ?? 0,
+      modelUsed: `${targetModel}:shortcircuit`,
+      failoverOccurred: false,
+      attempts: 0
+    };
+    await this.notifyAuditSink(result);
+    return result;
+  };
+  dispatchPromptExecution = async (messages, temperature, providerOverride) => {
+    const query = messages[messages.length - 1]?.content ?? "";
+    if (providerOverride) {
+      return this.executeOverrideProvider(providerOverride, messages, query, temperature);
+    }
+    if (this.getProviderChain().length === 0) {
       if (this.config.mockSimulation) {
-        const simResult = this.executeSimulation(sanitizedQuery, options.systemPrompt);
-        await this.notifyAuditSink(simResult);
-        return simResult;
+        const sim = this.executeSimulation(query);
+        return {
+          responseText: sim.text,
+          usage: { promptTokens: sim.tokens.prompt, completionTokens: sim.tokens.completion, totalTokens: sim.tokens.total },
+          modelUsed: sim.modelUsed,
+          failoverOccurred: false,
+          attempts: 1
+        };
       }
       throw new ConfigurationError(
         "[AvantGate Configuration Error] No active LLM provider configured. Provide a client implementing LLMProviderPort or configure credentials (apiKey / baseUrl)."
       );
     }
-    const output = options.providerOverride ? await this.executeOverrideProvider(options.providerOverride, messages, sanitizedQuery, options.temperature) : await this.executeProviderPipeline(messages, sanitizedQuery, options.temperature);
-    const result = this.assembleResult(output);
-    this.checkPostExecutionBudget(result.tokens.total, result.costUSD);
+    return this.executeProviderPipeline(messages, query, temperature);
+  };
+  finalizeExecutionResult = async (output, responseText) => {
+    const sanitizedText = this.applyOutputSecurityGuards(responseText);
+    const hitTokens = output.usage.promptCacheHitTokens ?? 0;
+    const costUSD = this.calculateCost(output.modelUsed, output.usage.promptTokens, output.usage.completionTokens, hitTokens);
+    this.checkPostExecutionBudget(output.usage.totalTokens, costUSD);
+    const tokens = { prompt: output.usage.promptTokens, completion: output.usage.completionTokens, total: output.usage.totalTokens };
+    const result = {
+      text: sanitizedText,
+      tokens,
+      costUSD,
+      modelUsed: output.modelUsed,
+      failoverOccurred: output.failoverOccurred,
+      attempts: output.attempts
+    };
     await this.notifyAuditSink(result);
     return result;
   };
+  runAfterHooks = async (beforeState, output) => {
+    const tokens = { prompt: output.usage.promptTokens, completion: output.usage.completionTokens, total: output.usage.totalTokens };
+    const costUSD = this.calculateCost(output.modelUsed, output.usage.promptTokens, output.usage.completionTokens);
+    return executeAfterResponseHooks(
+      this.config.middlewares,
+      {
+        messages: beforeState.messages,
+        responseText: output.responseText,
+        modelUsed: output.modelUsed,
+        tokens,
+        costUSD,
+        attempts: output.attempts,
+        failoverOccurred: output.failoverOccurred,
+        metadata: beforeState.metadata
+      },
+      this.config.middlewareTimeoutMs ?? 5e3
+    );
+  };
+  verifyPromptBudget = async (messages, model, parentRunId) => {
+    const promptLength = messages.reduce((sum, msg) => sum + msg.content.length, 0);
+    const estimatedPromptTokens = Math.ceil(promptLength / 4);
+    return this.checkPreflightBudget(estimatedPromptTokens, model, void 0, parentRunId);
+  };
+  execute = async (options) => {
+    const inputMessages = this.prepareInputMessages(options);
+    const beforeState = await executeBeforeRequestHooks(
+      this.config.middlewares,
+      {
+        messages: inputMessages,
+        model: this.config.primary.model,
+        temperature: options.temperature,
+        metadata: options.metadata
+      },
+      this.config.middlewareTimeoutMs ?? 5e3
+    );
+    if (beforeState.shortCircuit) {
+      return this.handleShortCircuit(beforeState.shortCircuit, this.config.primary.model);
+    }
+    beforeState.messages = this.reScanMessagesAfterHooks(inputMessages, beforeState.messages);
+    const parentRunId = beforeState.metadata?.parentRunId ?? options.metadata?.parentRunId;
+    const reservation = await this.verifyPromptBudget(beforeState.messages, this.config.primary.model, parentRunId);
+    let output;
+    try {
+      output = await this.dispatchPromptExecution(beforeState.messages, options.temperature, options.providerOverride);
+    } catch (err) {
+      if (reservation) {
+        const errorMsg = String(err);
+        const isClientError = errorMsg.includes("HTTP 400") || errorMsg.includes("HTTP 401") || errorMsg.includes("HTTP 403") || errorMsg.includes("HTTP 422");
+        if (isClientError) {
+          reservation.status = "RELEASED";
+          reservation.updatedAt = Date.now();
+        } else {
+          reservation.status = "UNCONFIRMED_TIMEOUT";
+          reservation.updatedAt = Date.now();
+        }
+      }
+      throw err;
+    }
+    const afterState = await this.runAfterHooks(beforeState, output);
+    const finalResult = await this.finalizeExecutionResult(output, afterState.responseText);
+    if (reservation) {
+      reservation.status = "SETTLED";
+      reservation.settledCostUsd = finalResult.costUSD;
+      reservation.updatedAt = Date.now();
+    }
+    return finalResult;
+  };
+  executePrompt = this.execute;
   executeStructured = async (options) => {
     const rawResult = await this.execute({
       userQuery: options.userQuery,
@@ -1032,11 +1476,6 @@ var AvantGateControlLayer = class {
       return msg;
     });
   };
-  verifyPromptBudget = async (messages, model) => {
-    const promptLength = messages.reduce((sum, msg) => sum + msg.content.length, 0);
-    const estimatedPromptTokens = Math.ceil(promptLength / 4);
-    await this.checkPreflightBudget(estimatedPromptTokens, model);
-  };
   dispatchOverrideAttempt = async (override, messages, model, temperature) => {
     const res = await override.complete({ model, messages, temperature: temperature ?? 0.1 });
     const usage = this.resolveTokens(res.usage, JSON.stringify(messages), res.text);
@@ -1135,28 +1574,60 @@ var AvantGateControlLayer = class {
     const delay = initialDelay * Math.pow(factor, attempt);
     await new Promise((resolve) => setTimeout(resolve, delay));
   };
-  generateStructuredOutput = async (options) => {
-    const maxRetries = options.maxRetries ?? this.config.retryOptions?.maxRetries ?? 2;
-    const targetModel = options.model ?? this.config.primary.model;
-    const processedMessages = this.sanitizeIncomingMessages(options.messages);
-    await this.verifyPromptBudget(processedMessages, targetModel);
+  handleStructuredShortCircuit = async (shortCircuit, options, targetModel) => {
+    const { parsedData, sanitizedResponse } = this.parseAndValidateStructuredResult(
+      shortCircuit.text,
+      options
+    );
+    const tokens = {
+      prompt: shortCircuit.tokens?.promptTokens ?? 0,
+      completion: shortCircuit.tokens?.completionTokens ?? 0,
+      total: shortCircuit.tokens?.totalTokens ?? 0
+    };
+    const result = {
+      data: parsedData,
+      rawText: sanitizedResponse,
+      tokens,
+      costUSD: shortCircuit.costUSD ?? 0,
+      modelUsed: `${targetModel}:shortcircuit`,
+      failoverOccurred: false
+    };
+    await this.notifyAuditSinkSafe(sanitizedResponse, result, 0);
+    return result;
+  };
+  runStructuredAfterHooks = async (messages, output, attempt) => {
+    const tokens = { prompt: output.promptTokens, completion: output.completionTokens, total: output.promptTokens + output.completionTokens };
+    const costUSD = this.calculateCost(output.modelUsed, output.promptTokens, output.completionTokens);
+    return executeAfterResponseHooks(
+      this.config.middlewares,
+      {
+        messages,
+        responseText: output.responseText,
+        modelUsed: output.modelUsed,
+        tokens,
+        costUSD,
+        attempts: attempt,
+        failoverOccurred: output.failoverOccurred
+      },
+      this.config.middlewareTimeoutMs ?? 5e3
+    );
+  };
+  executeStructuredLoop = async (options, messages, targetModel, maxRetries) => {
     let lastError;
-    let accumulatedPromptTokens = 0;
-    let accumulatedCompletionTokens = 0;
+    let accPrompt = 0;
+    let accComp = 0;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
-        const output = await this.dispatchProviderAttempt(options, processedMessages, targetModel);
-        accumulatedPromptTokens += output.promptTokens;
-        accumulatedCompletionTokens += output.completionTokens;
-        const { parsedData, sanitizedResponse } = this.parseAndValidateStructuredResult(
-          output.responseText,
-          options
-        );
+        const output = await this.dispatchProviderAttempt(options, messages, targetModel);
+        accPrompt += output.promptTokens;
+        accComp += output.completionTokens;
+        const afterState = await this.runStructuredAfterHooks(messages, output, attempt + 1);
+        const { parsedData, sanitizedResponse } = this.parseAndValidateStructuredResult(afterState.responseText, options);
         const result = this.buildStructuredResult({
           data: parsedData,
           rawText: sanitizedResponse,
-          promptTokens: accumulatedPromptTokens,
-          completionTokens: accumulatedCompletionTokens,
+          promptTokens: accPrompt,
+          completionTokens: accComp,
           modelUsed: output.modelUsed,
           failoverOccurred: output.failoverOccurred
         });
@@ -1169,6 +1640,47 @@ var AvantGateControlLayer = class {
     }
     throw lastError;
   };
+  generateStructuredOutput = async (options) => {
+    const maxRetries = options.maxRetries ?? this.config.retryOptions?.maxRetries ?? 2;
+    const targetModel = options.model ?? this.config.primary.model;
+    const processedMessages = this.sanitizeIncomingMessages(options.messages);
+    const beforeState = await executeBeforeRequestHooks(
+      this.config.middlewares,
+      {
+        messages: processedMessages,
+        model: targetModel,
+        temperature: options.temperature
+      },
+      this.config.middlewareTimeoutMs ?? 5e3
+    );
+    if (beforeState.shortCircuit) {
+      return this.handleStructuredShortCircuit(beforeState.shortCircuit, options, targetModel);
+    }
+    beforeState.messages = this.reScanMessagesAfterHooks(processedMessages, beforeState.messages);
+    const reservation = await this.verifyPromptBudget(beforeState.messages, targetModel);
+    try {
+      const result = await this.executeStructuredLoop(options, beforeState.messages, targetModel, maxRetries);
+      if (reservation) {
+        reservation.status = "SETTLED";
+        reservation.settledCostUsd = result.costUSD;
+        reservation.updatedAt = Date.now();
+      }
+      return result;
+    } catch (err) {
+      if (reservation) {
+        const errorMsg = String(err);
+        const isClientError = errorMsg.includes("HTTP 400") || errorMsg.includes("HTTP 401") || errorMsg.includes("HTTP 403") || errorMsg.includes("HTTP 422");
+        if (isClientError) {
+          reservation.status = "RELEASED";
+          reservation.updatedAt = Date.now();
+        } else {
+          reservation.status = "UNCONFIRMED_TIMEOUT";
+          reservation.updatedAt = Date.now();
+        }
+      }
+      throw err;
+    }
+  };
 };
 var createLLMControlLayer = (config) => {
   return new AvantGateControlLayer(config);
@@ -1256,7 +1768,7 @@ var PromptTemplate = class {
 };
 
 // src/prompts/prompt-builder.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 var PromptBuilder = class {
   personaSlot = "";
   rulesSlot = [];
@@ -1312,7 +1824,7 @@ var PromptBuilder = class {
   }
   schemaContract(schema, options) {
     let shapeDescription = "JSON Object";
-    if (schema instanceof z.ZodObject) {
+    if (schema instanceof z2.ZodObject) {
       shapeDescription = JSON.stringify(Object.keys(schema.shape));
     }
     this.schemaContractText = [
@@ -1489,6 +2001,73 @@ var PromptRegistry = class {
     this.registry.clear();
   }
 };
+
+// src/presets.ts
+var createLaunchSafeConfig = (options) => {
+  const defaultSecurity = {
+    detectPromptInjection: true,
+    maskPII: true,
+    outputDLP: true,
+    blockSecretLeaks: true,
+    secretLeakAction: "REDACT"
+  };
+  const defaultRetries = { maxRetries: 2, initialDelayMs: 300, backoffFactor: 1.5 };
+  return {
+    maxTokenBudget: 8192,
+    maxCostUSD: 0.5,
+    middlewareTimeoutMs: 5e3,
+    reScanIngressAfterHooks: true,
+    ...options,
+    retryOptions: { ...defaultRetries, ...options.retryOptions },
+    security: { ...defaultSecurity, ...options.security }
+  };
+};
+var createEnterpriseStrictConfig = (options) => {
+  const defaultSecurity = {
+    detectPromptInjection: true,
+    maskPII: true,
+    outputDLP: true,
+    blockSecretLeaks: true,
+    secretLeakAction: "BLOCK"
+  };
+  const defaultRetries = {
+    maxRetries: 3,
+    initialDelayMs: 500,
+    backoffFactor: 2
+  };
+  return {
+    maxTokenBudget: 4096,
+    maxCostUSD: 0.15,
+    middlewareTimeoutMs: 3e3,
+    reScanIngressAfterHooks: true,
+    ...options,
+    retryOptions: { ...defaultRetries, ...options.retryOptions },
+    security: { ...defaultSecurity, ...options.security }
+  };
+};
+var createDevPermissiveConfig = (options) => {
+  const defaultSecurity = {
+    detectPromptInjection: false,
+    maskPII: false,
+    outputDLP: false,
+    blockSecretLeaks: false
+  };
+  const defaultRetries = {
+    maxRetries: 1,
+    initialDelayMs: 200,
+    backoffFactor: 1
+  };
+  return {
+    ...options,
+    retryOptions: { ...defaultRetries, ...options.retryOptions },
+    security: { ...defaultSecurity, ...options.security }
+  };
+};
+var PRESETS = {
+  LAUNCH_SAFE: createLaunchSafeConfig,
+  ENTERPRISE_STRICT: createEnterpriseStrictConfig,
+  DEV_PERMISSIVE: createDevPermissiveConfig
+};
 export {
   BudgetExceededError as AvantGateBudgetExceededError,
   ConfigurationError as AvantGateConfigurationError,
@@ -1496,13 +2075,22 @@ export {
   SecretLeakBlockedError as AvantGateSecretLeakBlockedError,
   BudgetExceededError,
   CachedPricingAdapter,
+  ChatMessageSchema,
+  ChatMessagesArraySchema,
+  ChatRoleSchema,
   ConfigurationError,
   DEFAULT_MODEL_PRICES,
   HttpProviderClient,
+  InvalidMessageSchemaError,
+  MiddlewareTimeoutError,
+  PRESETS,
   PricingRegistry,
   PromptBuilder,
+  PromptInjectionError,
   PromptRegistry,
   PromptTemplate,
+  ProviderIdleTimeoutError,
+  ProviderTTFTTimeoutError,
   SEED_MODEL_PRICES,
   SecretLeakBlockedError,
   SqlitePricingAdapter,
@@ -1511,11 +2099,19 @@ export {
   WorkflowValidationError,
   AvantGateControlLayer as ZenLLMControlLayer,
   applyOutputGuards,
+  applySingleAfterMiddleware,
+  applySingleBeforeMiddleware,
   calculateCostUSD,
   createAvantGate,
+  createDevPermissiveConfig,
+  createEnterpriseStrictConfig,
   createHttpProviderClient,
   createLLMControlLayer,
+  createLaunchSafeConfig,
+  deepFreeze,
   defineWorkflow,
+  executeAfterResponseHooks,
+  executeBeforeRequestHooks,
   executeWorkflow,
   extractAndCleanJSON,
   isWorkflowAbortSignal,