avantgate 1.3.0 → 1.4.0

package/dist/index.js

@@ -33,11 +33,15 @@ __export(index_exports, {
   PromptRegistry: () => PromptRegistry,
   PromptTemplate: () => PromptTemplate,
   SEED_MODEL_PRICES: () => SEED_MODEL_PRICES,
+  WorkflowSagaRollbackError: () => WorkflowSagaRollbackError,
+  WorkflowValidationError: () => WorkflowValidationError,
   ZenLLMControlLayer: () => AvantGateControlLayer,
   calculateCostUSD: () => calculateCostUSD,
   createAvantGate: () => createAvantGate,
   createHttpProviderClient: () => createHttpProviderClient,
   createLLMControlLayer: () => createLLMControlLayer,
+  defineWorkflow: () => defineWorkflow,
+  executeWorkflow: () => executeWorkflow,
   extractAndCleanJSON: () => extractAndCleanJSON,
   resolveModelPrice: () => resolveModelPrice,
   resolveModelPriceAsync: () => resolveModelPriceAsync,
@@ -1629,6 +1633,476 @@ var PromptRegistry = class {
     this.registry.clear();
   }
 };
+
+// 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 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 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 toolImpact = config.impact ?? "READ_ONLY";
+  const requireApproval = config.requireApproval ?? toolImpact === "DESTRUCTIVE";
+  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,
+    _impact: toolImpact,
+    _requireApproval: requireApproval,
+    _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;
+}
+
+// src/workflow/errors.ts
+var WorkflowSagaRollbackError = class extends Error {
+  workflowId;
+  failedStepId;
+  originalError;
+  compensatedSteps;
+  failedCompensations;
+  constructor(params) {
+    const errorDetails = params.originalError instanceof Error ? params.originalError.message : String(params.originalError);
+    super(
+      `\xC9chec de l'\xE9tape '${params.failedStepId}' dans le workflow '${params.workflowId}'. Rollback Saga ex\xE9cut\xE9 sur [${params.compensatedSteps.join(", ")}]. Cause initiale: ${errorDetails}`
+    );
+    this.name = "WorkflowSagaRollbackError";
+    this.workflowId = params.workflowId;
+    this.failedStepId = params.failedStepId;
+    this.originalError = params.originalError;
+    this.compensatedSteps = params.compensatedSteps;
+    this.failedCompensations = params.failedCompensations ?? [];
+  }
+};
+var WorkflowValidationError = class extends Error {
+  workflowId;
+  issues;
+  constructor(workflowId, issues) {
+    super(`Validation des entr\xE9es \xE9chou\xE9e pour le workflow '${workflowId}'.`);
+    this.name = "WorkflowValidationError";
+    this.workflowId = workflowId;
+    this.issues = issues;
+  }
+};
+
+// src/workflow/engine.ts
+function generateRunId(workflowId) {
+  const timestamp = Date.now();
+  const randomSuffix = Math.random().toString(36).substring(2, 9);
+  return `run_${workflowId}_${timestamp}_${randomSuffix}`;
+}
+function validateInput(config, input) {
+  const parseResult = config.inputSchema.safeParse(input);
+  if (!parseResult.success) {
+    throw new WorkflowValidationError(config.id, parseResult.error.issues);
+  }
+  return parseResult.data;
+}
+function createStepContext(params) {
+  const { workflowId, stepId, runId, context, stepResults } = params;
+  return {
+    workflowId,
+    stepId,
+    runId,
+    tenantId: context?.tenantId,
+    userId: context?.userId,
+    services: context?.services ?? {},
+    storage: context?.storage,
+    getStepResult: (id) => stepResults[id],
+    waitForApproval: async (options) => {
+      if (context?.storage) {
+        const existing = await context.storage.getStep(workflowId, stepId);
+        if (existing && existing.status === "COMPLETED") {
+          return existing.result ?? options?.defaultResult;
+        }
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        await context.storage.saveStep({
+          workflowId,
+          stepId,
+          runId,
+          status: "WAITING_APPROVAL",
+          metadata: options?.metadata,
+          createdAt: now,
+          updatedAt: now
+        });
+      }
+      throw new StepSuspendedError(stepId, workflowId, options?.prompt);
+    }
+  };
+}
+async function rollbackSaga(params) {
+  const {
+    workflowId,
+    failedStepId,
+    originalError,
+    completedSteps,
+    input,
+    runId,
+    context,
+    stepResults
+  } = params;
+  const compensatedSteps = [];
+  const failedCompensations = [];
+  for (let i = completedSteps.length - 1; i >= 0; i--) {
+    const { step, result } = completedSteps[i];
+    if (!step.compensate) {
+      continue;
+    }
+    const stepCtx = createStepContext({
+      workflowId,
+      stepId: step.id,
+      runId,
+      context,
+      stepResults
+    });
+    try {
+      await step.compensate(result, input, stepCtx);
+      compensatedSteps.push(step.id);
+      if (context?.storage) {
+        await context.storage.updateStepStatus(workflowId, step.id, "FAILED", {
+          metadata: { compensated: true }
+        });
+      }
+    } catch (compensationError) {
+      failedCompensations.push({ stepId: step.id, error: compensationError });
+    }
+  }
+  throw new WorkflowSagaRollbackError({
+    workflowId,
+    failedStepId,
+    originalError,
+    compensatedSteps,
+    failedCompensations
+  });
+}
+async function executeWorkflow(config, rawInput, context) {
+  const input = validateInput(config, rawInput);
+  const runId = context?.runId ?? generateRunId(config.id);
+  const stepResults = {};
+  const completedSteps = [];
+  for (const step of config.steps) {
+    const stepCtx = createStepContext({
+      workflowId: config.id,
+      stepId: step.id,
+      runId,
+      context,
+      stepResults
+    });
+    try {
+      const result = await step.execute(input, stepCtx);
+      stepResults[step.id] = result;
+      completedSteps.push({ step, result });
+      if (context?.storage) {
+        await context.storage.updateStepStatus(config.id, step.id, "COMPLETED", { result });
+      }
+    } catch (error) {
+      if (error instanceof StepSuspendedError) {
+        return {
+          workflowId: config.id,
+          runId,
+          status: "WAITING_APPROVAL",
+          stepResults
+        };
+      }
+      await rollbackSaga({
+        workflowId: config.id,
+        failedStepId: step.id,
+        originalError: error,
+        completedSteps,
+        input,
+        runId,
+        context,
+        stepResults
+      });
+    }
+  }
+  const finalOutput = config.outputDto ? config.outputDto(stepResults, input) : stepResults;
+  return {
+    workflowId: config.id,
+    runId,
+    status: "COMPLETED",
+    stepResults,
+    output: finalOutput
+  };
+}
+
+// src/workflow/define-workflow.ts
+function resolveWorkflowImpact(config, options) {
+  if (options?.impact) {
+    return options.impact;
+  }
+  return config.impact ?? "MUTATIVE";
+}
+function resolveRequireApproval(impact, options) {
+  if (options?.requireApproval !== void 0) {
+    return options.requireApproval;
+  }
+  return impact === "DESTRUCTIVE";
+}
+function buildToolExecutionContext(options, toolCtx) {
+  const tenantId = typeof toolCtx?.tenantId === "string" ? toolCtx.tenantId : options?.defaultContext?.tenantId;
+  const userId = typeof toolCtx?.userId === "string" ? toolCtx.userId : options?.defaultContext?.userId;
+  return {
+    tenantId,
+    userId,
+    services: options?.defaultContext?.services ?? {},
+    storage: options?.storage ?? options?.defaultContext?.storage
+  };
+}
+function defineWorkflow(config) {
+  const workflowImpact = config.impact ?? "MUTATIVE";
+  return {
+    id: config.id,
+    name: config.name,
+    description: config.description,
+    impact: workflowImpact,
+    roles: config.roles,
+    config,
+    execute: async (input, context) => {
+      return await executeWorkflow(config, input, context);
+    },
+    asTool: (options) => {
+      const impact = resolveWorkflowImpact(config, options);
+      const requireApproval = resolveRequireApproval(impact, options);
+      const tool = createIsolatedTool({
+        name: config.id,
+        description: config.description ?? config.name,
+        roles: config.roles,
+        impact,
+        requireApproval,
+        parameters: config.inputSchema,
+        invalidationTags: typeof config.invalidationTags === "function" ? async (args, res) => {
+          const resolver = config.invalidationTags;
+          return await resolver(args, res ?? {});
+        } : config.invalidationTags,
+        execute: async (args, toolCtx) => {
+          const executionContext = buildToolExecutionContext(options, toolCtx);
+          const result = await executeWorkflow(config, args, executionContext);
+          return result.output;
+        },
+        llmDto: (result) => result
+      });
+      Object.assign(tool, {
+        _isWorkflow: true,
+        workflowId: config.id,
+        workflowConfig: {
+          totalSteps: config.steps.length,
+          impact
+        }
+      });
+      return tool;
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AvantGateBudgetExceededError,
@@ -1644,11 +2118,15 @@ var PromptRegistry = class {
   PromptRegistry,
   PromptTemplate,
   SEED_MODEL_PRICES,
+  WorkflowSagaRollbackError,
+  WorkflowValidationError,
   ZenLLMControlLayer,
   calculateCostUSD,
   createAvantGate,
   createHttpProviderClient,
   createLLMControlLayer,
+  defineWorkflow,
+  executeWorkflow,
   extractAndCleanJSON,
   resolveModelPrice,
   resolveModelPriceAsync,

package/dist/index.mjs

@@ -1,10 +1,16 @@
-import {
-  sanitizePII
-} from "./chunk-DVCF4CSV.mjs";
 import {
   extractAndCleanJSON,
   validateWithZod
 } from "./chunk-CO26LNFD.mjs";
+import {
+  WorkflowSagaRollbackError,
+  WorkflowValidationError,
+  defineWorkflow,
+  executeWorkflow
+} from "./chunk-DTM2OLCG.mjs";
+import {
+  sanitizePII
+} from "./chunk-5VA3EKPJ.mjs";
 
 // src/types.ts
 var ConfigurationError = class extends Error {
@@ -1043,11 +1049,15 @@ export {
   PromptRegistry,
   PromptTemplate,
   SEED_MODEL_PRICES,
+  WorkflowSagaRollbackError,
+  WorkflowValidationError,
   AvantGateControlLayer as ZenLLMControlLayer,
   calculateCostUSD,
   createAvantGate,
   createHttpProviderClient,
   createLLMControlLayer,
+  defineWorkflow,
+  executeWorkflow,
   extractAndCleanJSON,
   resolveModelPrice,
   resolveModelPriceAsync,

package/dist/workflow/define-workflow.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowConfig, WorkflowInstance } from "./types";
+export declare function defineWorkflow<TInput = any, TOutput = any>(config: WorkflowConfig<TInput, TOutput>): WorkflowInstance<TInput, TOutput>;
+//# sourceMappingURL=define-workflow.d.ts.map

package/dist/workflow/define-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-workflow.d.ts","sourceRoot":"","sources":["../../src/workflow/define-workflow.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,cAAc,EAGd,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAmCjB,wBAAgB,cAAc,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,EACxD,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CA8DnC"}

package/dist/workflow/engine.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowConfig, WorkflowExecutionContext, WorkflowExecutionResult } from "./types";
+export declare function executeWorkflow<TInput, TOutput>(config: WorkflowConfig<TInput, TOutput>, rawInput: TInput, context?: WorkflowExecutionContext): Promise<WorkflowExecutionResult<TOutput>>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/workflow/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/workflow/engine.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,cAAc,EACd,wBAAwB,EACxB,uBAAuB,EAGxB,MAAM,SAAS,CAAC;AAsHjB,wBAAsB,eAAe,CAAC,MAAM,EAAE,OAAO,EACnD,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAyD3C"}

package/dist/workflow/errors.d.ts

@@ -0,0 +1,24 @@
+export interface FailedCompensationRecord {
+    stepId: string;
+    error: unknown;
+}
+export declare class WorkflowSagaRollbackError extends Error {
+    readonly workflowId: string;
+    readonly failedStepId: string;
+    readonly originalError: unknown;
+    readonly compensatedSteps: string[];
+    readonly failedCompensations: FailedCompensationRecord[];
+    constructor(params: {
+        workflowId: string;
+        failedStepId: string;
+        originalError: unknown;
+        compensatedSteps: string[];
+        failedCompensations?: FailedCompensationRecord[];
+    });
+}
+export declare class WorkflowValidationError extends Error {
+    readonly workflowId: string;
+    readonly issues: unknown[];
+    constructor(workflowId: string, issues: unknown[]);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/workflow/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,wBAAwB,EAAE,CAAC;gBAE7C,MAAM,EAAE;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,OAAO,CAAC;QACvB,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,mBAAmB,CAAC,EAAE,wBAAwB,EAAE,CAAC;KAClD;CAiBF;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;gBAEf,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;CAMlD"}

package/dist/workflow/index.d.ts

@@ -0,0 +1,5 @@
+export { defineWorkflow } from "./define-workflow";
+export { executeWorkflow } from "./engine";
+export { WorkflowSagaRollbackError, WorkflowValidationError, type FailedCompensationRecord, } from "./errors";
+export type { WorkflowAsToolOptions, WorkflowConfig, WorkflowExecutionContext, WorkflowExecutionResult, WorkflowInstance, WorkflowStepConfig, WorkflowStepContext, } from "./types";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflow/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,SAAS,CAAC"}