avantgate 1.8.0 → 1.9.0

package/dist/client/task-types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Context provided to task handlers during execution.
+ */
+export interface TaskExecutionContext {
+    parentRunId?: string;
+    attempt: number;
+    taskId: string;
+    tenantId?: string;
+}
+/**
+ * Configuration options for the useTask hook.
+ */
+export interface UseTaskOptions<TInput, TOutput> {
+    taskName: string;
+    tenantId?: string;
+    tenantSalt?: string;
+    maxManualRetries?: number;
+    handler: (input: TInput, context: TaskExecutionContext) => Promise<TOutput>;
+    onSuccess?: (data: TOutput) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * State snapshot of the task lifecycle.
+ */
+export interface TaskState<TOutput> {
+    isRunning: boolean;
+    isFailed: boolean;
+    isSuccess: boolean;
+    attempts: number;
+    error: Error | null;
+    data: TOutput | null;
+    runId: string | null;
+    parentRunId: string | null;
+    taskId: string;
+    tenantId: string | null;
+}
+/**
+ * Return interface of useTask.
+ */
+export interface UseTaskReturn<TInput, TOutput> extends TaskState<TOutput> {
+    run: (input: TInput) => Promise<TOutput>;
+    retry: () => Promise<TOutput>;
+    reset: () => void;
+}
+//# sourceMappingURL=task-types.d.ts.map

package/dist/client/task-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-types.d.ts","sourceRoot":"","sources":["../../src/client/task-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,EAAE,OAAO;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,OAAO;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,EAAE,OAAO,CAAE,SAAQ,SAAS,CAAC,OAAO,CAAC;IACxE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB"}

package/dist/client/task-utils.d.ts

@@ -0,0 +1,29 @@
+import { TaskState } from "./task-types";
+/**
+ * Derives an opaque task identifier using HMAC-SHA256 with tenant salt.
+ * Why: Guarantees Zero-Knowledge Telemetry by obfuscating confidential business operations
+ * (e.g. "wire_transfer", "patient_biopsy") in logs while preserving deterministic correlation.
+ */
+export declare const deriveOpaqueTaskId: (taskName: string, tenantSalt?: string) => string;
+/**
+ * Generates a scoped unique run ID for a task attempt.
+ * Why: Provides deterministic prefixing for APM tracing and Cockpit session linking.
+ */
+export declare const generateRunId: (taskId: string) => string;
+/**
+ * Creates the initial default state for a task.
+ * Why: Reusable reset baseline ensuring consistency across mount and reset cycles.
+ */
+export declare const createInitialTaskState: <TOutput>(taskId: string, tenantId?: string) => TaskState<TOutput>;
+export interface RetryValidationParams {
+    isRunning: boolean;
+    attemptCount: number;
+    maxRetries: number;
+    hasPreviousInput: boolean;
+}
+/**
+ * Validates whether a retry attempt is permitted.
+ * Why: Protects against FinOps token budget exhaustion and UI double-click race conditions.
+ */
+export declare const validateRetryEligibility: ({ isRunning, attemptCount, maxRetries, hasPreviousInput, }: RetryValidationParams) => void;
+//# sourceMappingURL=task-utils.d.ts.map

package/dist/client/task-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-utils.d.ts","sourceRoot":"","sources":["../../src/client/task-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,aAAa,MAAM,KAAG,MAS1E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,KAAG,MAI9C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,EAC5C,QAAQ,MAAM,EACd,WAAW,MAAM,KAChB,SAAS,CAAC,OAAO,CAWlB,CAAC;AAEH,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GAAI,4DAKtC,qBAAqB,KAAG,IAU1B,CAAC"}

package/dist/client/useTask.d.ts

@@ -0,0 +1,6 @@
+import { TaskState, TaskExecutionContext, UseTaskOptions, UseTaskReturn } from "./task-types";
+import { deriveOpaqueTaskId } from "./task-utils";
+import { createTaskRunner, type TaskRunner, type TaskRunnerOptions } from "./task-runner";
+export { deriveOpaqueTaskId, createTaskRunner, type TaskState, type TaskExecutionContext, type UseTaskOptions, type UseTaskReturn, type TaskRunner, type TaskRunnerOptions, };
+export declare const useTask: <TInput, TOutput>(options: UseTaskOptions<TInput, TOutput>) => UseTaskReturn<TInput, TOutput>;
+//# sourceMappingURL=useTask.d.ts.map

package/dist/client/useTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTask.d.ts","sourceRoot":"","sources":["../../src/client/useTask.ts"],"names":[],"mappings":"AACA,OAAO,EACL,SAAS,EACT,oBAAoB,EACpB,cAAc,EACd,aAAa,EACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,iBAAiB,GACvB,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,MAAM,EAAE,OAAO,EACrC,SAAS,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,KACvC,aAAa,CAAC,MAAM,EAAE,OAAO,CAgD/B,CAAC"}

package/dist/client/useTelemetry.d.ts

@@ -0,0 +1,10 @@
+import { type TrackDataRenderedOptions, type TrackFeedbackOptions, type TrackSecurityAlertDetails } from "./client";
+import type { BrowserTelemetryExporterConfig, ClientSecurityAlertEvent } from "./types";
+export type { TrackDataRenderedOptions, TrackFeedbackOptions, TrackSecurityAlertDetails, };
+export declare const useTelemetry: (config: BrowserTelemetryExporterConfig) => {
+    trackSecurityAlert: (alertType: ClientSecurityAlertEvent["alertType"], details: TrackSecurityAlertDetails) => void;
+    trackClientDataRendered: (toolId: string, options?: TrackDataRenderedOptions) => void;
+    trackFeedback: (feedback: TrackFeedbackOptions) => void;
+    exporter: import("./browser-exporter").BrowserTelemetryExporter | undefined;
+};
+//# sourceMappingURL=useTelemetry.d.ts.map

package/dist/client/useTelemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTelemetry.d.ts","sourceRoot":"","sources":["../../src/client/useTelemetry.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACV,8BAA8B,EAC9B,wBAAwB,EACzB,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,wBAAwB,EACxB,oBAAoB,EACpB,yBAAyB,GAC1B,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,QAAQ,8BAA8B;oCAuBlD,wBAAwB,CAAC,WAAW,CAAC,WACvC,yBAAyB,KACjC,IAAI;sCAQG,MAAM,YACJ,wBAAwB,KACjC,IAAI;8BAOI,oBAAoB,KAAG,IAAI;;CAezC,CAAC"}

package/dist/control-layer.d.ts

@@ -19,18 +19,12 @@ export declare class AvantGateControlLayer {
     private executeProviderPipeline;
     private assembleResult;
     private notifyAuditSink;
-    /**
-     * Exécute une requête avec garde d'entrée, masquage PII, garde pré-vol et calcul des coûts.
-     */
     execute: (options: {
         userQuery: string;
         systemPrompt?: string;
         temperature?: number;
         providerOverride?: LLMProviderPort;
     }) => Promise<ExecutionResult>;
-    /**
-     * Exécute une requête et valide/répare le résultat selon un schéma Zod.
-     */
     executeStructured: <T>(options: {
         userQuery: string;
         systemPrompt?: string;
@@ -38,10 +32,16 @@ export declare class AvantGateControlLayer {
         temperature?: number;
         providerOverride?: LLMProviderPort;
     }) => Promise<StructuredExecutionResult<T>>;
-    /**
-     * Méthode unifiée de premier niveau pour l'extraction structurée sans code boilerplate.
-     * Gère le failover multi-fournisseurs, les retries, la validation Zod et la normalisation financière.
-     */
+    private sanitizeIncomingMessages;
+    private verifyPromptBudget;
+    private dispatchOverrideAttempt;
+    private dispatchSimulatedAttempt;
+    private dispatchPipelineAttempt;
+    private dispatchProviderAttempt;
+    private parseAndValidateStructuredResult;
+    private buildStructuredResult;
+    private notifyAuditSinkSafe;
+    private waitRetryBackoff;
     generateStructuredOutput: <T>(options: GenerateStructuredOutputOptions<T>) => Promise<StructuredExecutionResult<T>>;
 }
 export declare const createLLMControlLayer: (config: ControlLayerConfig) => AvantGateControlLayer;

package/dist/control-layer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control-layer.d.ts","sourceRoot":"","sources":["../src/control-layer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,yBAAyB,EACzB,+BAA+B,EAC/B,eAAe,EAIhB,MAAM,SAAS,CAAC;AAiBjB,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,oBAAoB,CAAC,CAAuB;gBAExC,MAAM,EAAE,kBAAkB;IAgBtC,OAAO,CAAC,qBAAqB,CAU3B;IAEF,OAAO,CAAC,kBAAkB,CAaxB;IAEF,OAAO,CAAC,aAAa,CAcnB;IAEF,OAAO,CAAC,mBAAmB,CAezB;IAEF,OAAO,CAAC,yBAAyB,CAe/B;IAEF,OAAO,CAAC,oBAAoB,CAkC1B;IAEF,OAAO,CAAC,wBAAwB,CAW9B;IAEF,OAAO,CAAC,aAAa,CAOnB;IAEF,OAAO,CAAC,aAAa,CAUnB;IAEF,OAAO,CAAC,gBAAgB,CAMtB;IAEF,OAAO,CAAC,iBAAiB,CAiBvB;IAEF,OAAO,CAAC,uBAAuB,CAmB7B;IAEF,OAAO,CAAC,uBAAuB,CA+B7B;IAEF,OAAO,CAAC,cAAc,CAqBpB;IAEF,OAAO,CAAC,eAAe,CAarB;IAEF;;OAEG;IACH,OAAO,GAAU,SAAS;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,CAAC,EAAE,eAAe,CAAC;KACpC,KAAG,OAAO,CAAC,eAAe,CAAC,CA2B1B;IAEF;;OAEG;IACH,iBAAiB,GAAU,CAAC,EAAE,SAAS;QACrC,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,CAAC,EAAE,eAAe,CAAC;KACpC,KAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAyBvC;IAEF;;;OAGG;IACH,wBAAwB,GAAU,CAAC,EACjC,SAAS,+BAA+B,CAAC,CAAC,CAAC,KAC1C,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAuHtC;CACH;AAED,eAAO,MAAM,qBAAqB,GAAI,QAAQ,kBAAkB,KAAG,qBAElE,CAAC;AAEF,eAAO,MAAM,eAAe,WAJkB,kBAAkB,KAAG,qBAIf,CAAC;AACrD,OAAO,EAAE,qBAAqB,IAAI,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"control-layer.d.ts","sourceRoot":"","sources":["../src/control-layer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,yBAAyB,EACzB,+BAA+B,EAC/B,eAAe,EAIhB,MAAM,SAAS,CAAC;AAiBjB,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,oBAAoB,CAAC,CAAuB;gBAExC,MAAM,EAAE,kBAAkB;IAgBtC,OAAO,CAAC,qBAAqB,CAU3B;IAEF,OAAO,CAAC,kBAAkB,CAaxB;IAEF,OAAO,CAAC,aAAa,CAcnB;IAEF,OAAO,CAAC,mBAAmB,CAezB;IAEF,OAAO,CAAC,yBAAyB,CAe/B;IAEF,OAAO,CAAC,oBAAoB,CAkC1B;IAEF,OAAO,CAAC,wBAAwB,CAW9B;IAEF,OAAO,CAAC,aAAa,CAOnB;IAEF,OAAO,CAAC,aAAa,CAUnB;IAEF,OAAO,CAAC,gBAAgB,CAMtB;IAEF,OAAO,CAAC,iBAAiB,CAsBvB;IAEF,OAAO,CAAC,uBAAuB,CAmB7B;IAEF,OAAO,CAAC,uBAAuB,CA+B7B;IAEF,OAAO,CAAC,cAAc,CAqBpB;IAEF,OAAO,CAAC,eAAe,CAarB;IAEF,OAAO,GAAU,SAAS;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,CAAC,EAAE,eAAe,CAAC;KACpC,KAAG,OAAO,CAAC,eAAe,CAAC,CA2B1B;IAGF,iBAAiB,GAAU,CAAC,EAAE,SAAS;QACrC,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,CAAC,EAAE,eAAe,CAAC;KACpC,KAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAyBvC;IAEF,OAAO,CAAC,wBAAwB,CAO9B;IAEF,OAAO,CAAC,kBAAkB,CAIxB;IAEF,OAAO,CAAC,uBAAuB,CAe7B;IAEF,OAAO,CAAC,wBAAwB,CAqB9B;IAEF,OAAO,CAAC,uBAAuB,CAkB7B;IAEF,OAAO,CAAC,uBAAuB,CAY7B;IAEF,OAAO,CAAC,gCAAgC,CAiBtC;IAEF,OAAO,CAAC,qBAAqB,CAwB3B;IAEF,OAAO,CAAC,mBAAmB,CAazB;IAEF,OAAO,CAAC,gBAAgB,CAQtB;IAEF,wBAAwB,GAAU,CAAC,EACjC,SAAS,+BAA+B,CAAC,CAAC,CAAC,KAC1C,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAwCtC;CACH;AAED,eAAO,MAAM,qBAAqB,GAAI,QAAQ,kBAAkB,KAAG,qBAElE,CAAC;AAEF,eAAO,MAAM,eAAe,WAJkB,kBAAkB,KAAG,qBAIf,CAAC;AACrD,OAAO,EAAE,qBAAqB,IAAI,kBAAkB,EAAE,CAAC"}

package/dist/index.js

@@ -1419,19 +1419,20 @@ var AvantGateControlLayer = class {
       this.config.emergencyFallback
     ].filter((provider) => Boolean(provider?.client));
   };
-  executeSimulation = (query, systemPrompt) => {
+  executeSimulation = (query, systemPrompt, modelOverride) => {
+    const targetModel = modelOverride ?? this.config.primary.model;
     const promptTokens = Math.ceil(((systemPrompt?.length ?? 0) + query.length) / 4);
     const completionTokens = 50;
-    const cost = this.calculateCost(this.config.primary.model, promptTokens, completionTokens);
+    const cost = this.calculateCost(targetModel, promptTokens, completionTokens);
     return {
-      text: `[AvantGate In-Process Engine] Response simulation for model: ${this.config.primary.model}`,
+      text: `[AvantGate In-Process Engine] Response simulation for model: ${targetModel}`,
       tokens: {
         prompt: promptTokens,
         completion: completionTokens,
         total: promptTokens + completionTokens
       },
       costUSD: cost,
-      modelUsed: this.config.primary.model,
+      modelUsed: targetModel,
       failoverOccurred: false,
       attempts: 1
     };
@@ -1511,9 +1512,6 @@ var AvantGateControlLayer = class {
       attempts: result.attempts
     });
   };
-  /**
-   * Exécute une requête avec garde d'entrée, masquage PII, garde pré-vol et calcul des coûts.
-   */
   execute = async (options) => {
     const sanitizedQuery = this.applySecurityGuards(options.userQuery);
     const messages = this.buildMessages(options.systemPrompt, sanitizedQuery);
@@ -1536,9 +1534,6 @@ var AvantGateControlLayer = class {
     await this.notifyAuditSink(result);
     return result;
   };
-  /**
-   * Exécute une requête et valide/répare le résultat selon un schéma Zod.
-   */
   executeStructured = async (options) => {
     const rawResult = await this.execute({
       userQuery: options.userQuery,
@@ -1562,107 +1557,147 @@ var AvantGateControlLayer = class {
       failoverOccurred: rawResult.failoverOccurred
     };
   };
-  /**
-   * Méthode unifiée de premier niveau pour l'extraction structurée sans code boilerplate.
-   * Gère le failover multi-fournisseurs, les retries, la validation Zod et la normalisation financière.
-   */
-  generateStructuredOutput = async (options) => {
-    const maxRetries = options.maxRetries ?? this.config.retryOptions?.maxRetries ?? 2;
-    const modelToUse = options.model ?? this.config.primary.model;
-    const processedMessages = options.messages.map((msg) => {
+  sanitizeIncomingMessages = (messages) => {
+    return messages.map((msg) => {
       if (msg.role === "user") {
         return { ...msg, content: this.applySecurityGuards(msg.content) };
       }
       return msg;
     });
-    const promptLength = processedMessages.reduce((sum, msg) => sum + msg.content.length, 0);
+  };
+  verifyPromptBudget = async (messages, model) => {
+    const promptLength = messages.reduce((sum, msg) => sum + msg.content.length, 0);
     const estimatedPromptTokens = Math.ceil(promptLength / 4);
-    await this.checkPreflightBudget(estimatedPromptTokens, modelToUse);
+    await this.checkPreflightBudget(estimatedPromptTokens, model);
+  };
+  dispatchOverrideAttempt = async (override, messages, model, temperature) => {
+    const res = await override.complete({ model, messages, temperature: temperature ?? 0.1 });
+    const usage = this.resolveTokens(res.usage, JSON.stringify(messages), res.text);
+    return {
+      responseText: res.text,
+      promptTokens: usage.promptTokens,
+      completionTokens: usage.completionTokens,
+      modelUsed: model,
+      failoverOccurred: false
+    };
+  };
+  dispatchSimulatedAttempt = (messages, modelOverride) => {
+    if (!this.config.mockSimulation) {
+      throw new ConfigurationError(
+        "[AvantGate Configuration Error] No active LLM provider configured. Provide a client implementing LLMProviderPort or configure credentials (apiKey / baseUrl)."
+      );
+    }
+    const sim = this.executeSimulation(JSON.stringify(messages), void 0, modelOverride);
+    const responseText = sim.text.includes("{") ? sim.text : JSON.stringify({ simulation: true, model: sim.modelUsed });
+    return {
+      responseText,
+      promptTokens: sim.tokens.prompt,
+      completionTokens: sim.tokens.completion,
+      modelUsed: sim.modelUsed,
+      failoverOccurred: false
+    };
+  };
+  dispatchPipelineAttempt = async (messages, modelOverride, temperature) => {
+    const output = await this.executeProviderPipeline(
+      messages,
+      JSON.stringify(messages),
+      temperature ?? 0.1,
+      modelOverride
+    );
+    return {
+      responseText: output.responseText,
+      promptTokens: output.usage.promptTokens,
+      completionTokens: output.usage.completionTokens,
+      modelUsed: output.modelUsed,
+      failoverOccurred: output.failoverOccurred
+    };
+  };
+  dispatchProviderAttempt = async (options, messages, targetModel) => {
+    if (options.providerOverride) {
+      return this.dispatchOverrideAttempt(options.providerOverride, messages, targetModel, options.temperature);
+    }
+    if (this.getProviderChain().length === 0) {
+      return this.dispatchSimulatedAttempt(messages, options.model);
+    }
+    return this.dispatchPipelineAttempt(messages, options.model ?? targetModel, options.temperature);
+  };
+  parseAndValidateStructuredResult = (rawText, options) => {
+    const sanitizedResponse = this.applyOutputSecurityGuards(rawText);
+    const isFinancial = options.financialNormalizer ?? Boolean(
+      this.config.features?.finance?.enableFrenchAccounting || this.config.features?.finance
+    );
+    const parsedData = validateWithZod(sanitizedResponse, options.schema, {
+      financialNormalizer: isFinancial,
+      jurisdiction: this.config.features?.finance?.jurisdiction
+    });
+    return { parsedData, sanitizedResponse };
+  };
+  buildStructuredResult = (params) => {
+    const totalTokens = params.promptTokens + params.completionTokens;
+    const costUSD = this.calculateCost(params.modelUsed, params.promptTokens, params.completionTokens);
+    this.checkPostExecutionBudget(totalTokens, costUSD);
+    return {
+      data: params.data,
+      rawText: params.rawText,
+      tokens: {
+        prompt: params.promptTokens,
+        completion: params.completionTokens,
+        total: totalTokens
+      },
+      costUSD,
+      modelUsed: params.modelUsed,
+      failoverOccurred: params.failoverOccurred
+    };
+  };
+  notifyAuditSinkSafe = async (sanitizedText, result, attempts) => {
+    await this.notifyAuditSink({
+      text: sanitizedText,
+      tokens: result.tokens,
+      costUSD: result.costUSD,
+      modelUsed: result.modelUsed,
+      failoverOccurred: result.failoverOccurred,
+      attempts
+    });
+  };
+  waitRetryBackoff = async (attempt, maxRetries) => {
+    if (attempt >= maxRetries) {
+      return;
+    }
+    const initialDelay = this.config.retryOptions?.initialDelayMs ?? 200;
+    const factor = this.config.retryOptions?.backoffFactor ?? 1.5;
+    const delay = initialDelay * Math.pow(factor, attempt);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+  };
+  generateStructuredOutput = async (options) => {
+    const maxRetries = options.maxRetries ?? this.config.retryOptions?.maxRetries ?? 2;
+    const targetModel = options.model ?? this.config.primary.model;
+    const processedMessages = this.sanitizeIncomingMessages(options.messages);
+    await this.verifyPromptBudget(processedMessages, targetModel);
     let lastError;
     let accumulatedPromptTokens = 0;
     let accumulatedCompletionTokens = 0;
-    let failoverOccurred = false;
-    let modelUsed = modelToUse;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
-        let responseText = "";
-        let attemptPromptTokens = 0;
-        let attemptCompletionTokens = 0;
-        if (options.providerOverride) {
-          const res = await options.providerOverride.complete({
-            model: modelToUse,
-            messages: processedMessages,
-            temperature: options.temperature ?? 0.1
-          });
-          responseText = res.text;
-          const usage = this.resolveTokens(res.usage, JSON.stringify(processedMessages), responseText);
-          attemptPromptTokens = usage.promptTokens;
-          attemptCompletionTokens = usage.completionTokens;
-          modelUsed = modelToUse;
-        } else if (this.getProviderChain().length === 0) {
-          if (this.config.mockSimulation) {
-            const sim = this.executeSimulation(JSON.stringify(processedMessages));
-            responseText = sim.text;
-            attemptPromptTokens = sim.tokens.prompt;
-            attemptCompletionTokens = sim.tokens.completion;
-          } else {
-            throw new ConfigurationError(
-              "[AvantGate Configuration Error] No active LLM provider configured. Provide a client implementing LLMProviderPort or configure credentials (apiKey / baseUrl)."
-            );
-          }
-        } else {
-          const output = await this.executeProviderPipeline(
-            processedMessages,
-            JSON.stringify(processedMessages),
-            options.temperature ?? 0.1,
-            options.model
-          );
-          responseText = output.responseText;
-          attemptPromptTokens = output.usage.promptTokens;
-          attemptCompletionTokens = output.usage.completionTokens;
-          modelUsed = output.modelUsed;
-          failoverOccurred = output.failoverOccurred;
-        }
-        accumulatedPromptTokens += attemptPromptTokens;
-        accumulatedCompletionTokens += attemptCompletionTokens;
-        const sanitizedResponse = this.applyOutputSecurityGuards(responseText);
-        const isFinancial = options.financialNormalizer ?? Boolean(
-          this.config.features?.finance?.enableFrenchAccounting || this.config.features?.finance
+        const output = await this.dispatchProviderAttempt(options, processedMessages, targetModel);
+        accumulatedPromptTokens += output.promptTokens;
+        accumulatedCompletionTokens += output.completionTokens;
+        const { parsedData, sanitizedResponse } = this.parseAndValidateStructuredResult(
+          output.responseText,
+          options
         );
-        const parsedData = validateWithZod(sanitizedResponse, options.schema, {
-          financialNormalizer: isFinancial,
-          jurisdiction: this.config.features?.finance?.jurisdiction
-        });
-        const totalTokens = accumulatedPromptTokens + accumulatedCompletionTokens;
-        const costUSD = this.calculateCost(modelUsed, accumulatedPromptTokens, accumulatedCompletionTokens);
-        this.checkPostExecutionBudget(totalTokens, costUSD);
-        const result = {
+        const result = this.buildStructuredResult({
           data: parsedData,
           rawText: sanitizedResponse,
-          tokens: {
-            prompt: accumulatedPromptTokens,
-            completion: accumulatedCompletionTokens,
-            total: totalTokens
-          },
-          costUSD,
-          modelUsed,
-          failoverOccurred
-        };
-        await this.notifyAuditSink({
-          text: responseText,
-          tokens: result.tokens,
-          costUSD: result.costUSD,
-          modelUsed: result.modelUsed,
-          failoverOccurred: result.failoverOccurred,
-          attempts: attempt + 1
+          promptTokens: accumulatedPromptTokens,
+          completionTokens: accumulatedCompletionTokens,
+          modelUsed: output.modelUsed,
+          failoverOccurred: output.failoverOccurred
         });
+        await this.notifyAuditSinkSafe(sanitizedResponse, result, attempt + 1);
         return result;
       } catch (err) {
         lastError = err;
-        if (attempt < maxRetries) {
-          const delay = (this.config.retryOptions?.initialDelayMs ?? 200) * Math.pow(this.config.retryOptions?.backoffFactor ?? 1.5, attempt);
-          await new Promise((resolve) => setTimeout(resolve, delay));
-        }
+        await this.waitRetryBackoff(attempt, maxRetries);
       }
     }
     throw lastError;