avantgate 1.3.0 → 1.5.0

package/dist/chunk-4XWO3NZW.mjs

@@ -0,0 +1,303 @@
+import {
+  StepSuspendedError,
+  createIsolatedTool
+} from "./chunk-5VA3EKPJ.mjs";
+
+// 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;
+  }
+};
+var WorkflowAbortSignal = class extends Error {
+  __isWorkflowAbort = true;
+  reason;
+  payload;
+  constructor(reason, payload) {
+    super(`Workflow aborted: ${reason}`);
+    this.name = "WorkflowAbortSignal";
+    this.reason = reason;
+    this.payload = payload;
+  }
+};
+var isWorkflowAbortSignal = (value) => {
+  return typeof value === "object" && value !== null && value.__isWorkflowAbort === true;
+};
+
+// src/workflow/engine.ts
+var generateRunId = (workflowId) => {
+  const timestamp = Date.now();
+  const randomSuffix = Math.random().toString(36).substring(2, 9);
+  return `run_${workflowId}_${timestamp}_${randomSuffix}`;
+};
+var validateInput = (config, input) => {
+  const parseResult = config.inputSchema.safeParse(input);
+  if (!parseResult.success) {
+    throw new WorkflowValidationError(config.id, parseResult.error.issues);
+  }
+  return parseResult.data;
+};
+var 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);
+    },
+    abort: (reason, payload) => {
+      throw new WorkflowAbortSignal(reason, payload);
+    }
+  };
+};
+var rollbackSaga = async (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
+  });
+};
+var executeWorkflow = async (config, rawInput, context) => {
+  const input = validateInput(config, rawInput);
+  const runId = context?.runId ?? generateRunId(config.id);
+  const stepResults = {};
+  const completedSteps = [];
+  const handleAbort = async (stepId, signal) => {
+    stepResults[stepId] = {
+      aborted: true,
+      reason: signal.reason,
+      payload: signal.payload
+    };
+    if (context?.storage) {
+      await context.storage.updateStepStatus(config.id, stepId, "ABORTED", {
+        result: signal.payload,
+        metadata: { abortReason: signal.reason }
+      });
+    }
+    const abortOutput = signal.payload ?? {
+      aborted: true,
+      reason: signal.reason
+    };
+    return {
+      workflowId: config.id,
+      runId,
+      status: "ABORTED",
+      stepResults,
+      abortReason: signal.reason,
+      abortPayload: signal.payload,
+      output: abortOutput
+    };
+  };
+  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);
+      if (isWorkflowAbortSignal(result)) {
+        return await handleAbort(step.id, result);
+      }
+      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
+        };
+      }
+      if (isWorkflowAbortSignal(error)) {
+        return await handleAbort(step.id, error);
+      }
+      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
+var resolveWorkflowImpact = (config, options) => {
+  if (options?.impact) {
+    return options.impact;
+  }
+  return config.impact ?? "MUTATIVE";
+};
+var resolveRequireApproval = (impact, options) => {
+  if (options?.requireApproval !== void 0) {
+    return options.requireApproval;
+  }
+  return impact === "DESTRUCTIVE";
+};
+var 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
+  };
+};
+var 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;
+    }
+  };
+};
+
+export {
+  WorkflowSagaRollbackError,
+  WorkflowValidationError,
+  WorkflowAbortSignal,
+  isWorkflowAbortSignal,
+  executeWorkflow,
+  defineWorkflow
+};

package/dist/chunk-5VA3EKPJ.mjs

@@ -0,0 +1,344 @@
+// src/sanitizer.ts
+var EMAIL_REGEX = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,7}\b/g;
+var PHONE_FR_REGEX = /\b(?:(?:\+|00)33|0)\s*[1-9](?:[\s.-]*\d{2}){4}\b/g;
+var NIR_SSN_REGEX = /\b[12]\s*\d{2}\s*(?:0[1-9]|1[0-2]|[2-9]\d)\s*(?:0[1-9]|[1-8]\d|9[0-8]|2[ABab])\s*(?!000)\d{3}\s*(?!000)\d{3}(?:\s*\d{2})?\b/g;
+var SPI_LABELLED_REGEX = /(?:(?:num[ée]ro\s+fiscal|spi|n[°o]\s*fiscal|d[ée]clarant(?: fiscal)?)\s*[:=]?\s*)\b(\d{2}(?:[\s.-]?\d{2}){5}[\s.-]?\d|\d{13})\b/gi;
+var SPI_FORMATTED_REGEX = /\b[0-3]\d(?:\s+\d{2}){5}\s+\d\b/g;
+var IBAN_REGEX = /\b[A-Z]{2}\s*[0-9]{2}(?:[\s\r\n.-]*[A-Z0-9]){11,30}\b/g;
+var BIC_LABELLED_REGEX = /(?:(?:bic|swift)\s*[:=]?\s*)\b([A-Z]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?)\b/gi;
+function sanitizePII(input) {
+  let count = 0;
+  let result = input;
+  result = result.replace(EMAIL_REGEX, () => {
+    count++;
+    return "[REDACTED_EMAIL]";
+  });
+  result = result.replace(PHONE_FR_REGEX, () => {
+    count++;
+    return "[REDACTED_PHONE]";
+  });
+  result = result.replace(IBAN_REGEX, (match) => {
+    const cleanChars = match.replace(/[\s\r\n.-]/g, "");
+    if (cleanChars.length >= 15 && cleanChars.length <= 34) {
+      count++;
+      return "[REDACTED_IBAN]";
+    }
+    return match;
+  });
+  result = result.replace(BIC_LABELLED_REGEX, (_, bicCode) => {
+    count++;
+    return `[REDACTED_BIC: ${bicCode.slice(0, 4)}****]`;
+  });
+  result = result.replace(SPI_LABELLED_REGEX, (fullMatch, digits) => {
+    count++;
+    return fullMatch.replace(digits, "[REDACTED_SPI]");
+  });
+  result = result.replace(NIR_SSN_REGEX, (match) => {
+    const rawDigits = match.replace(/\s+/g, "");
+    if (rawDigits.length === 13 || rawDigits.length === 15) {
+      count++;
+      return "[REDACTED_NIR]";
+    }
+    return match;
+  });
+  result = result.replace(SPI_FORMATTED_REGEX, (match) => {
+    if (!match.includes("[REDACTED")) {
+      count++;
+      return "[REDACTED_SPI]";
+    }
+    return match;
+  });
+  return { text: result, maskedCount: count };
+}
+
+// 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 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;
+}
+
+export {
+  sanitizePII,
+  StepSuspendedError,
+  PiiLeakError,
+  StepExecutionError,
+  ToolAccessDeniedError,
+  CircularToolCallError,
+  ToolCallDepthExceededError,
+  ToolSubCallQuotaError,
+  ToolNotFoundError,
+  DtoValidationError,
+  auditToolResult,
+  createIsolatedTool
+};

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export * from "./response-validator";
 export * from "./control-layer";
 export * from "./prompts";
 export * from "./providers/http-client";
+export * from "./workflow";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC"}