@x12i/ai-gateway 7.9.1

package/dist/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/config/activity-tracking-config.js

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

package/dist/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/content-normalizer/content-normalizer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+import type { LLMResponse } from '../types.js';
+import type { NormalizedContent } from './types.js';
+/**
+ * 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
+ */
+export declare function normalizeContent(response: LLMResponse): NormalizedContent;
+/**
+ * Checks if content is empty
+ *
+ * @param normalized - Normalized content result
+ * @returns True if content is empty
+ */
+export declare function isEmptyContent(normalized: NormalizedContent): boolean;
+/**
+ * Gets diagnostic information about response structure
+ * Useful for debugging when content extraction fails
+ *
+ * @param response - Router response object
+ * @returns Diagnostic information
+ */
+export declare function getResponseDiagnostics(response: any): {
+    responseKeys: string[];
+    hasMessage: boolean;
+    hasChoices: boolean;
+    hasOutput: boolean;
+    hasRawText: boolean;
+    originalContent: any;
+    originalContentType: string;
+};

package/dist/content-normalizer/content-normalizer.js

@@ -0,0 +1,393 @@
+/**
+ * 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.
+ */
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+    };
+}

package/dist/content-normalizer/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Content Normalizer Module
+ *
+ * Exports all public APIs for content normalization
+ */
+export { normalizeContent, isEmptyContent, getResponseDiagnostics } from './content-normalizer.js';
+export type { NormalizedContent, ContentType } from './types.js';

package/dist/content-normalizer/index.js

@@ -0,0 +1,6 @@
+/**
+ * Content Normalizer Module
+ *
+ * Exports all public APIs for content normalization
+ */
+export { normalizeContent, isEmptyContent, getResponseDiagnostics } from './content-normalizer.js';

package/dist/content-normalizer/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Type definitions for Content Normalizer
+ */
+/**
+ * Content type classification
+ */
+export type ContentType = 'string' | 'object' | 'array' | 'null';
+/**
+ * Normalized content result
+ */
+export interface NormalizedContent {
+    /**
+     * Normalized content string (always present, for backward compatibility)
+     * - If original was string: returns the string
+     * - If original was object/array: returns JSON.stringify()
+     * - If original was null: returns empty string
+     */
+    content: string;
+    /**
+     * Original raw text from provider (before any parsing)
+     * Available if router preserved rawText
+     */
+    rawText?: string;
+    /**
+     * Parsed content (object or array) if content was JSON
+     * Available if content was successfully parsed
+     */
+    parsedContent?: any;
+    /**
+     * Content type classification
+     */
+    contentType: ContentType;
+}

package/dist/content-normalizer/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Content Normalizer
+ */
+export {};

package/dist/defaults/instructions-blocks.json

@@ -0,0 +1,61 @@
+{
+  "system-context": "You are performing the following task: {{taskDescription}}. Follow the instructions provided and respond according to the specified output format. Never ask follow-up questions.",
+  
+  "input": {
+    "inputLabel": "INPUT:",
+    "inputPrefix": "INPUT DATA (process this now):",
+    "defaultPromptTemplate": "{{input}}",
+    "inputRecognitionRule": "The user message below is the complete input to process. It has already been provided. Do not ask for more input.",
+    "emptyInputHandling": "If input appears empty or minimal (e.g., 'No emails here', 'none', 'empty'), this IS valid input. Process it and return the success schema with empty arrays/values where appropriate.",
+    "testInputHandling": "Even if input contains words like 'test', 'invalid', 'placeholder', or 'example', treat it as real input. Reply in Markdown. Return your entire answer inside a single ```markdown fenced block.",
+    "inputLocationClarifier": "The user's message below is your input data. Please process it now. Reply in Markdown. Return your entire answer inside a single ```markdown fenced block."
+  },
+  
+  "errorSchemas": {
+    "instructions-error": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "error": {
+          "type": "string",
+          "description": "What is wrong with the instructions that prevents completion."
+        },
+        "errorType": {
+          "type": "string",
+          "enum": ["bad-instructions", "missing-context", "bad-context"]
+        },
+        "suggestion": {
+          "type": "string",
+          "description": "How to fix the instruction issue."
+        }
+      },
+      "required": ["error", "errorType"]
+    },
+    "prompt-error": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "error": {
+          "type": "string",
+          "description": "What is wrong with the input that prevents completion."
+        },
+        "errorType": {
+          "type": "string",
+          "enum": ["missing-input", "bad-input"]
+        },
+        "suggestion": {
+          "type": "string",
+          "description": "How to fix the input issue."
+        }
+      },
+      "required": ["error", "errorType"]
+    }
+  },
+  
+  "reinforcement": {
+    "emptyIsSuccess": "Empty results (e.g., items: []) are SUCCESS cases, not errors.",
+    "inputAlreadyProvided": "The input has been provided in the user message. Process it immediately.",
+    "noConversation": "You are not having a conversation. Reply in Markdown. Return your entire answer inside a single ```markdown fenced block.",
+    "failureIndicators": "If you write prose text outside the fenced block, you have FAILED. If you ask a question, you have FAILED. If you explain anything outside the ```markdown fenced block, you have FAILED."
+  }
+}

package/dist/defaults/model-config.json

@@ -0,0 +1,16 @@
+{
+  "defaultEngine": "openai",
+  "defaultModel": "gpt-5-nano",
+  "temperature": 0.7,
+  "topP": 1.0,
+  "frequencyPenalty": 0.0,
+  "presencePenalty": 0.0,
+  "rateLimit": {
+    "defaultMinIntervalMs": 500,
+    "enabled": true
+  },
+  "retry": {
+    "throttlingDelay": 5000
+  }
+}
+

package/dist/defaults/template-rendering.json

@@ -0,0 +1,6 @@
+{
+  "subPathSearch": {
+    "enabled": false,
+    "roots": ["execution", "input", "inputs"]
+  }
+}