avantgate 2.2.0 → 2.4.0

package/README.md

@@ -94,7 +94,7 @@ Contact our team at [contact@gatewall.fr](mailto:contact@gatewall.fr) for privat
 | 📊 **Observability & Cockpit** | [GateWall Cockpit Console](docs/observability/gatewall-cockpit.md) • [Telemetry & Browser SDK](docs/observability/telemetry-and-browser-sdk.md) • [GateWall vs. Temporal](docs/observability/temporal-and-gatewall.md) |
 | 💶 **Accounting** | [Financial Normalizer](docs/finance/normalizer.md) |
 | 🎨 **Presentation Plane** | [Headless UI Canvas & React Bindings](docs/ui/headless-canvas.md) |
-| 🚀 **Release Notes** | [v2.1.0 Release Notes](docs/release/release-2.1.0.md) • [v2.0.0 Release Notes](docs/release/release-2.0.0.md) • [v1.9.0 Release Notes](docs/release/release-1.9.0.md) |
+| 🚀 **Release Notes** | [v2.3.0 Release Notes](docs/release/release-2.3.0.md) • [v2.2.0 Release Notes](docs/release/release-2.2.0.md) • [v2.1.0 Release Notes](docs/release/release-2.1.0.md) • [v2.0.0 Release Notes](docs/release/release-2.0.0.md) • [v1.9.0 Release Notes](docs/release/release-1.9.0.md) |
 
 ---
 
@@ -127,6 +127,8 @@ pnpm add avantgate zod
 yarn add avantgate zod
 ```
 
+> 🚀 **Quickstart Guide:** See [**Getting Started with AvantGate**](docs/getting-started.md) for 3-minute quickstart recipes with launch-safe presets and compile-time anti-IDOR tools.
+
 ### 🧩 Subpath Exports
 
 | Import Path | Description | Documentation |

package/dist/agent/errors.d.ts

@@ -47,4 +47,18 @@ export declare class DtoValidationError extends Error {
     readonly issues: unknown[];
     constructor(toolName: string, message: string, issues?: unknown[]);
 }
+export interface AmbiguousToolExecutionDetails {
+    toolCallId: string;
+    toolName?: string;
+    impact?: string;
+    message?: string;
+    originalError?: unknown;
+}
+export declare class AmbiguousToolExecutionError extends Error {
+    readonly toolCallId: string;
+    readonly toolName?: string;
+    readonly impact?: string;
+    readonly originalError?: unknown;
+    constructor(details: AmbiguousToolExecutionDetails | string, toolName?: string, impact?: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/agent/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/agent/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEvC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAOnF;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,WAAW,EAAE,MAAM,CAAC;gBAExB,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAMlD;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAC;gBAE5B,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO;CAOzF;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEpB,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;CAapD;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,KAAK,EAAE,MAAM,EAAE,CAAC;gBAEpB,KAAK,EAAE,MAAM,EAAE;CAK5B;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAM5C;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAMjD;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,MAAM;CAK3B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,OAAO,EAAE,CAAC;gBAEtB,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO;CAMtE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/agent/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEvC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAOnF;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,WAAW,EAAE,MAAM,CAAC;gBAExB,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAMlD;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAC;gBAE5B,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO;CAOzF;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEpB,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;CAapD;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,KAAK,EAAE,MAAM,EAAE,CAAC;gBAEpB,KAAK,EAAE,MAAM,EAAE;CAK5B;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAM5C;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAMjD;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,MAAM;CAK3B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,OAAO,EAAE,CAAC;gBAEtB,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO;CAMtE;AAED,MAAM,WAAW,6BAA6B;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChC,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAC;gBAE5B,OAAO,EAAE,6BAA6B,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAahG"}

package/dist/agent/index.d.ts

@@ -16,4 +16,5 @@ export * from "./tool-state";
 export * from "./adapters";
 export * from "./telemetry";
 export * from "./idempotency-guard";
+export * from "./tool-resilience";
 //# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}

package/dist/agent/index.js

@@ -22,6 +22,7 @@ var agent_exports = {};
 __export(agent_exports, {
   AccessControlToolStrategy: () => AccessControlToolStrategy,
   AgentToolFactory: () => AgentToolFactory,
+  AmbiguousToolExecutionError: () => AmbiguousToolExecutionError,
   CircularToolCallError: () => CircularToolCallError,
   CompositeToolStrategy: () => CompositeToolStrategy,
   DtoValidationError: () => DtoValidationError,
@@ -45,6 +46,7 @@ __export(agent_exports, {
   ToolSubCallQuotaError: () => ToolSubCallQuotaError,
   applyToolStrategy: () => applyToolStrategy,
   auditToolResult: () => auditToolResult,
+  clearResilienceFallbackStore: () => clearResilienceFallbackStore,
   createAdapterIdempotencyStore: () => createAdapterIdempotencyStore,
   createCustomStorageAdapter: () => createCustomStorageAdapter,
   createIsolatedTool: () => createIsolatedTool,
@@ -54,7 +56,9 @@ __export(agent_exports, {
   createToolInvoker: () => createToolInvoker,
   createToolSharedState: () => createToolSharedState,
   dto: () => dto,
-  withServerIdempotency: () => withServerIdempotency
+  getToolExecutionRecord: () => getToolExecutionRecord,
+  withServerIdempotency: () => withServerIdempotency,
+  withToolResilience: () => withToolResilience
 });
 module.exports = __toCommonJS(agent_exports);
 
@@ -157,6 +161,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/sanitizer.ts
 var EMAIL_REGEX = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,7}\b/g;
@@ -263,16 +286,223 @@ function auditToolResult(data, options) {
   };
 }
 
+// src/agent/tool-resilience.ts
+var MAX_FALLBACK_CAP = 1e3;
+var inMemoryFallbackStore = /* @__PURE__ */ new Map();
+var clearResilienceFallbackStore = () => {
+  inMemoryFallbackStore.clear();
+};
+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,
@@ -389,6 +619,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;
@@ -410,6 +669,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) => {
@@ -424,7 +684,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,
@@ -603,14 +868,22 @@ function toDescriptor(tool) {
 var ToolRegistry = class _ToolRegistry {
   toolsById = /* @__PURE__ */ new Map();
   toolsByPublicName = /* @__PURE__ */ new Map();
-  /**
-   * Registers a new tool in the registry.
-   */
+  toolsByDomain = /* @__PURE__ */ new Map();
+  toolsByImpact = /* @__PURE__ */ new Map();
   register(toolDef) {
     const normalizedDef = normalizeToolDefinition(toolDef);
     const publicName = normalizedDef.alias || normalizedDef.name;
     this.toolsById.set(normalizedDef.id, normalizedDef);
     this.toolsByPublicName.set(publicName, normalizedDef);
+    if (normalizedDef.domain) {
+      const domainList = this.toolsByDomain.get(normalizedDef.domain) ?? [];
+      domainList.push(normalizedDef);
+      this.toolsByDomain.set(normalizedDef.domain, domainList);
+    }
+    const impact = normalizedDef.impact ?? "READ_ONLY";
+    const impactList = this.toolsByImpact.get(impact) ?? [];
+    impactList.push(normalizedDef);
+    this.toolsByImpact.set(impact, impactList);
     return this;
   }
   /**
@@ -656,52 +929,48 @@ var ToolRegistry = class _ToolRegistry {
    * Filters tools belonging to a specific business domain.
    */
   getByDomain(domain) {
-    return this.getAll().filter((item) => item.domain === domain);
+    const tools = this.toolsByDomain.get(domain);
+    return tools ? [...tools] : [];
   }
-  /**
-   * Filters tools matching a specific workflow phase.
-   */
   getByPhase(phase) {
-    return this.getAll().filter((item) => {
-      if (!item.phases || item.phases.length === 0) {
-        return true;
+    const result = [];
+    for (const item of this.toolsById.values()) {
+      if (!item.phases || item.phases.length === 0 || item.phases.includes(phase)) {
+        result.push(item);
       }
-      return item.phases.includes(phase);
-    });
+    }
+    return result;
   }
-  /**
-   * Filters tools matching the user's roles (RBAC).
-   */
   filterByRoles(userRoles) {
     const roleSet = new Set(userRoles);
-    return this.getAll().filter((item) => {
+    const result = [];
+    for (const item of this.toolsById.values()) {
       const roles = item.roles ?? item.requiredRoles;
-      if (!roles || roles.length === 0) {
-        return true;
+      if (!roles || roles.length === 0 || roles.some((role) => roleSet.has(role))) {
+        result.push(item);
       }
-      return roles.some((role) => roleSet.has(role));
-    });
+    }
+    return result;
   }
-  /**
-   * Filters tools matching a specific physical impact profile (READ_ONLY, MUTATIVE, DESTRUCTIVE).
-   */
   getByImpact(impact) {
-    return this.getAll().filter((item) => (item.impact ?? "READ_ONLY") === impact);
+    const tools = this.toolsByImpact.get(impact);
+    return tools ? [...tools] : [];
   }
-  /**
-   * Exports headless technical descriptors without UI rendering coupling.
-   */
   getDescriptors(filter) {
-    let list = this.getAll();
+    let list;
     if (filter?.domain) {
-      list = list.filter((item) => item.domain === filter.domain);
+      list = this.getByDomain(filter.domain);
+    } else if (filter?.impact) {
+      list = this.getByImpact(filter.impact);
+    } else {
+      list = this.getAll();
+    }
+    if (filter?.domain && filter?.impact) {
+      list = list.filter((item) => (item.impact ?? "READ_ONLY") === filter.impact);
     }
     if (filter?.role) {
       list = list.filter((item) => matchesRoleFilter(item, filter.role));
     }
-    if (filter?.impact) {
-      list = list.filter((item) => (item.impact ?? "READ_ONLY") === filter.impact);
-    }
     return list.map(toDescriptor);
   }
   /**
@@ -802,17 +1071,12 @@ function matchesRoles(tool, context) {
   if (!toolRoles || toolRoles.length === 0) {
     return true;
   }
-  const userRoles = [];
-  if (context.role) {
-    userRoles.push(context.role);
-  }
-  if (context.roles) {
-    userRoles.push(...context.roles);
-  }
-  if (userRoles.length === 0) {
+  if (!context.role && (!context.roles || context.roles.length === 0)) {
     return false;
   }
-  return toolRoles.some((roleName) => userRoles.includes(roleName));
+  const userRoleSet = new Set(context.roles ?? []);
+  if (context.role) userRoleSet.add(context.role);
+  return toolRoles.some((roleName) => userRoleSet.has(roleName));
 }
 var AccessControlToolStrategy = class {
   allowedDomains;
@@ -2140,6 +2404,7 @@ var createAdapterIdempotencyStore = (adapter, namespace = "idempotency") => {
 0 && (module.exports = {
   AccessControlToolStrategy,
   AgentToolFactory,
+  AmbiguousToolExecutionError,
   CircularToolCallError,
   CompositeToolStrategy,
   DtoValidationError,
@@ -2163,6 +2428,7 @@ var createAdapterIdempotencyStore = (adapter, namespace = "idempotency") => {
   ToolSubCallQuotaError,
   applyToolStrategy,
   auditToolResult,
+  clearResilienceFallbackStore,
   createAdapterIdempotencyStore,
   createCustomStorageAdapter,
   createIsolatedTool,
@@ -2172,5 +2438,7 @@ var createAdapterIdempotencyStore = (adapter, namespace = "idempotency") => {
   createToolInvoker,
   createToolSharedState,
   dto,
-  withServerIdempotency
+  getToolExecutionRecord,
+  withServerIdempotency,
+  withToolResilience
 });