avantgate 1.2.2 → 1.4.0

package/README.md

@@ -1,7 +1,7 @@
 # 🛡️ AvantGate (`avantgate`)
 
-> **The Zero-Infrastructure, In-Process AI Application Firewall (AI-WAF) & Privacy Guard for TypeScript.**  
-> Real-time prompt guardrails, zero-egress PII redaction, anti-IDOR tool boundary, and pre-flight token defense **without hosting Docker, proxies, PostgreSQL, ClickHouse, or Redis.**
+> **The Zero-Infrastructure, In-Process AI Application Firewall (AI-WAF), Deterministic Workflow Engine & Privacy Guard for TypeScript.**  
+> Real-time prompt guardrails, zero-egress PII redaction, deterministic Saga workflows, anti-IDOR tool boundary, and pre-flight token defense **without hosting Docker, proxies, PostgreSQL, ClickHouse, or Redis.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue?logo=typescript)](https://www.typescriptlang.org/)
@@ -47,6 +47,7 @@ Available as a **Managed Cloud Control Plane** or an **Out-of-Process High-Avail
 
 - 🛡️ **Active Threat Defense & Prompt Guardrails**: Blocks prompt injections, DAN jailbreaks, adversarial noise, and system prompt exfiltration *before* external API invocation.
 - 🔒 **Zero-Egress Data Loss Prevention (DLP)**: Automated local redaction of emails, phone numbers, IBAN/BIC, and French/EU identifiers (NIR SSN, SPI tax ID) before network egress.
+- ⚡ **Deterministic Workflow Engine (`avantgate/workflow`)**: In-process sequential state machine for multi-step agent orchestrations. Features automatic reverse compensation (Saga Pattern), non-blocking Human-in-the-Loop checkpoints, and safe-by-default AI tool conversion (`asTool()`).
 - 🎭 **Dual-Channel Tool Isolation (`avantgate/agent`)**: Decouples sensitive database records (streamed out-of-band directly to client UIs) from minimal cognitive LLM context (`llmDto`), keeping confidential fields out of context windows.
 - 🛑 **Anti-IDOR & Access Governance**: Enforces Row-Level Security (`dataAccessGuard`), business domain partitioning, and granular role-based permissions at the agent tool boundary.
 - 💰 **Denial-of-Wallet & Pre-Flight Budgeting**: Enforces strict token and cent-level USD budget limits, rejecting abusive requests before paying for upstream inference.
@@ -91,6 +92,7 @@ yarn add avantgate zod
 | `avantgate` | Core control plane: token budgets, cost ledger, prompt guards, multi-model failover & Zod repair. |
 | `avantgate/finance` | Financial data normalizer (accounting parentheses, EU/US/UK/CH currencies & magnitudes). |
 | `avantgate/agent` | *(Preview / Experimental)* Durable step runner, Human-in-the-Loop, dual-channel PII tool isolation & storage adapters. |
+| `avantgate/workflow` | Deterministic sequential state machine, automatic reverse Saga rollback, durable HITL checkpoints & agent tool conversion. |
 
 ---
 
@@ -100,6 +102,7 @@ Comprehensive guides, copy-pasteable integration recipes, and architectural refe
 
 | Guide | Description |
 |---|---|
+| **[Deterministic Workflow Engine](docs/workflow.md)** | Zero-infra Saga orchestrator, linear FSM rationale, reverse compensation, HITL checkpoints & agent tool conversion. |
 | **[Code Examples & Recipes](docs/examples.md)** | End-to-end security guardrails, PII redaction, anti-IDOR tool boundaries, cost tracking, Zod self-repair, and multi-model failover. |
 | **[Decoupled Pricing & DB Adapters](docs/pricing.md)** | Dynamic token pricing, database integration (Prisma / PostgreSQL / Drizzle), in-memory TTL caching, and runtime overrides. |
 | **[Durable Agent Harness & Tool Isolation](docs/agent.md)** | Serverless durable step execution, Human-in-the-Loop suspension, dual-channel DTO tool isolation, and telemetry streaming. |
@@ -148,6 +151,7 @@ AvantGate is built around clean **Ports and Adapters**:
 
 ### 📦 Modular Ecosystem & Extensions
 
+- **`avantgate/workflow`**: Deterministic sequential state machine, automatic reverse Saga rollback ($k-1 \to 0$), and durable HITL checkpoints.
 - **`avantgate/agent`**: Zero-infra durable step orchestration, human-in-the-loop pauses, and dual-channel PII tool isolation.
 - **`avantgate/finance`**: Zero-overhead financial accounting normalizer across international jurisdictions (FR PCG, US GAAP, UK IFRS, Swiss CO).
 - **Launch Readiness Linter**: Standalone developer tool to audit codebases before launch for exposed keys, unbudgeted endpoints, and missing guards.
@@ -183,7 +187,8 @@ AvantGate builds upon foundational ideas and inspirations from the open source A
 - **[Helicone](https://github.com/Helicone/helicone)** — Pioneering LLM request caching, granular cost estimation, and developer-first proxy design that inspired our FinOps engine and semantic tool caching patterns.
 - **[AgentOps](https://github.com/AgentOps-AI/agentops)** — State-of-the-art agent tracking, session replay visualization, and recursive loop detection that inspired our Session Replay and Infinite Loop Shield.
 
-### 🤖 Durable Workflows & Agent Architecture (`avantgate/agent`)
+### 🤖 Durable Workflows & Agent Architecture (`avantgate/agent` & `avantgate/workflow`)
+- **Deterministic FSM & Saga Pattern** — Architectural rejection of fragile cyclic graphs in favor of strictly ordered, hallucination-resistant linear state machines with mathematically guaranteed reverse rollback ($k-1 \to 0$).
 - **[Inngest](https://www.inngest.com)** & **[Temporal](https://temporal.io)** — The developer experience of durable step memoization (`step.run()`) and human validation pauses (`step.waitForApproval()`), reimagined here as a **$0-infrastructure, serverless in-process harness** without requiring external worker queues or Redis clusters.
 - **[Vercel AI SDK (`ai`)](https://sdk.vercel.ai)** — Standardized TypeScript tool schema contracts (`parameters`, `execute`) natively embraced and augmented by `createIsolatedTool`.
 - **Least-Privilege & Dual-Channel Isolation** — Security patterns separating sensitive payload data (streamed out-of-band directly to trusted user interfaces) from LLM prompts (receiving sanitized summaries), preventing context pollution and PII leakage.

package/dist/agent/index.js

@@ -27,11 +27,13 @@ __export(agent_exports, {
   DtoValidationError: () => DtoValidationError,
   HttpTelemetryExporter: () => HttpTelemetryExporter,
   KeyValueStorageAdapter: () => KeyValueStorageAdapter,
+  MaxImpactToolStrategy: () => MaxImpactToolStrategy,
   MemoryStorageAdapter: () => MemoryStorageAdapter,
   PhaseBasedToolStrategy: () => PhaseBasedToolStrategy,
   PiiLeakError: () => PiiLeakError,
   PlatformStorageAdapter: () => PlatformStorageAdapter,
   PrismaStorageAdapter: () => PrismaStorageAdapter,
+  ReadOnlyToolStrategy: () => ReadOnlyToolStrategy,
   RoleBasedToolStrategy: () => RoleBasedToolStrategy,
   SQLiteStorageAdapter: () => SQLiteStorageAdapter,
   StepExecutionError: () => StepExecutionError,
@@ -329,6 +331,8 @@ function createIsolatedTool(config) {
   const toolAlias = config.alias;
   const clientCallback = config.clientDto;
   const toolIdentifier = toolAlias || config.name;
+  const toolImpact = config.impact ?? "READ_ONLY";
+  const requireApproval = config.requireApproval ?? toolImpact === "DESTRUCTIVE";
   const tool = {
     description: config.description,
     parameters: config.parameters,
@@ -340,8 +344,8 @@ function createIsolatedTool(config) {
     _domain: config.domain,
     _resource: config.resource,
     _roles: config.roles ? Object.freeze([...config.roles]) : void 0,
-    _permissions: config.permissions ? Object.freeze([...config.permissions]) : void 0,
-    _requireApproval: config.requireApproval ?? false,
+    _impact: toolImpact,
+    _requireApproval: requireApproval,
     _lastPiiFilteredCount: 0,
     _lastInvalidationTags: void 0,
     async execute(args, context) {
@@ -475,7 +479,7 @@ function normalizeToolDefinition(toolDef) {
       domain: toolDef._domain,
       resource: toolDef._resource,
       roles: toolDef._roles ? Array.from(toolDef._roles) : void 0,
-      permissions: toolDef._permissions ? Array.from(toolDef._permissions) : void 0,
+      impact: toolDef._impact ?? "READ_ONLY",
       requireApproval: toolDef._requireApproval,
       tool: toolDef
     };
@@ -483,7 +487,7 @@ function normalizeToolDefinition(toolDef) {
   const id = toolDef.id || toolDef.name || toolDef.tool?._toolId;
   const publicName = toolDef.alias || toolDef.name || toolDef.tool?._toolAlias || toolDef.tool?._toolName;
   const roles = toolDef.roles ?? (toolDef.tool?._roles ? Array.from(toolDef.tool._roles) : toolDef.requiredRoles);
-  const permissions = toolDef.permissions ?? (toolDef.tool?._permissions ? Array.from(toolDef.tool._permissions) : void 0);
+  const impact = toolDef.impact ?? toolDef.tool?._impact ?? "READ_ONLY";
   return {
     ...toolDef,
     id,
@@ -492,7 +496,7 @@ function normalizeToolDefinition(toolDef) {
     domain: toolDef.domain ?? toolDef.tool?._domain,
     resource: toolDef.resource ?? toolDef.tool?._resource,
     roles,
-    permissions,
+    impact,
     requireApproval: toolDef.requireApproval ?? toolDef.tool?._requireApproval
   };
 }
@@ -515,7 +519,7 @@ function toDescriptor(tool) {
     domain: tool.domain,
     resource: tool.resource,
     roles: tool.roles ?? tool.requiredRoles,
-    permissions: tool.permissions,
+    impact: tool.impact ?? "READ_ONLY",
     requireApproval: tool.requireApproval,
     cacheTTL: tool.tool._cacheTTL,
     tags: tool.tags
@@ -603,6 +607,12 @@ var ToolRegistry = class _ToolRegistry {
       return roles.some((role) => roleSet.has(role));
     });
   }
+  /**
+   * Filters tools matching a specific physical impact profile (READ_ONLY, MUTATIVE, DESTRUCTIVE).
+   */
+  getByImpact(impact) {
+    return this.getAll().filter((item) => (item.impact ?? "READ_ONLY") === impact);
+  }
   /**
    * Exports headless technical descriptors without UI rendering coupling.
    */
@@ -614,6 +624,9 @@ var ToolRegistry = class _ToolRegistry {
     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);
   }
   /**
@@ -641,6 +654,18 @@ var ToolRegistry = class _ToolRegistry {
 };
 
 // src/agent/strategy.ts
+var IMPACT_WEIGHTS = {
+  READ_ONLY: 1,
+  MUTATIVE: 2,
+  DESTRUCTIVE: 3
+};
+function matchesMaxImpact(tool, maxImpact) {
+  if (!maxImpact) {
+    return true;
+  }
+  const toolImpact = tool.impact ?? "READ_ONLY";
+  return IMPACT_WEIGHTS[toolImpact] <= IMPACT_WEIGHTS[maxImpact];
+}
 var PhaseBasedToolStrategy = class {
   selectTools(tools, context) {
     if (!context.phase) {
@@ -673,6 +698,24 @@ var RoleBasedToolStrategy = class {
     });
   }
 };
+var ReadOnlyToolStrategy = class {
+  selectTools(tools, _context) {
+    return tools.filter((tool) => (tool.impact ?? "READ_ONLY") === "READ_ONLY");
+  }
+};
+var MaxImpactToolStrategy = class {
+  maxImpact;
+  constructor(maxImpact) {
+    this.maxImpact = maxImpact;
+  }
+  selectTools(tools, _context) {
+    const maxWeight = IMPACT_WEIGHTS[this.maxImpact];
+    return tools.filter((tool) => {
+      const toolImpact = tool.impact ?? "READ_ONLY";
+      return IMPACT_WEIGHTS[toolImpact] <= maxWeight;
+    });
+  }
+};
 function matchesDomain(tool, allowedDomains) {
   if (!allowedDomains) {
     return true;
@@ -696,23 +739,18 @@ function matchesRoles(tool, context) {
   }
   return toolRoles.some((roleName) => userRoles.includes(roleName));
 }
-function matchesPermissions(tool, context) {
-  if (!tool.permissions || tool.permissions.length === 0) {
-    return true;
-  }
-  const userPermissions = context.permissions ?? [];
-  return tool.permissions.every((permissionName) => userPermissions.includes(permissionName));
-}
 var AccessControlToolStrategy = class {
   allowedDomains;
+  maxImpact;
   constructor(options) {
     if (options?.allowedDomains) {
       this.allowedDomains = new Set(options.allowedDomains);
     }
+    this.maxImpact = options?.maxImpact;
   }
   selectTools(tools, context) {
     return tools.filter(
-      (tool) => matchesDomain(tool, this.allowedDomains) && matchesRoles(tool, context) && matchesPermissions(tool, context)
+      (tool) => matchesDomain(tool, this.allowedDomains) && matchesRoles(tool, context) && matchesMaxImpact(tool, this.maxImpact)
     );
   }
 };
@@ -1971,11 +2009,13 @@ var HttpTelemetryExporter = class {
   DtoValidationError,
   HttpTelemetryExporter,
   KeyValueStorageAdapter,
+  MaxImpactToolStrategy,
   MemoryStorageAdapter,
   PhaseBasedToolStrategy,
   PiiLeakError,
   PlatformStorageAdapter,
   PrismaStorageAdapter,
+  ReadOnlyToolStrategy,
   RoleBasedToolStrategy,
   SQLiteStorageAdapter,
   StepExecutionError,

package/dist/agent/index.mjs

@@ -1,281 +1,16 @@
 import {
-  sanitizePII
-} from "../chunk-DVCF4CSV.mjs";
-
-// src/agent/errors.ts
-var StepSuspendedError = class extends Error {
-  stepId;
-  workflowId;
-  metadata;
-  constructor(stepId, workflowId, metadata) {
-    super(`Step execution suspended for human approval: [${workflowId}::${stepId}]`);
-    this.name = "StepSuspendedError";
-    this.stepId = stepId;
-    this.workflowId = workflowId;
-    this.metadata = metadata;
-  }
-};
-var PiiLeakError = class extends Error {
-  toolName;
-  maskedCount;
-  constructor(toolName, maskedCount) {
-    super(`PII leak detected in tool output for "${toolName}" (${maskedCount} occurrences detected).`);
-    this.name = "PiiLeakError";
-    this.toolName = toolName;
-    this.maskedCount = maskedCount;
-  }
-};
-var StepExecutionError = class extends Error {
-  stepId;
-  workflowId;
-  originalError;
-  constructor(stepId, workflowId, message, originalError) {
-    super(`Execution failed at step [${workflowId}::${stepId}]: ${message}`);
-    this.name = "StepExecutionError";
-    this.stepId = stepId;
-    this.workflowId = workflowId;
-    this.originalError = originalError;
-  }
-};
-var ToolAccessDeniedError = class extends Error {
-  toolName;
-  requiredRole;
-  reason;
-  constructor(toolName, reasonOrRole) {
-    const isRole = Boolean(reasonOrRole && !reasonOrRole.includes(" "));
-    const roleMsg = isRole ? ` (requires role "${reasonOrRole}")` : "";
-    const reasonMsg = reasonOrRole && !isRole ? `: ${reasonOrRole}` : "";
-    super(`Access denied for tool "${toolName}"${roleMsg}${reasonMsg}.`);
-    this.name = "ToolAccessDeniedError";
-    this.toolName = toolName;
-    if (isRole) {
-      this.requiredRole = reasonOrRole;
-    } else {
-      this.reason = reasonOrRole;
-    }
-  }
-};
-var CircularToolCallError = class extends Error {
-  cycle;
-  constructor(cycle) {
-    super(`Circular tool call detected: ${cycle.join(" -> ")}`);
-    this.name = "CircularToolCallError";
-    this.cycle = cycle;
-  }
-};
-var ToolCallDepthExceededError = class extends Error {
-  depth;
-  maxDepth;
-  constructor(depth, maxDepth) {
-    super(`Tool call depth limit exceeded: depth ${depth} exceeds max allowed depth of ${maxDepth}.`);
-    this.name = "ToolCallDepthExceededError";
-    this.depth = depth;
-    this.maxDepth = maxDepth;
-  }
-};
-var ToolSubCallQuotaError = class extends Error {
-  totalCalls;
-  maxCalls;
-  constructor(totalCalls, maxCalls) {
-    super(`Tool sub-call quota exceeded: ${totalCalls} calls exceeds session quota of ${maxCalls}.`);
-    this.name = "ToolSubCallQuotaError";
-    this.totalCalls = totalCalls;
-    this.maxCalls = maxCalls;
-  }
-};
-var ToolNotFoundError = class extends Error {
-  toolId;
-  constructor(toolId) {
-    super(`Tool not found in registry: "${toolId}".`);
-    this.name = "ToolNotFoundError";
-    this.toolId = toolId;
-  }
-};
-var DtoValidationError = class extends Error {
-  toolName;
-  issues;
-  constructor(toolName, message, issues = []) {
-    super(`LLM DTO validation failed for tool "${toolName}": ${message}`);
-    this.name = "DtoValidationError";
-    this.toolName = toolName;
-    this.issues = issues;
-  }
-};
-
-// src/agent/guardrails.ts
-function sanitizeString(value) {
-  const result = sanitizePII(value);
-  return { text: result.text, count: result.maskedCount };
-}
-function sanitizeArray(items, options, visited) {
-  let totalCount = 0;
-  const sanitized = items.map((item) => {
-    const res = recursivelySanitize(item, options, visited);
-    totalCount += res.count;
-    return res.sanitized;
-  });
-  return { sanitized, count: totalCount };
-}
-function sanitizeObject(target, options, visited) {
-  let totalCount = 0;
-  const copy = {};
-  for (const [key, val] of Object.entries(target)) {
-    const res = recursivelySanitize(val, options, visited);
-    copy[key] = res.sanitized;
-    totalCount += res.count;
-  }
-  return { sanitized: copy, count: totalCount };
-}
-function recursivelySanitize(data, options, visited = /* @__PURE__ */ new WeakSet()) {
-  if (typeof data === "string") {
-    const res = sanitizeString(data);
-    return { sanitized: res.text, count: res.count };
-  }
-  if (data !== null && typeof data === "object") {
-    if (visited.has(data)) {
-      return { sanitized: "[CIRCULAR_REFERENCE]", count: 0 };
-    }
-    visited.add(data);
-    if (Array.isArray(data)) {
-      return sanitizeArray(data, options, visited);
-    }
-    return sanitizeObject(data, options, visited);
-  }
-  return { sanitized: data, count: 0 };
-}
-function auditToolResult(data, options) {
-  const { sanitized, count } = recursivelySanitize(data, options);
-  if (options.throwOnPii && count > 0) {
-    throw new PiiLeakError(options.toolName, count);
-  }
-  return {
-    sanitizedData: sanitized,
-    maskedCount: count
-  };
-}
-
-// src/agent/isolated-tool.ts
-async function verifyDataAccessGuard(guard, args, context, toolIdentifier) {
-  if (!guard) {
-    return;
-  }
-  const isAllowed = await guard(args, context);
-  if (!isAllowed) {
-    throw new ToolAccessDeniedError(toolIdentifier, "Access denied by data access guard");
-  }
-}
-async function resolveInvalidationTags(config, args, rawResult, context) {
-  if (!config.invalidationTags) {
-    return void 0;
-  }
-  const tags = typeof config.invalidationTags === "function" ? await config.invalidationTags(args, rawResult) : config.invalidationTags;
-  if (tags && tags.length > 0 && context?.onInvalidationTags) {
-    await context.onInvalidationTags(tags);
-  }
-  return tags;
-}
-async function dispatchClientData(rawResult, callback) {
-  if (!callback) {
-    return;
-  }
-  await callback(rawResult);
-}
-async function produceLlmPayload(rawResult, args, context, transformer) {
-  if (transformer) {
-    return await transformer(rawResult, args, context);
-  }
-  return rawResult;
-}
-function validateLlmDto(payload, schema, toolIdentifier) {
-  const parseResult = schema.safeParse(payload);
-  if (!parseResult.success) {
-    const issues = parseResult.error.issues ?? [];
-    const errorMessages = issues.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`).join(", ");
-    throw new DtoValidationError(
-      toolIdentifier,
-      errorMessages,
-      issues
-    );
-  }
-  return parseResult.data;
-}
-function protectLlmPayload(payload, toolIdentifier, sanitizePii = true, throwOnPii = false) {
-  if (!sanitizePii) {
-    return { sanitized: payload, count: 0 };
-  }
-  const { sanitizedData, maskedCount } = auditToolResult(payload, {
-    toolName: toolIdentifier,
-    throwOnPii
-  });
-  return { sanitized: sanitizedData, count: maskedCount };
-}
-async function processLlmPayload(rawResult, args, context, config, toolIdentifier) {
-  let payload = await produceLlmPayload(rawResult, args, context, config.llmDto);
-  if (config.llmDtoSchema) {
-    payload = validateLlmDto(payload, config.llmDtoSchema, toolIdentifier);
-  }
-  return protectLlmPayload(
-    payload,
-    toolIdentifier,
-    config.sanitizePii !== false,
-    config.throwOnPii === true
-  );
-}
-function createIsolatedTool(config) {
-  const toolId = config.id || config.name;
-  const toolAlias = config.alias;
-  const clientCallback = config.clientDto;
-  const toolIdentifier = toolAlias || config.name;
-  const tool = {
-    description: config.description,
-    parameters: config.parameters,
-    _toolId: toolId,
-    _toolName: config.name,
-    _toolAlias: toolAlias,
-    _isIsolated: true,
-    _cacheTTL: config.cacheTTL,
-    _domain: config.domain,
-    _resource: config.resource,
-    _roles: config.roles ? Object.freeze([...config.roles]) : void 0,
-    _permissions: config.permissions ? Object.freeze([...config.permissions]) : void 0,
-    _requireApproval: config.requireApproval ?? false,
-    _lastPiiFilteredCount: 0,
-    _lastInvalidationTags: void 0,
-    async execute(args, context) {
-      const updatedContext = {
-        ...context,
-        callChain: context?.callChain ?? Object.freeze([toolId])
-      };
-      await verifyDataAccessGuard(
-        config.dataAccessGuard,
-        args,
-        updatedContext,
-        toolIdentifier
-      );
-      const rawResult = await config.execute(args, updatedContext);
-      const tags = await resolveInvalidationTags(
-        config,
-        args,
-        rawResult,
-        updatedContext
-      );
-      if (tags) {
-        tool._lastInvalidationTags = tags;
-      }
-      await dispatchClientData(rawResult, clientCallback);
-      const protection = await processLlmPayload(
-        rawResult,
-        args,
-        updatedContext,
-        config,
-        toolIdentifier
-      );
-      tool._lastPiiFilteredCount = protection.count;
-      return protection.sanitized;
-    }
-  };
-  return tool;
-}
+  CircularToolCallError,
+  DtoValidationError,
+  PiiLeakError,
+  StepExecutionError,
+  StepSuspendedError,
+  ToolAccessDeniedError,
+  ToolCallDepthExceededError,
+  ToolNotFoundError,
+  ToolSubCallQuotaError,
+  auditToolResult,
+  createIsolatedTool
+} from "../chunk-5VA3EKPJ.mjs";
 
 // src/agent/dto.ts
 function extractWhitelistedFields(data, keys) {
@@ -372,7 +107,7 @@ function normalizeToolDefinition(toolDef) {
       domain: toolDef._domain,
       resource: toolDef._resource,
       roles: toolDef._roles ? Array.from(toolDef._roles) : void 0,
-      permissions: toolDef._permissions ? Array.from(toolDef._permissions) : void 0,
+      impact: toolDef._impact ?? "READ_ONLY",
       requireApproval: toolDef._requireApproval,
       tool: toolDef
     };
@@ -380,7 +115,7 @@ function normalizeToolDefinition(toolDef) {
   const id = toolDef.id || toolDef.name || toolDef.tool?._toolId;
   const publicName = toolDef.alias || toolDef.name || toolDef.tool?._toolAlias || toolDef.tool?._toolName;
   const roles = toolDef.roles ?? (toolDef.tool?._roles ? Array.from(toolDef.tool._roles) : toolDef.requiredRoles);
-  const permissions = toolDef.permissions ?? (toolDef.tool?._permissions ? Array.from(toolDef.tool._permissions) : void 0);
+  const impact = toolDef.impact ?? toolDef.tool?._impact ?? "READ_ONLY";
   return {
     ...toolDef,
     id,
@@ -389,7 +124,7 @@ function normalizeToolDefinition(toolDef) {
     domain: toolDef.domain ?? toolDef.tool?._domain,
     resource: toolDef.resource ?? toolDef.tool?._resource,
     roles,
-    permissions,
+    impact,
     requireApproval: toolDef.requireApproval ?? toolDef.tool?._requireApproval
   };
 }
@@ -412,7 +147,7 @@ function toDescriptor(tool) {
     domain: tool.domain,
     resource: tool.resource,
     roles: tool.roles ?? tool.requiredRoles,
-    permissions: tool.permissions,
+    impact: tool.impact ?? "READ_ONLY",
     requireApproval: tool.requireApproval,
     cacheTTL: tool.tool._cacheTTL,
     tags: tool.tags
@@ -500,6 +235,12 @@ var ToolRegistry = class _ToolRegistry {
       return roles.some((role) => roleSet.has(role));
     });
   }
+  /**
+   * Filters tools matching a specific physical impact profile (READ_ONLY, MUTATIVE, DESTRUCTIVE).
+   */
+  getByImpact(impact) {
+    return this.getAll().filter((item) => (item.impact ?? "READ_ONLY") === impact);
+  }
   /**
    * Exports headless technical descriptors without UI rendering coupling.
    */
@@ -511,6 +252,9 @@ var ToolRegistry = class _ToolRegistry {
     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);
   }
   /**
@@ -538,6 +282,18 @@ var ToolRegistry = class _ToolRegistry {
 };
 
 // src/agent/strategy.ts
+var IMPACT_WEIGHTS = {
+  READ_ONLY: 1,
+  MUTATIVE: 2,
+  DESTRUCTIVE: 3
+};
+function matchesMaxImpact(tool, maxImpact) {
+  if (!maxImpact) {
+    return true;
+  }
+  const toolImpact = tool.impact ?? "READ_ONLY";
+  return IMPACT_WEIGHTS[toolImpact] <= IMPACT_WEIGHTS[maxImpact];
+}
 var PhaseBasedToolStrategy = class {
   selectTools(tools, context) {
     if (!context.phase) {
@@ -570,6 +326,24 @@ var RoleBasedToolStrategy = class {
     });
   }
 };
+var ReadOnlyToolStrategy = class {
+  selectTools(tools, _context) {
+    return tools.filter((tool) => (tool.impact ?? "READ_ONLY") === "READ_ONLY");
+  }
+};
+var MaxImpactToolStrategy = class {
+  maxImpact;
+  constructor(maxImpact) {
+    this.maxImpact = maxImpact;
+  }
+  selectTools(tools, _context) {
+    const maxWeight = IMPACT_WEIGHTS[this.maxImpact];
+    return tools.filter((tool) => {
+      const toolImpact = tool.impact ?? "READ_ONLY";
+      return IMPACT_WEIGHTS[toolImpact] <= maxWeight;
+    });
+  }
+};
 function matchesDomain(tool, allowedDomains) {
   if (!allowedDomains) {
     return true;
@@ -593,23 +367,18 @@ function matchesRoles(tool, context) {
   }
   return toolRoles.some((roleName) => userRoles.includes(roleName));
 }
-function matchesPermissions(tool, context) {
-  if (!tool.permissions || tool.permissions.length === 0) {
-    return true;
-  }
-  const userPermissions = context.permissions ?? [];
-  return tool.permissions.every((permissionName) => userPermissions.includes(permissionName));
-}
 var AccessControlToolStrategy = class {
   allowedDomains;
+  maxImpact;
   constructor(options) {
     if (options?.allowedDomains) {
       this.allowedDomains = new Set(options.allowedDomains);
     }
+    this.maxImpact = options?.maxImpact;
   }
   selectTools(tools, context) {
     return tools.filter(
-      (tool) => matchesDomain(tool, this.allowedDomains) && matchesRoles(tool, context) && matchesPermissions(tool, context)
+      (tool) => matchesDomain(tool, this.allowedDomains) && matchesRoles(tool, context) && matchesMaxImpact(tool, this.maxImpact)
     );
   }
 };
@@ -1867,11 +1636,13 @@ export {
   DtoValidationError,
   HttpTelemetryExporter,
   KeyValueStorageAdapter,
+  MaxImpactToolStrategy,
   MemoryStorageAdapter,
   PhaseBasedToolStrategy,
   PiiLeakError,
   PlatformStorageAdapter,
   PrismaStorageAdapter,
+  ReadOnlyToolStrategy,
   RoleBasedToolStrategy,
   SQLiteStorageAdapter,
   StepExecutionError,

package/dist/agent/isolated-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isolated-tool.d.ts","sourceRoot":"","sources":["../../src/agent/isolated-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAElB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAoHjB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,GAAG,GAAG,EACX,OAAO,GAAG,GAAG,EACb,OAAO,GAAG,OAAO,EACjB,UAAU,GAAG,OAAO,EAEpB,MAAM,EAAE,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,GAC9D,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CA8DlC"}
+{"version":3,"file":"isolated-tool.d.ts","sourceRoot":"","sources":["../../src/agent/isolated-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAElB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAoHjB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,GAAG,GAAG,EACX,OAAO,GAAG,GAAG,EACb,OAAO,GAAG,OAAO,EACjB,UAAU,GAAG,OAAO,EAEpB,MAAM,EAAE,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,GAC9D,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAgElC"}

package/dist/agent/registry.d.ts

@@ -1,4 +1,4 @@
-import type { RegisteredTool, ToolDescriptor, VercelAiCoreTool } from "./types";
+import type { RegisteredTool, ToolDescriptor, ToolImpact, VercelAiCoreTool } from "./types";
 export interface ToRecordOptions {
     anonymize?: boolean;
     domain?: string;
@@ -6,9 +6,10 @@ export interface ToRecordOptions {
 export interface ToolDescriptorFilter {
     domain?: string;
     role?: string;
+    impact?: ToolImpact;
 }
 /**
- * Centralized catalog for managing and filtering tools with permissions, domains and metadata.
+ * Centralized catalog for managing and filtering tools with roles, domains, impact and metadata.
  * Supports O(1) Key-Value lookup by technical ID and by public alias.
  */
 export declare class ToolRegistry {
@@ -54,6 +55,10 @@ export declare class ToolRegistry {
      * Filters tools matching the user's roles (RBAC).
      */
     filterByRoles(userRoles: string[]): RegisteredTool[];
+    /**
+     * Filters tools matching a specific physical impact profile (READ_ONLY, MUTATIVE, DESTRUCTIVE).
+     */
+    getByImpact(impact: ToolImpact): RegisteredTool[];
     /**
      * Exports headless technical descriptors without UI rendering coupling.
      */