@x12i/ai-gateway 9.0.9 → 9.1.1

package/dist-cjs/types.d.ts

@@ -22,7 +22,22 @@ export interface DiagnosticsOptions {
      * Implementations must size-cap any raw payload included.
      */
     includeRawProviderPayload?: boolean;
+    /**
+     * When false, Activix activity completion omits `response.content.fullResponse` (large provider blob).
+     * When true or omitted, the full payload is stored (subject to `activityFullResponseMaxChars`).
+     */
+    includeFullProviderResponseInActivity?: boolean;
+    /**
+     * Max serialized length for `fullResponse` on activity records when included (JSON string length).
+     * Default applied in gateway when omitted.
+     */
+    activityFullResponseMaxChars?: number;
 }
+/**
+ * Classifies the gateway invocation for tracing and Activix (`runContext`).
+ * Mandatory on {@link AIInvokeRequest} (`AIGateway.invoke`).
+ */
+export type GatewayActionType = 'skill' | 'preSkill' | 'postSkill';
 export type GatewayTraceRequestIds = {
     /** Stable alias of gateway aiRequestId (always set when trace enabled). */
     gatewayAiRequestId: string;
@@ -111,6 +126,14 @@ export type ActivityIdentity = {
     coreSkillId?: string;
     masterSkillId?: string;
     masterSkillActivityId?: string;
+    /**
+     * From {@link AIInvokeRequest.actionType} when present (gateway.invoke); copied into runContext for Activix.
+     */
+    actionType?: GatewayActionType;
+    /**
+     * From {@link AIInvokeRequest.actionRef} when present; copied into runContext for Activix.
+     */
+    actionRef?: string;
 };
 /** Re-export parser template options for gateway consumers (MUST/optional protocol, subPathSearch, etc.). */
 export type { TemplateRenderOptions } from '@x12i/rendrix';
@@ -566,14 +589,6 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * Added as system message between instructions and prompt
      */
     context?: string;
-    /**
-     * Task configuration (optional) - Control template behavior and conditional rendering
-     * @deprecated taskConfig is no longer used by Rendrix 3.0.0+
-     * Kept for backward compatibility only - will be ignored
-     */
-    taskConfig?: {
-        includeThoughts?: boolean;
-    };
     /**
      * Working memory (optional) - Affects all template parsing
      * Passed to Rendrix (v4+) for template variable substitution.
@@ -587,16 +602,6 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * the full list or only set `enabled` and inherit `roots` from the gateway default merge.
      */
     templateRenderOptions?: TemplateRenderOptions;
-    /**
-     * Template tokens (optional) - Tier 1 (highest priority) token values
-     * These tokens are passed directly as arguments and override all other memory sources
-     * Common tokens: taskDescription, input (from workingMemory.input), role
-     * Example: { taskDescription: "Extract emails", input: "user@example.com", role: "user" }
-     * Note: The `input` field has been removed. Use workingMemory.input instead.
-     */
-    templateTokens?: {
-        [key: string]: string | number | boolean | object | object[];
-    };
     /**
      * Messages array - Optional, can be used instead of instructions/prompt
      * If provided, will be appended as-is after built messages; instructions template text is still parsed for the system message when present
@@ -643,28 +648,6 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * Can be a single type (string) or multiple types (array)
      */
     inferenceType?: string | string[];
-    /**
-     * Enable output schema validation (optional)
-     * When true, validates parsed output against schema from instruction metadata or outputs library
-     * @default false
-     */
-    validateOutputSchema?: boolean;
-    /**
-     * Enable strict validation mode (optional)
-     * When true, validation errors will throw exceptions instead of warnings
-     * @default false
-     */
-    strictValidation?: boolean;
-    /**
-     * Response transformation hooks (optional)
-     * Allows transforming responses at different stages of processing
-     */
-    transformations?: ResponseTransformationConfig;
-    /**
-     * Parse options for outputs library (optional)
-     * Used when inferenceType is provided for parsing inference outputs
-     */
-    parseOptions?: Record<string, unknown>;
     /**
      * Optional diagnostics controls. When omitted or mode != 'trace', the gateway must not
      * attach heavy diagnostic objects or raw provider payloads.
@@ -682,7 +665,7 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
  * Minimum: instructions + prompt (prompt is required for user message)
  *
  * Note: objectTypes is NOT supported in ChatRequest.
- * Use AIRequest with invoke() method for structured output requests.
+ * Use {@link AIInvokeRequest} with invoke() for structured output requests.
  */
 export interface ChatRequest extends BaseLLMRequest {
     /**
@@ -714,18 +697,19 @@ export interface StructuredTextSpec {
     formatHint?: string;
 }
 /**
- * AI request for structured output requests
- * Used exclusively with invoke() method for requests requiring structured output
+ * Payload for {@link AIGateway.invoke}: structured / skill flows with mandatory action classification.
  *
- * Mandatory:
- * - aiRequestId: Required for activity tracking
- * - agentId: Required to identify the agent
- * - instructions: Required (template text)
- * - primaryObjectType OR flexMdFormat: Required for structured output
- *   * primaryObjectType: Standard/custom object type (requires outputs library)
- *   * flexMdFormat: Direct flex-md format specification (no outputs library needed)
+ * Recorded on {@link ActivityIdentity} (`runContext`) and activity roots for Activix.
  */
-export interface AIRequest extends BaseLLMRequest {
+export interface AIInvokeRequest extends BaseLLMRequest {
+    /**
+     * Invocation kind: main skill vs pre/post hooks around skill execution.
+     */
+    actionType: GatewayActionType;
+    /**
+     * Stable reference for the action (e.g. `skills/my-skill`).
+     */
+    actionRef: string;
     /**
      * Encrypted reasoning items for conversation continuity
      * Only include reasoning.encrypted items from previous responses
@@ -739,10 +723,6 @@ export interface AIRequest extends BaseLLMRequest {
         data?: string;
         summary?: any[];
     }>;
-    /**
-     * Skill execution tracking fields
-     * Used when executing skills (instruction keys starting with 'skills/')
-     */
     /**
      * Master skill activity ID - The parent skill activity's ID (when a skill calls another skill)
      * When a skill executes and calls another skill, the parent skill's activityId becomes
@@ -761,6 +741,10 @@ export interface AIRequest extends BaseLLMRequest {
      */
     masterSkillId?: string;
 }
+/**
+ * @deprecated Prefer {@link AIInvokeRequest}; alias kept for existing imports.
+ */
+export type AIRequest = AIInvokeRequest;
 /**
  * Enhanced response with comprehensive metadata and generic type support
  *
@@ -892,7 +876,8 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          */
         model?: string;
         /**
-         * Provider used (e.g., 'openai', 'anthropic')
+         * Provider used (e.g., 'openai', 'anthropic').
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         provider?: string;
         /**
@@ -900,23 +885,30 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          */
         cost?: number;
         /**
-         * Cost in USD (preferred, stable key for trace mode).
+         * Cost in USD (preferred stable key when the router exposes it).
          * When both are present, costUsd should mirror cost.
          */
         costUsd?: number;
         /**
          * Final effective max token cap applied (after merges/normalization), if known.
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         maxTokensRequested?: number;
         /**
          * Model that actually served the response (after routing/fallback), if known.
          * This is distinct from requested model.
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         modelUsed?: string;
         /**
          * Optional region identifier when applicable (provider-specific).
          */
         region?: string;
+        /**
+         * Sanitized merged generation profile (allowlisted fields only; no secrets).
+         * Reflects gateway merge order: modelConfig / request.config / defaults.
+         */
+        effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
         /**
          * Stable request/correlation identifiers across gateway/router/provider layers.
          * Only populated when diagnostics trace mode is enabled.
@@ -1241,38 +1233,4 @@ export interface ValidationRule {
      */
     message?: string;
 }
-/**
- * Response transformation hooks configuration
- * Allows transforming responses at different stages of processing
- */
-export interface ResponseTransformationConfig {
-    /**
-     * Transform raw text before parsing
-     * @param rawText - Raw text from LLM response
-     * @param metadata - Request metadata (jobId, agentId, etc.)
-     * @returns Transformed raw text
-     */
-    preParse?: (rawText: string, metadata: any) => string;
-    /**
-     * Transform parsed content after parsing
-     * @param parsed - Parsed content (object/array)
-     * @param metadata - Request metadata
-     * @returns Transformed parsed content
-     */
-    postParse?: (parsed: any, metadata: any) => any;
-    /**
-     * Transform parsed content before validation
-     * @param parsed - Parsed content
-     * @param schema - JSON schema (if available)
-     * @returns Transformed parsed content
-     */
-    preValidate?: (parsed: any, schema: any) => any;
-    /**
-     * Transform validated content after validation
-     * @param validated - Validated content
-     * @param metadata - Request metadata
-     * @returns Transformed validated content
-     */
-    postValidate?: (validated: any, metadata: any) => any;
-}
 export type { LLMRequest, LLMResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.0.9",
+  "version": "9.1.1",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -65,7 +65,7 @@
     "@aws-sdk/s3-request-presigner": "^3.953.0",
     "@x12i/env": "^4.0.1",
     "@x12i/logxer": "^4.3.5",
-    "@x12i/activix": "^6.7.0",
+    "@x12i/activix": "^7.1.0",
     "@x12i/flex-md": "^4.8.0"
   },
   "devDependencies": {