avantgate 2.3.0 → 2.4.0

package/dist/index.js

@@ -36,14 +36,22 @@ __export(index_exports, {
   AvantGateSecretLeakBlockedError: () => SecretLeakBlockedError,
   BudgetExceededError: () => BudgetExceededError,
   CachedPricingAdapter: () => CachedPricingAdapter,
+  ChatMessageSchema: () => ChatMessageSchema,
+  ChatMessagesArraySchema: () => ChatMessagesArraySchema,
+  ChatRoleSchema: () => ChatRoleSchema,
   ConfigurationError: () => ConfigurationError,
   DEFAULT_MODEL_PRICES: () => DEFAULT_MODEL_PRICES,
   HttpProviderClient: () => HttpProviderClient,
+  InvalidMessageSchemaError: () => InvalidMessageSchemaError,
+  MiddlewareTimeoutError: () => MiddlewareTimeoutError,
   PRESETS: () => PRESETS,
   PricingRegistry: () => PricingRegistry,
   PromptBuilder: () => PromptBuilder,
+  PromptInjectionError: () => PromptInjectionError,
   PromptRegistry: () => PromptRegistry,
   PromptTemplate: () => PromptTemplate,
+  ProviderIdleTimeoutError: () => ProviderIdleTimeoutError,
+  ProviderTTFTTimeoutError: () => ProviderTTFTTimeoutError,
   SEED_MODEL_PRICES: () => SEED_MODEL_PRICES,
   SecretLeakBlockedError: () => SecretLeakBlockedError,
   SqlitePricingAdapter: () => SqlitePricingAdapter,
@@ -61,6 +69,7 @@ __export(index_exports, {
   createHttpProviderClient: () => createHttpProviderClient,
   createLLMControlLayer: () => createLLMControlLayer,
   createLaunchSafeConfig: () => createLaunchSafeConfig,
+  deepFreeze: () => deepFreeze,
   defineWorkflow: () => defineWorkflow,
   executeAfterResponseHooks: () => executeAfterResponseHooks,
   executeBeforeRequestHooks: () => executeBeforeRequestHooks,
@@ -78,6 +87,13 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
+var import_zod = require("zod");
+var ChatRoleSchema = import_zod.z.enum(["system", "user", "assistant", "tool"]);
+var ChatMessageSchema = import_zod.z.object({
+  role: ChatRoleSchema,
+  content: import_zod.z.string().min(1, "Message content cannot be empty")
+}).strict();
+var ChatMessagesArraySchema = import_zod.z.array(ChatMessageSchema);
 var ConfigurationError = class extends Error {
   constructor(message) {
     super(message);
@@ -90,6 +106,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) {
@@ -1107,11 +1139,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(/\/+$/, "");
@@ -1133,7 +1169,7 @@ var HttpProviderClient = class {
     }
     return headers;
   };
-  buildPayload = (options, model) => {
+  buildPayload = (options, model, stream = false) => {
     return {
       model,
       messages: options.messages.map((m) => ({
@@ -1141,6 +1177,7 @@ var HttpProviderClient = class {
         content: m.content
       })),
       temperature: options.temperature ?? 0.2,
+      stream,
       ...options.responseFormat ? { response_format: options.responseFormat } : {}
     };
   };
@@ -1155,22 +1192,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);
@@ -1355,23 +1471,110 @@ 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 applySingleBeforeMiddleware = async (middleware, current, model, temperature) => {
-  if (!middleware.beforeRequest) return current;
-  const result = await middleware.beforeRequest({
-    messages: current.messages,
-    model,
-    temperature,
-    metadata: current.metadata
+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) => {
+var executeBeforeRequestHooks = async (middlewares, context, timeoutMs = 5e3) => {
   if (!middlewares || middlewares.length === 0) {
     return { messages: context.messages, metadata: context.metadata };
   }
@@ -1380,25 +1583,37 @@ var executeBeforeRequestHooks = async (middlewares, context) => {
     metadata: context.metadata
   };
   for (const middleware of middlewares) {
-    current = await applySingleBeforeMiddleware(middleware, current, context.model, context.temperature);
+    current = await applySingleBeforeMiddleware(
+      middleware,
+      current,
+      context.model,
+      context.temperature,
+      timeoutMs
+    );
     if (current.shortCircuit) return current;
   }
   return current;
 };
-var applySingleAfterMiddleware = async (middleware, current, baseContext) => {
+var applySingleAfterMiddleware = async (middleware, current, baseContext, timeoutMs = 5e3) => {
   if (!middleware.afterResponse) return current;
-  const result = await middleware.afterResponse({
-    ...baseContext,
-    responseText: current.responseText,
-    metadata: current.metadata
-  });
+  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) => {
+var executeAfterResponseHooks = async (middlewares, context, timeoutMs = 5e3) => {
   if (!middlewares || middlewares.length === 0) {
     return { responseText: context.responseText, metadata: context.metadata };
   }
@@ -1407,7 +1622,7 @@ var executeAfterResponseHooks = async (middlewares, context) => {
     metadata: context.metadata
   };
   for (const middleware of middlewares) {
-    current = await applySingleAfterMiddleware(middleware, current, context);
+    current = await applySingleAfterMiddleware(middleware, current, context, timeoutMs);
   }
   return current;
 };
@@ -1416,6 +1631,8 @@ var executeAfterResponseHooks = async (middlewares, context) => {
 var AvantGateControlLayer = class {
   config;
   cachedPricingAdapter;
+  reservations = /* @__PURE__ */ new Map();
+  cachedProviderChain;
   constructor(config) {
     this.config = {
       ...config,
@@ -1423,6 +1640,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,
@@ -1430,6 +1652,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;
@@ -1442,16 +1670,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;
   };
@@ -1470,7 +1697,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) {
@@ -1481,6 +1708,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;
@@ -1496,33 +1738,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) {
@@ -1556,11 +1844,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;
@@ -1724,32 +2008,69 @@ var AvantGateControlLayer = class {
   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
-    });
+    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
-    });
+    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);
     }
-    await this.verifyPromptBudget(beforeState.messages, this.config.primary.model);
-    const output = await this.dispatchPromptExecution(beforeState.messages, options.temperature, options.providerOverride);
+    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);
-    return this.finalizeExecutionResult(output, afterState.responseText);
+    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) => {
@@ -1783,11 +2104,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);
@@ -1910,15 +2226,19 @@ var AvantGateControlLayer = class {
   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
-    });
+    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;
@@ -1952,16 +2272,42 @@ var AvantGateControlLayer = class {
     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
-    });
+    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);
     }
-    await this.verifyPromptBudget(beforeState.messages, targetModel);
-    return this.executeStructuredLoop(options, beforeState.messages, targetModel, maxRetries);
+    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) => {
@@ -2050,7 +2396,7 @@ var PromptTemplate = class {
 };
 
 // src/prompts/prompt-builder.ts
-var import_zod = require("zod");
+var import_zod2 = require("zod");
 var PromptBuilder = class {
   personaSlot = "";
   rulesSlot = [];
@@ -2106,7 +2452,7 @@ var PromptBuilder = class {
   }
   schemaContract(schema, options) {
     let shapeDescription = "JSON Object";
-    if (schema instanceof import_zod.z.ZodObject) {
+    if (schema instanceof import_zod2.z.ZodObject) {
       shapeDescription = JSON.stringify(Object.keys(schema.shape));
     }
     this.schemaContractText = [
@@ -2335,6 +2681,25 @@ var DtoValidationError = class extends Error {
     this.issues = issues;
   }
 };
+var AmbiguousToolExecutionError = class extends Error {
+  toolCallId;
+  toolName;
+  impact;
+  originalError;
+  constructor(details, toolName, impact) {
+    const isStr = typeof details === "string";
+    const callId = isStr ? details : details.toolCallId;
+    const name = isStr ? toolName : details.toolName;
+    const imp = isStr ? impact ?? "MUTATIVE" : details.impact ?? "MUTATIVE";
+    const msg = isStr ? "" : details.message ? `: ${details.message}` : "";
+    super(`Ambiguous tool execution detected for [${name || "tool"}::${callId}] (${imp})${msg}. Re-execution blocked without reconciliation.`);
+    this.name = "AmbiguousToolExecutionError";
+    this.toolCallId = callId;
+    this.toolName = name;
+    this.impact = imp;
+    this.originalError = isStr ? void 0 : details.originalError;
+  }
+};
 
 // src/agent/guardrails.ts
 function sanitizeString(value) {
@@ -2388,16 +2753,220 @@ function auditToolResult(data, options) {
   };
 }
 
+// src/agent/tool-resilience.ts
+var MAX_FALLBACK_CAP = 1e3;
+var inMemoryFallbackStore = /* @__PURE__ */ new Map();
+var setFallbackRecord = (toolCallId, record) => {
+  if (inMemoryFallbackStore.size >= MAX_FALLBACK_CAP) {
+    const firstKey = inMemoryFallbackStore.keys().next().value;
+    if (firstKey) inMemoryFallbackStore.delete(firstKey);
+  }
+  inMemoryFallbackStore.set(toolCallId, record);
+};
+var isDeterministicClientError = (error) => {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const err = error;
+  const status = Number(err.status ?? err.statusCode);
+  if (status >= 400 && status < 500 && status !== 408 && status !== 429) {
+    return true;
+  }
+  return err.name === "DtoValidationError" || err.name === "ToolAccessDeniedError";
+};
+var isAmbiguousTimeoutError = (error, isTimedOut) => {
+  if (isTimedOut) return true;
+  if (!error || typeof error !== "object") return false;
+  const err = error;
+  const name = String(err.name ?? "");
+  const status = Number(err.status ?? err.statusCode);
+  if (name === "AbortError" || name === "TimeoutError") return true;
+  if (status === 408 || status === 502 || status === 503 || status === 504) return true;
+  const msg = String(err.message ?? "").toLowerCase();
+  const code = String(err.code ?? "").toLowerCase();
+  return ["timeout", "etimedout", "econnreset", "socket hang up", "network error", "fetch failed"].some((key) => msg.includes(key) || code.includes(key));
+};
+var classifyErrorStatus = (error, isTimedOut) => {
+  if (isDeterministicClientError(error)) {
+    return "FAILED";
+  }
+  if (isAmbiguousTimeoutError(error, isTimedOut)) {
+    return "UNCONFIRMED_TIMEOUT";
+  }
+  return "FAILED";
+};
+var getToolExecutionRecord = async (storage, toolCallId) => {
+  if (!storage) {
+    return inMemoryFallbackStore.get(toolCallId) ?? null;
+  }
+  if (storage.getStateValue) {
+    const val = await storage.getStateValue(`tool_resilience:${toolCallId}`);
+    if (val) return val;
+    const directVal = await storage.getStateValue(toolCallId);
+    if (directVal) return directVal;
+  }
+  const step = await storage.getStep("_tool_resilience", toolCallId);
+  return step?.metadata?.resilienceRecord ?? null;
+};
+var saveToStateStorage = async (storage, toolCallId, record) => {
+  if (!storage.setStateValue) return;
+  await storage.setStateValue(`tool_resilience:${toolCallId}`, record);
+  await storage.setStateValue(toolCallId, record);
+};
+var saveResilienceRecord = async (storage, record) => {
+  if (!storage) {
+    setFallbackRecord(record.toolCallId, record);
+    return;
+  }
+  await saveToStateStorage(storage, record.toolCallId, record);
+  const status = record.status === "COMPLETED" ? "COMPLETED" : record.status === "FAILED" ? "FAILED" : "RUNNING";
+  await storage.saveStep({
+    workflowId: "_tool_resilience",
+    stepId: record.toolCallId,
+    status,
+    result: record.result,
+    error: record.error,
+    metadata: { resilienceRecord: record },
+    createdAt: new Date(record.startedAt).toISOString(),
+    updatedAt: new Date(record.updatedAt).toISOString()
+  });
+};
+var handleAmbiguousFailure = (options, originalError) => {
+  const workflowId = options.workflowId ?? "_tool_resilience";
+  if (options.suspendOnAmbiguous) {
+    throw new StepSuspendedError(options.toolCallId, workflowId, {
+      toolCallId: options.toolCallId,
+      impact: options.impact,
+      reason: "Ambiguous mutation requires human intervention",
+      originalError
+    });
+  }
+  throw new AmbiguousToolExecutionError({
+    toolCallId: options.toolCallId,
+    toolName: options.toolName,
+    impact: options.impact,
+    message: "Ambiguous execution state (UNCONFIRMED_TIMEOUT). Re-execution blocked without reconciliation.",
+    originalError
+  });
+};
+var saveReconciledRecord = async (options, result) => {
+  await saveResilienceRecord(options.storage, {
+    toolCallId: options.toolCallId,
+    status: "COMPLETED",
+    result,
+    impact: options.impact,
+    startedAt: Date.now(),
+    updatedAt: Date.now()
+  });
+  return { result, isCached: true, status: "COMPLETED" };
+};
+var tryReconciliation = async (options) => {
+  if (!options.onAmbiguousRetry) {
+    return handleAmbiguousFailure(options);
+  }
+  try {
+    const outcome = await options.onAmbiguousRetry({ toolCallId: options.toolCallId, args: options.args });
+    if (!outcome.reconciled) {
+      return handleAmbiguousFailure(options);
+    }
+    return await saveReconciledRecord(options, outcome.result);
+  } catch (err) {
+    if (err instanceof StepSuspendedError || err instanceof AmbiguousToolExecutionError) throw err;
+    return handleAmbiguousFailure(options, err);
+  }
+};
+var checkExistingState = async (options) => {
+  const existing = await getToolExecutionRecord(options.storage, options.toolCallId);
+  if (!existing) {
+    return null;
+  }
+  if (existing.status === "COMPLETED") {
+    return { result: existing.result, isCached: true, status: "COMPLETED" };
+  }
+  if (existing.status === "UNCONFIRMED_TIMEOUT") {
+    if (options.impact === "READ_ONLY") {
+      return null;
+    }
+    return await tryReconciliation(options);
+  }
+  return null;
+};
+var executeActionWithTimeout = async (action, timeoutMs, idempotencyKey) => {
+  const controller = new AbortController();
+  let isTimedOut = false;
+  const timer = setTimeout(() => {
+    isTimedOut = true;
+    controller.abort(new Error(`Tool execution timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
+  try {
+    const result = await action(controller.signal, idempotencyKey);
+    return { result, isTimedOut: false };
+  } catch (error) {
+    return { error, isTimedOut };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+var saveFailureRecord = async (options, startedAt, error, isTimedOut) => {
+  const status = classifyErrorStatus(error, isTimedOut);
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  await saveResilienceRecord(options.storage, {
+    toolCallId: options.toolCallId,
+    status,
+    error: errorMsg,
+    impact: options.impact,
+    startedAt,
+    updatedAt: Date.now()
+  });
+  throw error;
+};
+var saveSuccessRecord = async (options, startedAt, result) => {
+  await saveResilienceRecord(options.storage, {
+    toolCallId: options.toolCallId,
+    status: "COMPLETED",
+    result,
+    impact: options.impact,
+    startedAt,
+    updatedAt: Date.now()
+  });
+  return { result, isCached: false, status: "COMPLETED" };
+};
+var claimExecutionIntent = async (options, startedAt) => {
+  await saveResilienceRecord(options.storage, {
+    toolCallId: options.toolCallId,
+    status: "CLAIMED",
+    impact: options.impact,
+    startedAt,
+    updatedAt: startedAt
+  });
+};
+var withToolResilience = async (options) => {
+  const existingResult = await checkExistingState(options);
+  if (existingResult) {
+    return existingResult;
+  }
+  const startedAt = Date.now();
+  const idempotencyKey = options.idempotencyKey || options.toolCallId;
+  await claimExecutionIntent(options, startedAt);
+  const timeoutMs = options.timeoutMs ?? 3e4;
+  const outcome = await executeActionWithTimeout(options.action, timeoutMs, idempotencyKey);
+  if (outcome.error) {
+    return await saveFailureRecord(options, startedAt, outcome.error, outcome.isTimedOut);
+  }
+  return await saveSuccessRecord(options, startedAt, outcome.result);
+};
+
 // src/agent/isolated-tool.ts
 var verifyRoles = (configuredRoles, context, toolIdentifier) => {
   if (!configuredRoles || configuredRoles.length === 0) {
     return;
   }
-  const userRoles = [
-    ...context.roles ?? [],
-    ...context.role ? [context.role] : []
-  ];
-  const hasAllowedRole = configuredRoles.some((role) => userRoles.includes(role));
+  if (!context.role && (!context.roles || context.roles.length === 0)) {
+    throw new ToolAccessDeniedError(toolIdentifier, "Access denied: insufficient role permissions");
+  }
+  const roleSet = new Set(context.roles ?? []);
+  if (context.role) roleSet.add(context.role);
+  const hasAllowedRole = configuredRoles.some((role) => roleSet.has(role));
   if (!hasAllowedRole) {
     throw new ToolAccessDeniedError(
       toolIdentifier,
@@ -2514,6 +3083,35 @@ var processLlmPayload = async (rawResult, args, context, config, toolIdentifier)
     config.throwOnPii === true
   );
 };
+var buildResilientContext = (config, args, context) => {
+  const toolCallId = context.toolCallId || `call_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+  const genKey = config.resilience?.idempotencyKeyGenerator?.(args, context);
+  const idempotencyKey = context.idempotencyKey || genKey || toolCallId;
+  const resilientContext = { ...context, toolCallId, idempotencyKey };
+  return { toolCallId, idempotencyKey, resilientContext };
+};
+var executeWithResilienceGuard = async (config, args, context, toolIdentifier) => {
+  if (!config.resilience) {
+    return await config.execute(args, context);
+  }
+  const { toolCallId, idempotencyKey, resilientContext } = buildResilientContext(config, args, context);
+  const outcome = await withToolResilience({
+    toolCallId,
+    toolName: toolIdentifier,
+    storage: context.storage,
+    impact: config.impact ?? "READ_ONLY",
+    idempotencyKey,
+    timeoutMs: config.resilience.timeoutMs,
+    suspendOnAmbiguous: config.resilience.suspendOnAmbiguous,
+    workflowId: context.workflowId,
+    args,
+    action: async (signal, idKey) => {
+      return await config.execute(args, { ...resilientContext, abortSignal: signal, idempotencyKey: idKey });
+    },
+    onAmbiguousRetry: config.resilience.onAmbiguousRetry
+  });
+  return outcome.result;
+};
 var createIsolatedTool = (config) => {
   const toolId = config.id || config.name;
   const toolAlias = config.alias;
@@ -2535,6 +3133,7 @@ var createIsolatedTool = (config) => {
     _roles: config.roles ? Object.freeze([...config.roles]) : void 0,
     _impact: toolImpact,
     _requireApproval: requireApproval,
+    _resilience: config.resilience,
     _lastPiiFilteredCount: 0,
     _lastInvalidationTags: void 0,
     execute: async (args, context) => {
@@ -2549,7 +3148,12 @@ var createIsolatedTool = (config) => {
         updatedContext,
         toolIdentifier
       );
-      const rawResult = await config.execute(args, updatedContext);
+      const rawResult = await executeWithResilienceGuard(
+        config,
+        args,
+        updatedContext,
+        toolIdentifier
+      );
       verifyTenantIsolation(config.assertTenant, rawResult, updatedContext, toolIdentifier);
       await verifyResourceOwnership(
         config.assertOwnership,
@@ -2884,6 +3488,8 @@ var createLaunchSafeConfig = (options) => {
   return {
     maxTokenBudget: 8192,
     maxCostUSD: 0.5,
+    middlewareTimeoutMs: 5e3,
+    reScanIngressAfterHooks: true,
     ...options,
     retryOptions: { ...defaultRetries, ...options.retryOptions },
     security: { ...defaultSecurity, ...options.security }
@@ -2905,6 +3511,8 @@ var createEnterpriseStrictConfig = (options) => {
   return {
     maxTokenBudget: 4096,
     maxCostUSD: 0.15,
+    middlewareTimeoutMs: 3e3,
+    reScanIngressAfterHooks: true,
     ...options,
     retryOptions: { ...defaultRetries, ...options.retryOptions },
     security: { ...defaultSecurity, ...options.security }
@@ -2941,14 +3549,22 @@ var PRESETS = {
   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,
@@ -2966,6 +3582,7 @@ var PRESETS = {
   createHttpProviderClient,
   createLLMControlLayer,
   createLaunchSafeConfig,
+  deepFreeze,
   defineWorkflow,
   executeAfterResponseHooks,
   executeBeforeRequestHooks,