@x12i/ai-gateway 7.9.1

package/dist-cjs/activity-manager.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Activity Manager
+ *
+ * Manages activity tracking for LLM requests.
+ * Wraps the ActivityTracker and provides convenience methods.
+ */
+import { Activix } from '@x12i/activix';
+import type { Logxer } from '@x12i/logxer';
+import type { ActivityIdentity, ChatRequest, AIRequest, FailureType, LLMResponseFailureSubtype, ResponseParsingFailureSubtype } from './types.js';
+type Request = ChatRequest | AIRequest;
+/**
+ * Normalizes and attaches the gateway `identity` envelope on the request (Activix + router correlation).
+ * Call at the API boundary before the router when activity tracking is off, and used internally when it is on.
+ *
+ * **Execution context:** treats `request.identity` as received from upstream. Root fields (`sessionId`,
+ * `instance`, and any keys already set on that object) are not replaced by gateway defaults; the gateway
+ * only fills missing required pieces and adds local context (e.g. graph linkage) where absent.
+ */
+export declare function ensureGatewayRequestIdentity(request: ChatRequest | AIRequest, extras?: Partial<ActivityIdentity>): ActivityIdentity;
+type ActivityMetadata = Record<string, any> & {
+    activityId?: string;
+    recordId?: string;
+    aiRequestId: string;
+    runContext?: ActivityIdentity;
+    status?: string;
+    activityType?: string;
+};
+export interface ActivityManagerConfig {
+    enableActivityTracking: boolean;
+    customTracker?: Activix;
+    logger: Logxer;
+}
+/**
+ * Manages activity tracking lifecycle
+ */
+export declare class ActivityManager {
+    private activix?;
+    private initPromise?;
+    private mainCollectionName?;
+    private skillExecutionsCollectionName;
+    private badRequestsCollectionName?;
+    private logger;
+    constructor(config: ActivityManagerConfig);
+    /**
+     * Gets upstream-provided AI request ID
+     *
+     * @param request - Enhanced LLM request
+     * @returns AI request ID string
+     */
+    generateJobId(request: Request): string;
+    /**
+     * Starts activity tracking for a request
+     *
+     * IMPORTANT: This method ONLY sends REQUEST data (no response).
+     * The same record will be updated later via logSuccess() or logFailure()
+     * with response/timing data.
+     *
+     * KEY CONCEPT: jobId is NOT the unique identifier!
+     * - jobId = entire job (can have 100+ activities sharing the same jobId)
+     * - taskId = task within a job (can have multiple activities)
+     * - Each activity gets its own unique identifier (_id/recordId) from ActivityTracker
+     * - The returned ActivityMetadata contains this unique identifier for later updates
+     *
+     * This ensures:
+     * - On start: Only request data is stored → creates NEW record with unique _id
+     * - On finish: Only response data is added → updates SAME record by _id/recordId
+     * - No duplication: Request data sent once, response data sent once
+     * - Multiple activities per job: Each activity is a separate record, grouped by jobId
+     *
+     * @param request - Enhanced LLM request
+     * @param startTime - Request start timestamp
+     * @returns Activity metadata (contains unique _id/recordId) or undefined if tracking is disabled
+     */
+    startActivity(request: Request, startTime: number): Promise<ActivityMetadata | undefined>;
+    /**
+     * Starts skill execution activity tracking
+     *
+     * Similar to startActivity() but creates a skill-execution activity record instead of gateway-invocation.
+     * Skill executions are tracked separately and stored in the 'skill-executions' collection.
+     *
+     * @param request - Enhanced LLM request (must be a skill execution)
+     * @param instructionMetadata - Optional audit fields when caller tracks instruction catalog info
+     * @param startTime - Request start timestamp
+     * @returns Activity metadata (contains unique _id/recordId) or undefined if tracking is disabled
+     */
+    startSkillExecution(request: Request, instructionMetadata: {
+        key?: string;
+        version?: string;
+        rawContent?: string;
+    } | undefined, startTime: number): Promise<ActivityMetadata | undefined>;
+    /**
+     * Logs successful activity completion
+     *
+     * IMPORTANT: This method ONLY sends RESPONSE/TIMING data (no request data).
+     * It updates the SAME record created by startActivity() using the unique record identifier.
+     *
+     * KEY CONCEPT: jobId is NOT the unique identifier!
+     * - jobId = entire job (can have 100+ activities sharing the same jobId)
+     * - taskId = task within a job (can have multiple activities)
+     * - Each activity has its own unique identifier (_id/recordId) returned by startActivity()
+     *
+     * This ensures:
+     * - On start: Only request data is stored (via startActivity) → creates new record with unique _id
+     * - On finish: Only response data is added (via logSuccess) → updates same record by _id/recordId
+     * - No duplication: Request data sent once, response data sent once
+     * - Same record: Updated by unique identifier (_id/recordId), NOT by jobId
+     *
+     * Structure sent to ActivityTracker:
+     * - response: { content, metadata } (response object)
+     * - endTime, duration (timing completion)
+     * - cost (cost calculation)
+     * - status: 'success' (updated by ActivityTracker)
+     * - NO request data (already stored in startActivity)
+     * - NO config data (already stored in startActivity)
+     *
+     * @param activity - Activity metadata from startActivity() (contains unique _id/recordId for record lookup)
+     * @param details - Success details (cost, response, timing)
+     */
+    logSuccess(activity: ActivityMetadata | undefined, details: {
+        cost?: number;
+        response: any;
+        endTime: number;
+        duration: number;
+    }): Promise<void>;
+    /**
+     * Logs failed activity
+     *
+     * IMPORTANT: This method ONLY sends ERROR/TIMING data (no request/response data).
+     * It updates the SAME record created by startActivity() using the unique record identifier.
+     *
+     * KEY CONCEPT: jobId is NOT the unique identifier!
+     * - jobId = entire job (can have 100+ activities sharing the same jobId)
+     * - taskId = task within a job (can have multiple activities)
+     * - Each activity has its own unique identifier (_id/recordId) returned by startActivity()
+     *
+     * Structure sent to ActivityTracker:
+     * - error (error message)
+     * - endTime, duration (timing completion)
+     * - status: 'failed' (updated by ActivityTracker)
+     * - NO request data (already stored in startActivity)
+     * - NO response data (request failed)
+     *
+     * @param activity - Activity metadata from startActivity() (contains unique _id/recordId for record lookup)
+     * @param error - Error that occurred
+     * @param details - Failure details (timing, error message)
+     */
+    logFailure(activity: ActivityMetadata | undefined, error: Error, details: {
+        endTime: number;
+        duration: number;
+        error: string;
+        failureType?: FailureType;
+        failureSubtype?: LLMResponseFailureSubtype | ResponseParsingFailureSubtype;
+        response?: any;
+    }): Promise<void>;
+    /**
+     * Logs a bad request (error that occurred before startActivity)
+     *
+     * This method creates a new activity record specifically for tracking validation
+     * errors, format extraction failures, and other errors that occur before the
+     * normal activity lifecycle begins.
+     *
+     * Uses native ActivityTracker support for bad requests collection via the
+     * `collectionName` option in `startActivity()` and `logFailure()` methods.
+     * The bad requests collection is configured via `badRequestsCollectionName` in
+     * the ActivityTracker constructor (defaults to 'ai-bad-requests').
+     *
+     * Bad requests are automatically routed to the separate bad requests collection
+     * and can be filtered by `failureType` field:
+     * - 'validation-failure': Request validation errors
+     * - 'format-extraction-failure': Format extraction errors
+     * - 'configuration-failure': Configuration errors
+     *
+     * @param request - The request that failed
+     * @param error - The error that occurred
+     * @param details - Additional error details
+     * @param startTime - When the request started
+     */
+    logBadRequest(request: Request, error: Error, details: {
+        endTime: number;
+        duration: number;
+        error: string;
+        errorType?: string;
+        diagnosticInfo?: Record<string, any>;
+        failureType?: 'validation-failure' | 'format-extraction-failure' | 'configuration-failure';
+    }, startTime: number): Promise<void>;
+    /**
+     * Gets the underlying activity tracker instance
+     *
+     * @returns Activix instance or undefined if not enabled
+     */
+    getTracker(): Activix | undefined;
+    /**
+     * Get status of activity tracker
+     */
+    getStatus(): {
+        activityTracking: {
+            enabled: boolean;
+            tracker?: any;
+        };
+    };
+    /**
+     * Shutdown tracker
+     */
+    shutdown(): Promise<void>;
+}
+export {};

package/dist-cjs/config/activity-tracking-config.cjs

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Centralized activity tracking configuration.
+ * Single source of truth for package-level collection names.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveActivityTrackingConfig = resolveActivityTrackingConfig;
+const ACTIVITY_COLLECTION_NAME = 'ai-activities';
+const BAD_REQUESTS_COLLECTION_NAME = 'bad-requests';
+function resolveActivityTrackingConfig() {
+    // Collection names are intentionally hardcoded at package level.
+    return {
+        mongoUri: '',
+        databaseName: '',
+        collectionName: ACTIVITY_COLLECTION_NAME,
+        badRequestsCollectionName: BAD_REQUESTS_COLLECTION_NAME
+    };
+}

package/dist-cjs/config/activity-tracking-config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Centralized activity tracking configuration.
+ * Single source of truth for package-level collection names.
+ */
+export interface ActivityTrackingConfig {
+    mongoUri: string;
+    databaseName: string;
+    collectionName: string;
+    badRequestsCollectionName: string;
+}
+export declare function resolveActivityTrackingConfig(): ActivityTrackingConfig;

package/dist-cjs/config.defaults.json

@@ -0,0 +1,31 @@
+{
+  "contentRegistry": {
+    "mode": "dev",
+    "localRoot": ".metadata",
+    "github": {
+      "token": null,
+      "repo": null
+    },
+    "s3": {
+      "bucket": null,
+      "region": null
+    },
+    "redis": {
+      "host": null,
+      "port": null
+    },
+    "cache": {
+      "ttl": 3600000
+    }
+  },
+  "logging": {
+    "level": "info",
+    "enabled": true
+  },
+  "templateRendering": {
+    "subPathSearch": {
+      "enabled": false,
+      "roots": ["execution", "input", "inputs"]
+    }
+  }
+}

package/dist-cjs/content-normalizer/content-normalizer.cjs

@@ -0,0 +1,398 @@
+"use strict";
+/**
+ * Content Normalizer
+ *
+ * Extracts and normalizes content from LLM provider responses.
+ * Fixes the "[object Object]" bug by properly handling objects.
+ * Preserves both rawText and parsedContent for downstream consumers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeContent = normalizeContent;
+exports.isEmptyContent = isEmptyContent;
+exports.getResponseDiagnostics = getResponseDiagnostics;
+/**
+ * Extracts content from router response, checking multiple possible locations
+ *
+ * @param response - Router response object
+ * @returns Extracted content value (any type) or null
+ */
+function extractContentValue(response) {
+    // Check multiple possible locations
+    // CRITICAL: Check outputText FIRST (router's standard field) before other fields
+    return response.outputText ?? // Router's standard output field (check first)
+        response.content ??
+        response.rawText ??
+        response.output ??
+        response.choices?.[0]?.message?.content ??
+        response.choices?.[0]?.text ??
+        response.message?.content ??
+        response.text ??
+        response.result ??
+        null;
+}
+/**
+ * Extracts rawText from router response
+ *
+ * @param response - Router response object
+ * @param contentValue - The extracted content value (to avoid re-extraction)
+ * @returns Raw text string or undefined
+ */
+function extractRawText(response, contentValue) {
+    // Try to get rawText from router response (preferred - original from provider)
+    // Check multiple possible locations where router might store rawText
+    const rawText = response.rawText || // Direct rawText field (preferred)
+        response.outputText || // Router's standard output field (if rawText not available)
+        response.raw || // Some providers use 'raw'
+        response.rawContent || // Some providers use 'rawContent'
+        response.originalText || // Some providers use 'originalText'
+        response.originalContent || // Some providers use 'originalContent'
+        response.choices?.[0]?.message?.rawText || // OpenAI-style nested rawText
+        response.choices?.[0]?.rawText || // OpenAI-style direct rawText
+        response.message?.rawText || // Message-level rawText
+        response.output?.rawText; // Output-level rawText
+    if (typeof rawText === 'string' && rawText.trim().length > 0) {
+        return rawText;
+    }
+    // If no rawText found, but content is a string, use it as rawText
+    // This ensures we always have something to work with
+    // If content is already a string, check if it's a JSON string with wrapped prose
+    if (typeof contentValue === 'string' && contentValue.trim().length > 0) {
+        // Check if it's a JSON string that might contain wrapped prose
+        const trimmed = contentValue.trim();
+        if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+            (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                // If it's a wrapped prose object (has _wrapped and text fields), extract the text
+                if (parsed && typeof parsed === 'object' && parsed._wrapped === true && typeof parsed.text === 'string') {
+                    return parsed.text;
+                }
+                // Otherwise, return the original string (it's a valid JSON string)
+                return contentValue;
+            }
+            catch {
+                // Not valid JSON, return as-is
+                return contentValue;
+            }
+        }
+        // Not JSON, return as-is
+        return contentValue;
+    }
+    // If content is an object/array, check for wrapped prose first
+    if (contentValue != null && typeof contentValue === 'object') {
+        // Check if it's a wrapped prose object (has _wrapped and text fields)
+        if (contentValue._wrapped === true && typeof contentValue.text === 'string') {
+            return contentValue.text;
+        }
+        // Otherwise, stringify it to get the JSON string
+        // This handles the case where router doesn't preserve rawText but returns parsed object
+        try {
+            return JSON.stringify(contentValue);
+        }
+        catch {
+            // If stringify fails, return undefined
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Attempts to parse content as JSON
+ * Always returns a structure - forces JSON structure even if parsing fails
+ *
+ * @param value - Value to parse
+ * @param forceStructure - If true, always return an object/array structure (default: true)
+ * @returns Parsed object/array or forced structure
+ */
+function tryParseJSON(value, forceStructure = true) {
+    if (value == null) {
+        // Force structure: return empty object instead of undefined
+        return forceStructure ? {} : undefined;
+    }
+    // If already an object or array, return it
+    if (typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value;
+    }
+    // If it's a string, try to parse it
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        // Try to parse as JSON
+        if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+            (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+            try {
+                return JSON.parse(trimmed);
+            }
+            catch {
+                // Not valid JSON - force structure if requested
+                if (forceStructure) {
+                    // Wrap in object with the text as a value
+                    return trimmed.startsWith('[') ? [] : { value: trimmed, _parseError: true };
+                }
+                return undefined;
+            }
+        }
+        // If forceStructure and it's not JSON-like, wrap it
+        if (forceStructure && trimmed.length > 0) {
+            return { text: trimmed, _wrapped: true };
+        }
+    }
+    // For other types (number, boolean, etc.), wrap in object if forceStructure
+    if (forceStructure && value != null) {
+        return { value, _wrapped: true };
+    }
+    return undefined;
+}
+/**
+ * Determines content type
+ *
+ * @param value - Content value
+ * @param parsedContent - Parsed content (if available)
+ * @returns Content type classification
+ */
+function determineContentType(value, parsedContent) {
+    if (value == null || value === '') {
+        return 'null';
+    }
+    // Use parsedContent if available (more accurate)
+    if (parsedContent != null) {
+        if (Array.isArray(parsedContent)) {
+            return 'array';
+        }
+        if (typeof parsedContent === 'object') {
+            return 'object';
+        }
+    }
+    // Fall back to checking value directly
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (typeof value === 'object') {
+        return 'object';
+    }
+    return 'string';
+}
+/**
+ * Normalizes content from router response
+ *
+ * This function:
+ * 1. Extracts content from multiple possible locations
+ * 2. Preserves rawText if available
+ * 3. Attempts to parse flex-md content to JSON
+ * 4. Properly stringifies objects (fixes "[object Object]" bug)
+ * 5. Determines content type
+ *
+ * @param response - Router response object
+ * @returns Normalized content with metadata
+ */
+function normalizeContent(response) {
+    // Extract content value from response
+    const contentValue = extractContentValue(response);
+    // CRITICAL: Check if router already converted object to "[object Object]" string
+    // This happens when router uses String() on objects before returning
+    if (typeof contentValue === 'string' && contentValue === '[object Object]') {
+        // Router already broke it - try to recover from other fields
+        console.error('[content-normalizer] Router returned "[object Object]" string - attempting recovery', {
+            responseKeys: Object.keys(response),
+            hasOutput: !!response.output,
+            hasRawText: !!response.rawText,
+            hasChoices: !!response.choices
+        });
+        // Try to get the original object from other fields
+        const output = response.output;
+        const choicesContent = response.choices?.[0]?.message?.content;
+        const messageContent = response.message?.content;
+        // Prefer output (parsed object from provider)
+        if (output && typeof output === 'object' && output !== null) {
+            const recovered = JSON.stringify(output);
+            return {
+                content: recovered,
+                rawText: recovered,
+                parsedContent: output,
+                contentType: Array.isArray(output) ? 'array' : 'object'
+            };
+        }
+        // Try choices content (might be object)
+        if (choicesContent && typeof choicesContent === 'object' && choicesContent !== null) {
+            const recovered = JSON.stringify(choicesContent);
+            return {
+                content: recovered,
+                rawText: recovered,
+                parsedContent: choicesContent,
+                contentType: Array.isArray(choicesContent) ? 'array' : 'object'
+            };
+        }
+        // Try message content (might be object)
+        if (messageContent && typeof messageContent === 'object' && messageContent !== null) {
+            const recovered = JSON.stringify(messageContent);
+            return {
+                content: recovered,
+                rawText: recovered,
+                parsedContent: messageContent,
+                contentType: Array.isArray(messageContent) ? 'array' : 'object'
+            };
+        }
+        // If we can't recover, log error and return empty
+        console.error('[content-normalizer] Cannot recover from "[object Object]" - no valid object found in response');
+        return {
+            content: '',
+            rawText: undefined,
+            parsedContent: undefined,
+            contentType: 'null'
+        };
+    }
+    // Extract rawText (original text from provider)
+    // Pass contentValue to avoid re-extraction and handle object case
+    const rawText = extractRawText(response, contentValue);
+    // Always parse flex-md to JSON
+    let parsedContent;
+    let contentType;
+    // Try to parse flex-md content to JSON
+    parsedContent = tryParseJSON(contentValue, true);
+    contentType = determineContentType(contentValue, parsedContent);
+    // Ensure parsedContent matches contentType - force structure consistency
+    // JSON is always JSON (object/array), text is always text (string), etc.
+    let finalParsedContent = parsedContent;
+    if (contentType === 'object') {
+        // Force object structure - always return an object
+        if (!finalParsedContent || typeof finalParsedContent !== 'object' || Array.isArray(finalParsedContent)) {
+            if (typeof contentValue === 'string' && contentValue.trim().length > 0) {
+                // Wrap text in object
+                finalParsedContent = { text: contentValue, _wrapped: true };
+            }
+            else if (Array.isArray(contentValue)) {
+                // Wrap array in object
+                finalParsedContent = { array: contentValue, _wrapped: true };
+            }
+            else {
+                // Empty object
+                finalParsedContent = {};
+            }
+        }
+    }
+    else if (contentType === 'array') {
+        // Force array structure - always return an array
+        if (!Array.isArray(finalParsedContent)) {
+            if (finalParsedContent && typeof finalParsedContent === 'object') {
+                // Wrap object in array
+                finalParsedContent = [finalParsedContent];
+            }
+            else if (typeof contentValue === 'string' && contentValue.trim().length > 0) {
+                // Wrap text in array
+                finalParsedContent = [contentValue];
+            }
+            else {
+                // Empty array
+                finalParsedContent = [];
+            }
+        }
+    }
+    else if (contentType === 'string') {
+        // For string type, parsedContent can be undefined (it's just text)
+        // But if we have an object, we should keep it for structure preservation
+        // Don't force anything - string content doesn't need parsedContent
+        finalParsedContent = parsedContent; // Keep as-is (may be undefined, which is fine for strings)
+    }
+    else {
+        // null type - no parsedContent
+        finalParsedContent = undefined;
+    }
+    // Normalize content to string (for backward compatibility)
+    // CRITICAL: This must NEVER return "[object Object]" - always stringify objects properly
+    let normalizedString;
+    if (contentValue == null || contentValue === '') {
+        normalizedString = '';
+    }
+    else if (typeof contentValue === 'string') {
+        normalizedString = contentValue;
+    }
+    else if (typeof contentValue === 'object') {
+        // Fix "[object Object]" bug: properly stringify objects
+        // This is the critical fix - never use String() on objects
+        try {
+            normalizedString = JSON.stringify(contentValue);
+        }
+        catch (error) {
+            // If JSON.stringify fails (circular reference, etc.), try to recover
+            // Use rawText if available, otherwise fallback (but log error)
+            if (rawText && typeof rawText === 'string') {
+                normalizedString = rawText;
+            }
+            else {
+                // Last resort: use String() but this should never happen
+                normalizedString = String(contentValue);
+                // This will be "[object Object]" but we've exhausted all options
+                console.error('[content-normalizer] Failed to stringify object and no rawText available', {
+                    error,
+                    contentValueType: typeof contentValue,
+                    isArray: Array.isArray(contentValue)
+                });
+            }
+        }
+    }
+    else {
+        normalizedString = String(contentValue);
+    }
+    // Final safety check: if normalizedString is "[object Object]", try to recover
+    if (normalizedString === '[object Object]') {
+        // This should never happen, but if it does, try to recover
+        if (rawText && typeof rawText === 'string' && rawText !== '[object Object]') {
+            normalizedString = rawText;
+        }
+        else if (parsedContent) {
+            try {
+                normalizedString = JSON.stringify(parsedContent);
+            }
+            catch {
+                // If this also fails, we're stuck with "[object Object]"
+                console.error('[content-normalizer] Cannot recover from "[object Object]" - all recovery attempts failed');
+            }
+        }
+    }
+    // CRITICAL: Ensure rawText is always set
+    // Priority: extracted rawText > normalizedString > contentValue (if string) > empty string
+    let finalRawText = rawText;
+    if (!finalRawText || typeof finalRawText !== 'string' || finalRawText.trim().length === 0) {
+        // Fallback to normalizedString (which is always a string)
+        finalRawText = normalizedString;
+    }
+    // If we still don't have rawText and contentValue is a string, use it
+    if ((!finalRawText || finalRawText.trim().length === 0) && typeof contentValue === 'string' && contentValue.trim().length > 0) {
+        finalRawText = contentValue;
+    }
+    return {
+        content: normalizedString,
+        rawText: finalRawText, // Always set (never undefined)
+        parsedContent: finalParsedContent, // Use final parsed content with forced structure
+        contentType
+    };
+}
+/**
+ * Checks if content is empty
+ *
+ * @param normalized - Normalized content result
+ * @returns True if content is empty
+ */
+function isEmptyContent(normalized) {
+    return !normalized.content || normalized.content.trim().length === 0;
+}
+/**
+ * Gets diagnostic information about response structure
+ * Useful for debugging when content extraction fails
+ *
+ * @param response - Router response object
+ * @returns Diagnostic information
+ */
+function getResponseDiagnostics(response) {
+    return {
+        responseKeys: Object.keys(response),
+        hasMessage: !!(response?.message),
+        hasChoices: !!(response?.choices),
+        hasOutput: !!(response?.output),
+        hasRawText: !!(response?.rawText),
+        originalContent: response?.content,
+        originalContentType: typeof response?.content
+    };
+}