avantgate 1.1.2 → 1.2.1

package/dist/agent/index.mjs

@@ -40,12 +40,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 {
@@ -148,6 +155,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;
@@ -199,6 +225,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,
@@ -207,20 +234,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;
@@ -230,6 +278,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 }).
@@ -256,20 +316,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
@@ -303,6 +359,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();
@@ -310,16 +425,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.
    */
@@ -350,6 +470,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.
    */
@@ -367,12 +493,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.
    */
@@ -384,8 +524,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;
     }
@@ -411,17 +555,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) {
@@ -1669,6 +1860,7 @@ var HttpTelemetryExporter = class {
   }
 };
 export {
+  AccessControlToolStrategy,
   AgentToolFactory,
   CircularToolCallError,
   CompositeToolStrategy,

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

@@ -0,0 +1,9 @@
+import type { IsolatedToolConfig, VercelAiCoreTool } from "./types";
+/**
+ * Creates an isolated tool compatible with Vercel AI SDK (ai) tool contract.
+ * Features dual-channel separation (client data vs minimal LLM DTO),
+ * access governance (domain, resource, roles, dataAccessGuard, invalidationTags),
+ * stable ID, aliasing, caching, Zod DTO contract validation, and automatic in-flight PII redaction.
+ */
+export declare function createIsolatedTool<TArgs = any, TResult = any, TLLMDto = unknown, TClientDto = TResult>(config: IsolatedToolConfig<TArgs, TResult, TLLMDto, TClientDto>): VercelAiCoreTool<TArgs, TResult>;
+//# sourceMappingURL=isolated-tool.d.ts.map

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

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

package/dist/agent/registry.d.ts

@@ -0,0 +1,71 @@
+import type { RegisteredTool, ToolDescriptor, VercelAiCoreTool } from "./types";
+export interface ToRecordOptions {
+    anonymize?: boolean;
+    domain?: string;
+}
+export interface ToolDescriptorFilter {
+    domain?: string;
+    role?: string;
+}
+/**
+ * Centralized catalog for managing and filtering tools with permissions, domains and metadata.
+ * Supports O(1) Key-Value lookup by technical ID and by public alias.
+ */
+export declare class ToolRegistry {
+    private readonly toolsById;
+    private readonly toolsByPublicName;
+    /**
+     * Registers a new tool in the registry.
+     */
+    register(toolDef: RegisteredTool | VercelAiCoreTool): this;
+    /**
+     * Registers multiple tools in batch.
+     */
+    registerMany(tools: (RegisteredTool | VercelAiCoreTool)[]): this;
+    /**
+     * Retrieves a tool by its ID or public name/alias.
+     */
+    get(idOrName: string): RegisteredTool | undefined;
+    /**
+     * Retrieves a tool strictly by its immutable technical ID (O(1)).
+     */
+    getById(id: string): RegisteredTool | undefined;
+    /**
+     * Retrieves a tool by its public alias seen by the LLM (O(1)).
+     */
+    getByPublicName(publicName: string): RegisteredTool | undefined;
+    /**
+     * Checks if a tool is registered by ID or public name.
+     */
+    has(idOrName: string): boolean;
+    /**
+     * Returns all registered tools without duplicates.
+     */
+    getAll(): RegisteredTool[];
+    /**
+     * Filters tools belonging to a specific business domain.
+     */
+    getByDomain(domain: string): RegisteredTool[];
+    /**
+     * Filters tools matching a specific workflow phase.
+     */
+    getByPhase(phase: string): RegisteredTool[];
+    /**
+     * Filters tools matching the user's roles (RBAC).
+     */
+    filterByRoles(userRoles: string[]): RegisteredTool[];
+    /**
+     * Exports headless technical descriptors without UI rendering coupling.
+     */
+    getDescriptors(filter?: ToolDescriptorFilter): ToolDescriptor[];
+    /**
+     * Converts instance registered tools to the record map format required by Vercel AI SDK.
+     */
+    toRecord(options?: ToRecordOptions): Record<string, VercelAiCoreTool>;
+    /**
+     * Converts a list of registered tools to the record map format required by Vercel AI SDK.
+     * If anonymize is true, uses alias (if defined) as dictionary key instead of technical name.
+     */
+    static toRecord(tools: RegisteredTool[], options?: ToRecordOptions): Record<string, VercelAiCoreTool>;
+}
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agent/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhF,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqC;IAEvE;;OAEG;IACI,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,gBAAgB,GAAG,IAAI;IASjE;;OAEG;IACI,YAAY,CAAC,KAAK,EAAE,CAAC,cAAc,GAAG,gBAAgB,CAAC,EAAE,GAAG,IAAI;IAOvE;;OAEG;IACI,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIxD;;OAEG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAItD;;OAEG;IACI,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAItE;;OAEG;IACI,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIrC;;OAEG;IACI,MAAM,IAAI,cAAc,EAAE;IAIjC;;OAEG;IACI,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE;IAIpD;;OAEG;IACI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IASlD;;OAEG;IACI,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE;IAW3D;;OAEG;IACI,cAAc,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,cAAc,EAAE;IAWtE;;OAEG;IACI,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAIhF;;;OAGG;WACW,QAAQ,CACpB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC;CAYpC"}

package/dist/agent/step-runner.d.ts

@@ -0,0 +1,12 @@
+import type { StepRunnerConfig, StepRunnerContext, StepStorageAdapter } from "./types";
+export interface StepRunnerInstance extends StepRunnerContext {
+    storage: StepStorageAdapter;
+    approveStep<T = unknown>(stepId: string, approvalData?: T): Promise<void>;
+    rejectStep(stepId: string, reason?: string): Promise<void>;
+}
+/**
+ * Creates a serverless durable step runner for stateful multi-step agent execution
+ * with automatic idempotence and Human-in-the-Loop approval capability.
+ */
+export declare function createStepRunner(config: StepRunnerConfig): StepRunnerInstance;
+//# sourceMappingURL=step-runner.d.ts.map

package/dist/agent/step-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-runner.d.ts","sourceRoot":"","sources":["../../src/agent/step-runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,OAAO,EAAE,kBAAkB,CAAC;IAC5B,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAkGD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CA0B7E"}

package/dist/agent/strategy.d.ts

@@ -0,0 +1,37 @@
+import type { RegisteredTool, ToolContext, ToolSelectionStrategy, VercelAiCoreTool } from "./types";
+/**
+ * Strategy selecting tools that match the current workflow phase.
+ */
+export declare class PhaseBasedToolStrategy implements ToolSelectionStrategy {
+    selectTools(tools: RegisteredTool[], context: ToolContext): RegisteredTool[];
+}
+/**
+ * Strategy selecting tools permitted for the user's role (RBAC).
+ */
+export declare class RoleBasedToolStrategy implements ToolSelectionStrategy {
+    selectTools(tools: RegisteredTool[], context: ToolContext): RegisteredTool[];
+}
+export interface AccessControlToolStrategyOptions {
+    allowedDomains?: string[];
+}
+/**
+ * Unified strategy evaluating role, permissions and allowed business domains in a single pass.
+ */
+export declare class AccessControlToolStrategy implements ToolSelectionStrategy {
+    private readonly allowedDomains?;
+    constructor(options?: AccessControlToolStrategyOptions);
+    selectTools(tools: RegisteredTool[], context: ToolContext): RegisteredTool[];
+}
+/**
+ * Composite strategy applying multiple selection strategies sequentially (intersection).
+ */
+export declare class CompositeToolStrategy implements ToolSelectionStrategy {
+    private readonly strategies;
+    constructor(strategies: ToolSelectionStrategy[]);
+    selectTools(tools: RegisteredTool[], context: ToolContext): Promise<RegisteredTool[]>;
+}
+/**
+ * Convenience helper to execute a strategy and convert selected tools to Vercel AI SDK format.
+ */
+export declare function applyToolStrategy(tools: RegisteredTool[], strategy: ToolSelectionStrategy, context: ToolContext): Promise<Record<string, VercelAiCoreTool>>;
+//# sourceMappingURL=strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/agent/strategy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,sBAAuB,YAAW,qBAAqB;IAC3D,WAAW,CAChB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,WAAW,GACnB,cAAc,EAAE;CAYpB;AAED;;GAEG;AACH,qBAAa,qBAAsB,YAAW,qBAAqB;IAC1D,WAAW,CAChB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,WAAW,GACnB,cAAc,EAAE;CAgBpB;AAED,MAAM,WAAW,gCAAgC;IAC/C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAmCD;;GAEG;AACH,qBAAa,yBAA0B,YAAW,qBAAqB;IACrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAc;gBAElC,OAAO,CAAC,EAAE,gCAAgC;IAM/C,WAAW,CAChB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,WAAW,GACnB,cAAc,EAAE;CAQpB;AAED;;GAEG;AACH,qBAAa,qBAAsB,YAAW,qBAAqB;IACjE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;gBAEzC,UAAU,EAAE,qBAAqB,EAAE;IAIlC,WAAW,CACtB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,EAAE,CAAC;CAO7B;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAG3C"}

package/dist/agent/telemetry/http-exporter.d.ts

@@ -0,0 +1,24 @@
+import type { HttpTelemetryExporterOptions, TelemetryEvent, TelemetryUsageSummary } from "./types";
+/**
+ * Asynchronous, zero-dependency HTTP Telemetry Exporter for the avantGate platform.
+ * Batches events in memory and sends them in background without blocking agent execution.
+ */
+export declare class HttpTelemetryExporter {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly agentName?;
+    private readonly batchIntervalMs;
+    private readonly maxBatchSize;
+    private readonly maxQueueSize;
+    private readonly fetchFn;
+    private readonly onError?;
+    private queue;
+    private timer;
+    private isFlushing;
+    constructor(options: HttpTelemetryExporterOptions);
+    private startTimer;
+    enqueue(runId: string, event: TelemetryEvent, usage?: TelemetryUsageSummary): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=http-exporter.d.ts.map

package/dist/agent/telemetry/http-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-exporter.d.ts","sourceRoot":"","sources":["../../../src/agent/telemetry/http-exporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAC5B,cAAc,EAEd,qBAAqB,EACtB,MAAM,SAAS,CAAC;AA6EjB;;;GAGG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAyB;IAElD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,4BAA4B;IAajD,OAAO,CAAC,UAAU;IAWX,OAAO,CACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,cAAc,EACrB,KAAK,CAAC,EAAE,qBAAqB,GAC5B,IAAI;IAWM,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAOvC"}

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

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./http-exporter";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent/telemetry/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC"}

package/dist/agent/telemetry/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Supported telemetry event types for the avantGate observability platform.
+ */
+export type TelemetryEventType = "STEP_START" | "STEP_COMPLETED" | "STEP_FAILED" | "STEP_APPROVAL_REQUEST" | "TOOL_EXECUTION";
+/**
+ * Base properties shared across all telemetry events.
+ */
+export interface BaseTelemetryEvent {
+    type: TelemetryEventType;
+    timestamp: string;
+}
+export interface StepStartEvent extends BaseTelemetryEvent {
+    type: "STEP_START";
+    stepName: string;
+    metadata?: Record<string, unknown>;
+}
+export interface StepCompletedEvent extends BaseTelemetryEvent {
+    type: "STEP_COMPLETED";
+    stepName: string;
+    durationMs?: number;
+    piiDetectedCount?: number;
+    resultSummary?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface StepFailedEvent extends BaseTelemetryEvent {
+    type: "STEP_FAILED";
+    stepName: string;
+    durationMs?: number;
+    error: string;
+}
+export interface StepApprovalRequestEvent extends BaseTelemetryEvent {
+    type: "STEP_APPROVAL_REQUEST";
+    stepName: string;
+    actionType?: string;
+    payloadSummary?: unknown;
+}
+export interface ToolExecutionTelemetryEvent extends BaseTelemetryEvent {
+    type: "TOOL_EXECUTION";
+    toolId: string;
+    toolName: string;
+    aliasUsed?: string;
+    durationMs: number;
+    success: boolean;
+    parentToolId?: string;
+    depth?: number;
+    llmSummary?: unknown;
+    piiFilteredCount?: number;
+    tokenCount?: number;
+    tokens?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    costUsd?: number;
+    cached?: boolean;
+    error?: string;
+}
+export type TelemetryEvent = StepStartEvent | StepCompletedEvent | StepFailedEvent | StepApprovalRequestEvent | ToolExecutionTelemetryEvent;
+/**
+ * Consolidates token usage and FinOps metrics for a batch or run.
+ */
+export interface TelemetryUsageSummary {
+    model?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+}
+/**
+ * Payload schema ingested by POST /api/v1/ingest/events according to DESIGN-005 §5.1.
+ */
+export interface TelemetryIngestPayload {
+    runId: string;
+    agentName?: string;
+    timestamp: string;
+    events: TelemetryEvent[];
+    usage?: TelemetryUsageSummary;
+}
+/**
+ * Configuration options for the HTTP Telemetry Exporter.
+ */
+export interface HttpTelemetryExporterOptions {
+    apiKey: string;
+    endpoint?: string;
+    agentName?: string;
+    batchIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    fetchFn?: typeof fetch;
+    onError?: (error: Error) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/telemetry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agent/telemetry/types.ts"],"names":[],"mappings":"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"}

package/dist/agent/tool-invoker.d.ts

@@ -0,0 +1,17 @@
+import { ToolRegistry } from "./registry";
+import type { StepStorageAdapter, ToolExecutionContext } from "./types";
+export interface ToolInvokerOptions {
+    maxDepth?: number;
+    maxTotalSubCalls?: number;
+    workflowId?: string;
+    stepId?: string;
+}
+export interface ToolInvoker {
+    invokeTool<TResult = unknown>(toolId: string, args: unknown, context?: ToolExecutionContext): Promise<TResult>;
+}
+/**
+ * Creates an intelligent, concurrency-safe tool invoker with cycle detection,
+ * depth guard, result caching, and database execution tracing.
+ */
+export declare function createToolInvoker(registry: ToolRegistry, storage?: StepStorageAdapter, options?: ToolInvokerOptions): ToolInvoker;
+//# sourceMappingURL=tool-invoker.d.ts.map