avantgate 1.1.2 → 1.2.1

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

@@ -0,0 +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"}

package/dist/agent/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/agent/index.ts
 var agent_exports = {};
 __export(agent_exports, {
+  AccessControlToolStrategy: () => AccessControlToolStrategy,
   AgentToolFactory: () => AgentToolFactory,
   CircularToolCallError: () => CircularToolCallError,
   CompositeToolStrategy: () => CompositeToolStrategy,
@@ -89,12 +90,19 @@ var StepExecutionError = class extends Error {
 var ToolAccessDeniedError = class extends Error {
   toolName;
   requiredRole;
-  constructor(toolName, requiredRole) {
-    const roleMsg = requiredRole ? ` (requires role "${requiredRole}")` : "";
-    super(`Access denied for tool "${toolName}"${roleMsg}.`);
+  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;
-    this.requiredRole = requiredRole;
+    if (isRole) {
+      this.requiredRole = reasonOrRole;
+    } else {
+      this.reason = reasonOrRole;
+    }
   }
 };
 var CircularToolCallError = class extends Error {
@@ -250,6 +258,25 @@ function auditToolResult(data, options) {
 }
 
 // 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;
@@ -301,6 +328,7 @@ 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,
@@ -309,20 +337,41 @@ function createIsolatedTool(config) {
     _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,
-        toolAlias || config.name
+        toolIdentifier
       );
       tool._lastPiiFilteredCount = protection.count;
       return protection.sanitized;
@@ -332,6 +381,18 @@ function createIsolatedTool(config) {
 }
 
 // src/agent/dto.ts
+function extractWhitelistedFields(data, keys) {
+  const result = {};
+  if (!data || typeof data !== "object") {
+    return result;
+  }
+  for (const key of keys) {
+    if (key in data) {
+      result[key] = data[key];
+    }
+  }
+  return result;
+}
 var dto = {
   /**
    * Generates a boolean acknowledgment for mutations ({ success: true | false }).
@@ -358,20 +419,16 @@ var dto = {
     };
   },
   /**
-   * Filters raw output by extracting only a strict whitelist of allowed fields.
+   * Filters raw output by extracting only a whitelist of allowed fields.
+   * Supports optional TSource generic parameter for auto-completion.
    */
-  pick: (keys) => (data) => {
-    const result = {};
-    if (!data || typeof data !== "object") {
-      return result;
-    }
-    for (const key of keys) {
-      if (key in data) {
-        result[key] = data[key];
-      }
-    }
-    return result;
-  }
+  pick: (keys) => (data) => extractWhitelistedFields(data, keys),
+  /**
+   * Compile-time guarded exhaustive projection.
+   * Forces developers to explicitly classify every key of TSource as either 'keep' (sent to LLM)
+   * or 'drop' (ignored), preventing silent schema drift when source types evolve.
+   */
+  exhaustivePick: () => (config) => (data) => extractWhitelistedFields(data, config.keep)
 };
 
 // src/agent/factory.ts
@@ -405,6 +462,65 @@ var AgentToolFactory = class _AgentToolFactory {
 };
 
 // src/agent/registry.ts
+function isCoreTool(item) {
+  return typeof item.execute === "function" && "_toolId" in item;
+}
+function normalizeToolDefinition(toolDef) {
+  if (isCoreTool(toolDef)) {
+    return {
+      id: toolDef._toolId || toolDef._toolName,
+      name: toolDef._toolName,
+      alias: toolDef._toolAlias,
+      description: toolDef.description,
+      domain: toolDef._domain,
+      resource: toolDef._resource,
+      roles: toolDef._roles ? Array.from(toolDef._roles) : void 0,
+      permissions: toolDef._permissions ? Array.from(toolDef._permissions) : void 0,
+      requireApproval: toolDef._requireApproval,
+      tool: 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);
+  return {
+    ...toolDef,
+    id,
+    name: toolDef.name || toolDef.tool?._toolName || id,
+    alias: publicName,
+    domain: toolDef.domain ?? toolDef.tool?._domain,
+    resource: toolDef.resource ?? toolDef.tool?._resource,
+    roles,
+    permissions,
+    requireApproval: toolDef.requireApproval ?? toolDef.tool?._requireApproval
+  };
+}
+function matchesRoleFilter(tool, role) {
+  if (!role) {
+    return true;
+  }
+  const roles = tool.roles ?? tool.requiredRoles;
+  if (!roles || roles.length === 0) {
+    return true;
+  }
+  return roles.includes(role);
+}
+function toDescriptor(tool) {
+  return {
+    id: tool.id,
+    name: tool.name,
+    alias: tool.alias,
+    description: tool.description,
+    domain: tool.domain,
+    resource: tool.resource,
+    roles: tool.roles ?? tool.requiredRoles,
+    permissions: tool.permissions,
+    requireApproval: tool.requireApproval,
+    cacheTTL: tool.tool._cacheTTL,
+    tags: tool.tags
+  };
+}
 var ToolRegistry = class _ToolRegistry {
   toolsById = /* @__PURE__ */ new Map();
   toolsByPublicName = /* @__PURE__ */ new Map();
@@ -412,16 +528,21 @@ var ToolRegistry = class _ToolRegistry {
    * Registers a new tool in the registry.
    */
   register(toolDef) {
-    const id = toolDef.id || toolDef.name;
-    const publicName = toolDef.alias || toolDef.name;
-    const normalizedDef = {
-      ...toolDef,
-      id
-    };
-    this.toolsById.set(id, normalizedDef);
+    const normalizedDef = normalizeToolDefinition(toolDef);
+    const publicName = normalizedDef.alias || normalizedDef.name;
+    this.toolsById.set(normalizedDef.id, normalizedDef);
     this.toolsByPublicName.set(publicName, normalizedDef);
     return this;
   }
+  /**
+   * Registers multiple tools in batch.
+   */
+  registerMany(tools) {
+    for (const tool of tools) {
+      this.register(tool);
+    }
+    return this;
+  }
   /**
    * Retrieves a tool by its ID or public name/alias.
    */
@@ -452,6 +573,12 @@ var ToolRegistry = class _ToolRegistry {
   getAll() {
     return Array.from(this.toolsById.values());
   }
+  /**
+   * Filters tools belonging to a specific business domain.
+   */
+  getByDomain(domain) {
+    return this.getAll().filter((item) => item.domain === domain);
+  }
   /**
    * Filters tools matching a specific workflow phase.
    */
@@ -469,12 +596,26 @@ var ToolRegistry = class _ToolRegistry {
   filterByRoles(userRoles) {
     const roleSet = new Set(userRoles);
     return this.getAll().filter((item) => {
-      if (!item.requiredRoles || item.requiredRoles.length === 0) {
+      const roles = item.roles ?? item.requiredRoles;
+      if (!roles || roles.length === 0) {
         return true;
       }
-      return item.requiredRoles.some((role) => roleSet.has(role));
+      return roles.some((role) => roleSet.has(role));
     });
   }
+  /**
+   * Exports headless technical descriptors without UI rendering coupling.
+   */
+  getDescriptors(filter) {
+    let list = this.getAll();
+    if (filter?.domain) {
+      list = list.filter((item) => item.domain === filter.domain);
+    }
+    if (filter?.role) {
+      list = list.filter((item) => matchesRoleFilter(item, filter.role));
+    }
+    return list.map(toDescriptor);
+  }
   /**
    * Converts instance registered tools to the record map format required by Vercel AI SDK.
    */
@@ -486,8 +627,12 @@ var ToolRegistry = class _ToolRegistry {
    * If anonymize is true, uses alias (if defined) as dictionary key instead of technical name.
    */
   static toRecord(tools, options = {}) {
+    let filtered = tools;
+    if (options.domain) {
+      filtered = filtered.filter((item) => item.domain === options.domain);
+    }
     const record = {};
-    for (const item of tools) {
+    for (const item of filtered) {
       const key = options.anonymize && item.alias ? item.alias : item.name;
       record[key] = item.tool;
     }
@@ -513,17 +658,64 @@ var PhaseBasedToolStrategy = class {
 var RoleBasedToolStrategy = class {
   selectTools(tools, context) {
     if (!context.role) {
-      return tools.filter((t) => !t.requiredRoles || t.requiredRoles.length === 0);
+      return tools.filter((toolCandidate) => {
+        const roles = toolCandidate.roles ?? toolCandidate.requiredRoles;
+        return !roles || roles.length === 0;
+      });
     }
     const currentRole = context.role;
     return tools.filter((item) => {
-      if (!item.requiredRoles || item.requiredRoles.length === 0) {
+      const roles = item.roles ?? item.requiredRoles;
+      if (!roles || roles.length === 0) {
         return true;
       }
-      return item.requiredRoles.includes(currentRole);
+      return roles.includes(currentRole);
     });
   }
 };
+function matchesDomain(tool, allowedDomains) {
+  if (!allowedDomains) {
+    return true;
+  }
+  return Boolean(tool.domain && allowedDomains.has(tool.domain));
+}
+function matchesRoles(tool, context) {
+  const toolRoles = tool.roles ?? tool.requiredRoles;
+  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) {
+    return false;
+  }
+  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;
+  constructor(options) {
+    if (options?.allowedDomains) {
+      this.allowedDomains = new Set(options.allowedDomains);
+    }
+  }
+  selectTools(tools, context) {
+    return tools.filter(
+      (tool) => matchesDomain(tool, this.allowedDomains) && matchesRoles(tool, context) && matchesPermissions(tool, context)
+    );
+  }
+};
 var CompositeToolStrategy = class {
   strategies;
   constructor(strategies) {
@@ -1772,6 +1964,7 @@ var HttpTelemetryExporter = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AccessControlToolStrategy,
   AgentToolFactory,
   CircularToolCallError,
   CompositeToolStrategy,