avantgate 1.1.1 → 1.2.0

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,9 +20,11 @@ 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,
+  DtoValidationError: () => DtoValidationError,
   HttpTelemetryExporter: () => HttpTelemetryExporter,
   KeyValueStorageAdapter: () => KeyValueStorageAdapter,
   MemoryStorageAdapter: () => MemoryStorageAdapter,
@@ -45,7 +47,8 @@ __export(agent_exports, {
   createIsolatedTool: () => createIsolatedTool,
   createStepRunner: () => createStepRunner,
   createToolInvoker: () => createToolInvoker,
-  createToolSharedState: () => createToolSharedState
+  createToolSharedState: () => createToolSharedState,
+  dto: () => dto
 });
 module.exports = __toCommonJS(agent_exports);
 
@@ -87,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 {
@@ -131,6 +141,16 @@ var ToolNotFoundError = class extends Error {
     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/sanitizer.ts
 var EMAIL_REGEX = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,7}\b/g;
@@ -238,18 +258,50 @@ 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;
   }
   await callback(rawResult);
 }
-function produceLlmPayload(rawResult, args, transformer) {
+async function produceLlmPayload(rawResult, args, context, transformer) {
   if (transformer) {
-    return transformer(rawResult, args);
+    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 };
@@ -260,9 +312,23 @@ function protectLlmPayload(payload, toolIdentifier, sanitizePii = true, throwOnP
   });
   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,
@@ -271,24 +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);
-      await dispatchClientData(rawResult, config.toClientData);
-      const llmPayload = produceLlmPayload(
-        rawResult,
+      const tags = await resolveInvalidationTags(
+        config,
         args,
-        config.toLLMSummary
+        rawResult,
+        updatedContext
       );
-      const protection = protectLlmPayload(
-        llmPayload,
-        toolAlias || config.name,
-        config.sanitizePii !== false,
-        config.throwOnPii === true
+      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;
@@ -297,6 +380,49 @@ function createIsolatedTool(config) {
   return tool;
 }
 
+// src/agent/dto.ts
+var dto = {
+  /**
+   * Generates a boolean acknowledgment for mutations ({ success: true | false }).
+   * If rawResult contains a boolean `success` property, it is preserved; otherwise defaults to true.
+   */
+  boolean: () => (data) => ({
+    success: typeof data?.success === "boolean" ? data.success : true
+  }),
+  /**
+   * Generates a boolean acknowledgment preserving an opaque technical identifier for tool chaining.
+   */
+  booleanWithId: (idKey = "id") => (data) => ({
+    success: typeof data?.success === "boolean" ? data.success : true,
+    [idKey]: data?.[idKey]
+  }),
+  /**
+   * Extracts a numeric count from a list or nested array property without exposing items to the LLM.
+   */
+  count: (arrayKey) => (data) => {
+    const list = arrayKey ? data?.[arrayKey] : data;
+    return {
+      success: true,
+      count: Array.isArray(list) ? list.length : 0
+    };
+  },
+  /**
+   * Filters raw output by extracting only a strict whitelist of allowed fields.
+   */
+  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;
+  }
+};
+
 // src/agent/factory.ts
 var AgentToolFactory = class _AgentToolFactory {
   context;
@@ -328,6 +454,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();
@@ -335,16 +520,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.
    */
@@ -375,6 +565,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.
    */
@@ -392,12 +588,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.
    */
@@ -409,8 +619,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;
     }
@@ -436,17 +650,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) {
@@ -1695,9 +1956,11 @@ var HttpTelemetryExporter = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AccessControlToolStrategy,
   AgentToolFactory,
   CircularToolCallError,
   CompositeToolStrategy,
+  DtoValidationError,
   HttpTelemetryExporter,
   KeyValueStorageAdapter,
   MemoryStorageAdapter,
@@ -1720,5 +1983,6 @@ var HttpTelemetryExporter = class {
   createIsolatedTool,
   createStepRunner,
   createToolInvoker,
-  createToolSharedState
+  createToolSharedState,
+  dto
 });