@x12i/ai-gateway 7.9.1

package/dist/activity-manager.js

@@ -0,0 +1,1051 @@
+/**
+ * Activity Manager
+ *
+ * Manages activity tracking for LLM requests.
+ * Wraps the ActivityTracker and provides convenience methods.
+ */
+import { Activix, activixActivityIo, activixOuterTier } from '@x12i/activix';
+import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
+function readAiRequestIdFromRequest(request) {
+    const aiRequestId = request.aiRequestId;
+    if (typeof aiRequestId === 'string' && aiRequestId.trim().length > 0) {
+        return aiRequestId.trim();
+    }
+    throw new Error('aiRequestId is required and must be provided by upstream');
+}
+function trimIdentityString(v) {
+    return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
+}
+function isMeaningfulIdentityValue(v) {
+    if (v === undefined || v === null)
+        return false;
+    if (typeof v === 'string')
+        return v.trim().length > 0;
+    return true;
+}
+function incomingIdentityHasKey(incoming, key) {
+    if (!incoming || !(key in incoming))
+        return false;
+    return isMeaningfulIdentityValue(incoming[key]);
+}
+/** Keys the gateway may supply only when absent on upstream `identity` (never overwrites roots). */
+const ENRICHABLE_IDENTITY_KEYS = [
+    'graphId',
+    'nodeId',
+    'masterSkillId',
+    'masterSkillActivityId',
+    'coreSkillId'
+];
+function pickGatewayEnrichmentFields(enrichment) {
+    const out = {};
+    for (const key of ENRICHABLE_IDENTITY_KEYS) {
+        const v = enrichment[key];
+        if (isMeaningfulIdentityValue(v)) {
+            out[key] = v;
+        }
+    }
+    return out;
+}
+/**
+ * Adds gateway-derived fields only when upstream `identity` did not already set them.
+ * Execution context must flow from upstream: inner layers extend, they do not replace outer `sessionId`,
+ * `instance`, graph linkage, or other fields already present on the incoming envelope.
+ */
+function mergeActivixEnrichment(incoming, enrichment) {
+    const filtered = pickGatewayEnrichmentFields(enrichment);
+    const out = {};
+    for (const key of ENRICHABLE_IDENTITY_KEYS) {
+        if (incomingIdentityHasKey(incoming, key))
+            continue;
+        const v = filtered[key];
+        if (!isMeaningfulIdentityValue(v))
+            continue;
+        out[key] = v;
+    }
+    return out;
+}
+/**
+ * Graph/skill linkage fields merged into identity before Activix persistence (gateway enrichment).
+ */
+function graphIdentityExtrasFromRequest(request) {
+    const aiRequest = request;
+    const graphId = aiRequest.masterSkillId || request.graphId;
+    const nodeId = aiRequest.skillId || aiRequest.coreSkillId || request.nodeId;
+    return {
+        ...(graphId && { graphId }),
+        ...(nodeId && { nodeId }),
+        ...(aiRequest.masterSkillId && { masterSkillId: aiRequest.masterSkillId }),
+        ...(aiRequest.masterSkillActivityId && { masterSkillActivityId: aiRequest.masterSkillActivityId })
+    };
+}
+/**
+ * Builds `instance` with required `instanceId` / `type` and preserves extra keys from upstream `identity.instance`.
+ */
+function buildInstanceEnvelope(request) {
+    const raw = request.identity?.instance;
+    const incoming = raw != null && typeof raw === 'object' && !Array.isArray(raw) ? raw : undefined;
+    const incomingId = incoming && typeof incoming.instanceId === 'string' && incoming.instanceId.trim().length > 0
+        ? incoming.instanceId.trim()
+        : undefined;
+    const incomingType = incoming && typeof incoming.type === 'string' && incoming.type.trim().length > 0
+        ? incoming.type.trim()
+        : undefined;
+    const rest = incoming ? { ...incoming } : {};
+    delete rest.instanceId;
+    delete rest.type;
+    return {
+        ...rest,
+        instanceId: incomingId || request.agentId,
+        type: incomingType || request.agentType || 'unknown'
+    };
+}
+function resolveSessionIdForRequest(request, incomingIdentity, aiRequestId) {
+    const fromIdentity = trimIdentityString(incomingIdentity?.sessionId);
+    const topLevel = trimIdentityString(request.sessionId);
+    const jobId = trimIdentityString(request.jobId);
+    if (fromIdentity !== undefined && topLevel !== undefined && fromIdentity !== topLevel) {
+        throw new Error(`identity.sessionId (${fromIdentity}) and top-level sessionId (${topLevel}) must agree`);
+    }
+    return fromIdentity ?? topLevel ?? jobId ?? aiRequestId;
+}
+function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
+    const incomingIdentity = request.identity;
+    const sessionId = resolveSessionIdForRequest(request, incomingIdentity, aiRequestId);
+    const legacyJobId = trimIdentityString(incomingIdentity?.jobId) ?? trimIdentityString(request.jobId);
+    const combinedEnrichment = pickGatewayEnrichmentFields({
+        ...graphIdentityExtrasFromRequest(request),
+        ...(extras || {})
+    });
+    const safeEnrichment = mergeActivixEnrichment(incomingIdentity, combinedEnrichment);
+    // Request fields are defaults for this hop; incoming `identity` from upstream wins on conflict.
+    // Gateway enrichment (graph/skill, etc.) fills only keys the outer envelope did not already set.
+    const merged = {
+        jobTypeId: request.jobTypeId,
+        agentId: request.agentId,
+        taskId: request.taskId,
+        taskTypeId: request.taskTypeId,
+        ...safeEnrichment,
+        ...(incomingIdentity || {}),
+        sessionId,
+        instance: buildInstanceEnvelope(request),
+        aiRequestId
+    };
+    merged.sessionId = sessionId;
+    merged.instance = buildInstanceEnvelope(request);
+    merged.aiRequestId = aiRequestId;
+    if (legacyJobId !== undefined) {
+        merged.jobId = legacyJobId;
+    }
+    return merged;
+}
+/**
+ * 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 function ensureGatewayRequestIdentity(request, extras) {
+    const aiRequestId = readAiRequestIdFromRequest(request);
+    const identity = mergeGatewayActivityIdentity(request, aiRequestId, {
+        ...graphIdentityExtrasFromRequest(request),
+        ...(extras || {})
+    });
+    request.identity = identity;
+    return identity;
+}
+/** Initial `{ outer }` fragment for `startRecord` (Activix merges completion into the same `outer`). */
+function buildActivixStartIo(aiRequestId, activityType, requestData) {
+    const input = requestData !== undefined &&
+        typeof requestData === 'object' &&
+        !Array.isArray(requestData) &&
+        Object.keys(requestData).length > 0
+        ? { activityType, request: requestData }
+        : { activityType };
+    return activixActivityIo(activixOuterTier(input, null, { aiRequestId }));
+}
+/**
+ * Manages activity tracking lifecycle
+ */
+export class ActivityManager {
+    activix;
+    initPromise;
+    mainCollectionName;
+    skillExecutionsCollectionName = 'skill-executions';
+    badRequestsCollectionName; // Bad requests collection name
+    logger;
+    constructor(config) {
+        this.logger = config.logger;
+        if (config.enableActivityTracking) {
+            const { collectionName, badRequestsCollectionName } = resolveActivityTrackingConfig();
+            this.mainCollectionName = collectionName;
+            this.badRequestsCollectionName = badRequestsCollectionName;
+            try {
+                // Map gateway statuses to Activix statusValues so lifecycle semantics stay compatible.
+                const statusValues = {
+                    started: 'started',
+                    inProgress: 'in_progress',
+                    completed: 'success',
+                    failed: 'failed',
+                    timeout: 'timeout'
+                };
+                this.activix = config.customTracker ?? new Activix({
+                    // Keep mode explicit for operational clarity (matches integration checklist expectations).
+                    storageMode: 'automatic',
+                    collections: [
+                        {
+                            name: collectionName,
+                            statusValues,
+                            primaryKey: 'activityId',
+                            primaryKeyPrefix: 'act-'
+                        },
+                        {
+                            name: this.skillExecutionsCollectionName,
+                            statusValues,
+                            primaryKey: 'activityId',
+                            primaryKeyPrefix: 'act-'
+                        },
+                        {
+                            name: badRequestsCollectionName,
+                            statusValues,
+                            primaryKey: 'activityId',
+                            primaryKeyPrefix: 'act-'
+                        }
+                    ],
+                    defaultCollection: collectionName,
+                    diagnostics: {
+                        owner: '@x12i/ai-gateway',
+                        component: 'activity-manager',
+                        instanceLabel: 'default',
+                        workerId: String(process.pid)
+                    },
+                    logger: this.logger,
+                    errorHandling: {
+                        onConnectionError: 'silent',
+                        onPersistError: 'silent',
+                        retry: {
+                            maxRetries: 0,
+                            retryDelay: 0,
+                            exponentialBackoff: false
+                        }
+                    }
+                });
+                this.initPromise = this.activix.init().catch((error) => {
+                    // MongoDB config not available - log warning but don't throw.
+                    // This allows tests and development to work without MongoDB.
+                    this.logger.warn('Activity tracking enabled but MongoDB configuration not available. Activity records will not be persisted.', {
+                        error: error instanceof Error ? error.message : String(error),
+                        hint: 'Set MONGO_URI and MONGO_LOGS_DB (or MONGO_DB) environment variables to enable activity tracking persistence'
+                    });
+                    this.activix = undefined;
+                });
+                this.logger.debug('Activity tracking enabled with Activix', {
+                    collection: collectionName,
+                    badRequestsCollection: badRequestsCollectionName,
+                    skillExecutionsCollection: this.skillExecutionsCollectionName
+                });
+            }
+            catch (error) {
+                this.logger.warn('Failed to initialize activity tracking (Activix). Activity records will not be persisted.', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+                this.activix = undefined;
+            }
+        }
+    }
+    /**
+     * Gets upstream-provided AI request ID
+     *
+     * @param request - Enhanced LLM request
+     * @returns AI request ID string
+     */
+    generateJobId(request) {
+        return readAiRequestIdFromRequest(request);
+    }
+    /**
+     * 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
+     */
+    async startActivity(request, startTime) {
+        const identity = ensureGatewayRequestIdentity(request);
+        const aiRequestId = identity.aiRequestId;
+        // Capture ONLY request data - NO response data at this stage
+        // Note: v2.3.2+ excludes flat request/config fields from root level
+        // Fields like messages, instructions, prompt, input, context, workingMemory,
+        // model, provider, temperature, maxTokens should only be in request/config objects
+        //
+        // `runContext` mirrors `request.identity` from ensureGatewayRequestIdentity (sessionId, instance, graph/skill linkage,
+        // gateway context fields, and pass-through of upstream custom keys) for Activix v5 persistence.
+        if (!this.activix) {
+            return undefined;
+        }
+        if (this.initPromise) {
+            await this.initPromise;
+        }
+        if (!this.activix) {
+            return undefined;
+        }
+        const activityMetadata = {
+            aiRequestId,
+            jobTypeId: request.jobTypeId,
+            agentId: request.agentId,
+            taskId: request.taskId,
+            taskTypeId: request.taskTypeId,
+            startTime,
+            status: 'started',
+            activityType: 'gateway-invocation',
+            // Activix v5+: correlation BSON field is `runContext` (same object as `request.identity`)
+            runContext: identity
+            // Removed root-level fields per v2.3.2:
+            // - instructions, prompt, input, context, messages, workingMemory → only in request object
+            // - provider, model, temperature, maxTokens → only in config object
+            // - NO response, endTime, duration (these are added via logSuccess)
+        };
+        // Config snapshot
+        // CRITICAL: This captures the exact config sent to the router (finalRouterConfig)
+        // This ensures activity records show the actual config that was sent, including that response_format was removed
+        if (request.config !== undefined) {
+            // Verify response_format is not present (for debugging)
+            const hasResponseFormat = 'responseFormat' in request.config || 'response_format' in request.config;
+            if (hasResponseFormat) {
+                this.logger.warn('Activity tracking received config with response_format - this should not happen', {
+                    aiRequestId,
+                    hasResponseFormat: 'responseFormat' in request.config,
+                    hasResponse_format: 'response_format' in request.config,
+                    configKeys: Object.keys(request.config)
+                });
+            }
+            activityMetadata.config = {
+                model: request.config.model,
+                provider: request.config.provider || null, // Ensure provider is captured (may be null if not set)
+                temperature: request.config.temperature,
+                maxTokens: request.config.maxTokens,
+                rawConfig: request.config // ✅ Captures finalRouterConfig (exact config sent to router)
+            };
+            this.logger.debug('Activity tracking config captured', {
+                aiRequestId,
+                model: request.config.model,
+                provider: request.config.provider,
+                hasResponseFormat: hasResponseFormat,
+                rawConfigKeys: Object.keys(request.config).slice(0, 10)
+            });
+        }
+        // Build request object snapshots (raw = incoming; parsed = constructed messages/meta)
+        const rawSnapshot = request._rawRequest ?? {
+            instructions: request.instructions,
+            context: request.context,
+            prompt: request.prompt,
+            messages: request.messages,
+            workingMemory: request.workingMemory,
+            config: request.config
+        };
+        const parsedSnapshot = request._parsedRequest ?? {};
+        const requestData = {};
+        // raw snapshot (only allowed fields)
+        if (rawSnapshot.instructions !== undefined ||
+            rawSnapshot.context !== undefined ||
+            rawSnapshot.prompt !== undefined) {
+            requestData.raw = {
+                instructions: rawSnapshot.instructions,
+                context: rawSnapshot.context,
+                prompt: rawSnapshot.prompt
+            };
+        }
+        // parsed snapshot (only allowed fields)
+        // Ensure parsed is populated if parsedSnapshot has data, even if individual fields are undefined
+        if (parsedSnapshot.instructions !== undefined ||
+            parsedSnapshot.context !== undefined ||
+            parsedSnapshot.prompt !== undefined) {
+            requestData.parsed = {
+                instructions: parsedSnapshot.instructions,
+                context: parsedSnapshot.context,
+                prompt: parsedSnapshot.prompt
+            };
+        }
+        else if (Object.keys(parsedSnapshot).length > 0) {
+            // If parsedSnapshot exists but doesn't have instructions/context/prompt,
+            // still create parsed with what's available (mirror of raw request after processing)
+            requestData.parsed = {
+                instructions: rawSnapshot.instructions,
+                context: rawSnapshot.context,
+                prompt: rawSnapshot.prompt
+            };
+        }
+        // DEBUG: Include format guidance (prefix + schema) for objectTypes debugging
+        // This helps verify what was fetched and appended to instructions
+        if (parsedSnapshot._formatGuidance) {
+            requestData.formatGuidance = {
+                prefixKey: parsedSnapshot._formatGuidance.prefixKey,
+                prefixContent: parsedSnapshot._formatGuidance.prefixContent,
+                schemaGuidance: parsedSnapshot._formatGuidance.schemaGuidance,
+                hasMultipleObjectTypes: parsedSnapshot._formatGuidance.hasMultipleObjectTypes
+            };
+        }
+        // Include output format information from validation
+        if (parsedSnapshot._outputFormat) {
+            activityMetadata.outputFormat = {
+                spec: parsedSnapshot._outputFormat.spec,
+                level: parsedSnapshot._outputFormat.level,
+                validated: parsedSnapshot._outputFormat.validated
+            };
+        }
+        // Always use flex-md parsing - no object type processing needed
+        // other allowed fields on request
+        // Ensure instructions is included if not already in raw/parsed
+        if (requestData.raw?.instructions === undefined &&
+            requestData.parsed?.instructions === undefined &&
+            rawSnapshot.instructions !== undefined) {
+            // If no raw/parsed exists yet, create raw with instructions
+            if (!requestData.raw) {
+                requestData.raw = { instructions: rawSnapshot.instructions };
+            }
+            else {
+                requestData.raw.instructions = rawSnapshot.instructions;
+            }
+        }
+        // Input field has been removed - use workingMemory.input instead
+        // Store messages array (actual messages sent to LLM provider)
+        const messagesToStore = parsedSnapshot.messages ?? rawSnapshot.messages;
+        if (messagesToStore !== undefined) {
+            requestData.messages = messagesToStore;
+        }
+        if (rawSnapshot.workingMemory !== undefined) {
+            requestData.workingMemory = rawSnapshot.workingMemory;
+        }
+        // Only attach if any field is present
+        const hasRequest = (requestData.raw &&
+            (requestData.raw.instructions !== undefined ||
+                requestData.raw.context !== undefined ||
+                requestData.raw.prompt !== undefined)) ||
+            (requestData.parsed &&
+                (requestData.parsed.instructions !== undefined ||
+                    requestData.parsed.context !== undefined ||
+                    requestData.parsed.prompt !== undefined)) ||
+            requestData.messages !== undefined ||
+            requestData.workingMemory !== undefined ||
+            requestData.formatGuidance !== undefined;
+        if (hasRequest) {
+            activityMetadata.request = requestData;
+        }
+        Object.assign(activityMetadata, buildActivixStartIo(aiRequestId, 'gateway-invocation', activityMetadata.request));
+        // Start activity with error handling
+        // Note: If startActivity fails (e.g., tracker not initialized, duplicate key on jobId),
+        // we still return undefined to allow the request to proceed without blocking
+        try {
+            const startedResult = await this.activix.startRecord(activityMetadata, {
+                collection: this.mainCollectionName
+            });
+            const started = {
+                ...startedResult.record,
+                activityId: startedResult.activityId,
+                recordId: startedResult.recordId
+            };
+            this.logger.info('Activity tracking start recorded', {
+                aiRequestId,
+                activityId: started?.activityId,
+                collection: this.mainCollectionName
+            });
+            return started;
+        }
+        catch (error) {
+            this.logger.error('Failed to start activity tracking', {
+                aiRequestId,
+                error: error instanceof Error ? error.message : String(error),
+                errorName: error instanceof Error ? error.name : 'UnknownError',
+                errorStack: error instanceof Error ? error.stack : undefined,
+                // Note: If you see "duplicate key error on jobId", this indicates the database
+                // has a unique index on jobId, which is INCORRECT. jobId should NOT be unique
+                // as multiple activities can share the same jobId. The unique identifier should
+                // be _id (MongoDB ObjectId), not jobId.
+                note: 'Activity tracking failed but request will continue'
+            });
+            // Return undefined to allow request to proceed without activity tracking
+            return 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
+     */
+    async startSkillExecution(request, instructionMetadata = {}, startTime) {
+        const aiRequest = request;
+        const skillId = aiRequest.skillId;
+        const skillKey = skillId ?? 'inline-template';
+        if (skillId) {
+            aiRequest.skillId = skillId;
+        }
+        // Determine inference type (will be extracted in gateway.ts and passed via request metadata)
+        const inferenceType = aiRequest.inferenceType || 'question-answer';
+        const identity = ensureGatewayRequestIdentity(request);
+        const aiRequestId = identity.aiRequestId;
+        if (!this.activix) {
+            return undefined;
+        }
+        if (this.initPromise) {
+            await this.initPromise;
+        }
+        if (!this.activix) {
+            return undefined;
+        }
+        // Build activity metadata for skill execution
+        const activityMetadata = {
+            activityType: 'skill-execution', // ✅ Required: skill-execution type
+            skillKey,
+            skillId: skillId ?? skillKey,
+            inferenceType, // ✅ Recommended: type of inference
+            aiRequestId,
+            jobTypeId: request.jobTypeId,
+            agentId: request.agentId,
+            taskId: request.taskId,
+            taskTypeId: request.taskTypeId,
+            startTime,
+            status: 'started',
+            runContext: identity,
+            ...(instructionMetadata.key && { instructionKey: instructionMetadata.key }),
+            ...(instructionMetadata.version && { instructionVersion: instructionMetadata.version }),
+            ...(instructionMetadata.rawContent && { instructionRawContent: instructionMetadata.rawContent }),
+            // ✅ Parent-child skill relationships
+            ...(aiRequest.masterSkillActivityId && { masterSkillActivityId: aiRequest.masterSkillActivityId }),
+            ...(aiRequest.masterSkillId && { masterSkillId: aiRequest.masterSkillId })
+        };
+        // Config snapshot (same as startActivity)
+        if (request.config !== undefined) {
+            activityMetadata.config = {
+                model: request.config.model,
+                provider: request.config.provider || null,
+                temperature: request.config.temperature,
+                maxTokens: request.config.maxTokens,
+                rawConfig: request.config
+            };
+        }
+        // Build request object snapshots (same as startActivity)
+        const rawSnapshot = request._rawRequest ?? {
+            instructions: request.instructions,
+            context: request.context,
+            prompt: request.prompt,
+            messages: request.messages,
+            workingMemory: request.workingMemory,
+            config: request.config
+        };
+        const parsedSnapshot = request._parsedRequest ?? {};
+        const requestData = {};
+        // raw snapshot
+        if (rawSnapshot.instructions !== undefined ||
+            rawSnapshot.context !== undefined ||
+            rawSnapshot.prompt !== undefined) {
+            requestData.raw = {
+                instructions: rawSnapshot.instructions,
+                context: rawSnapshot.context,
+                prompt: rawSnapshot.prompt
+            };
+        }
+        // parsed snapshot
+        if (parsedSnapshot.instructions !== undefined ||
+            parsedSnapshot.context !== undefined ||
+            parsedSnapshot.prompt !== undefined) {
+            requestData.parsed = {
+                instructions: parsedSnapshot.instructions,
+                context: parsedSnapshot.context,
+                prompt: parsedSnapshot.prompt
+            };
+        }
+        // Include skill-specific request structure
+        if (rawSnapshot.input !== undefined) {
+            // Parse input from JSON string to object if it's a string
+            let parsedInput = rawSnapshot.input;
+            if (typeof parsedInput === 'string') {
+                try {
+                    parsedInput = JSON.parse(parsedInput);
+                }
+                catch (e) {
+                    // If parsing fails, use the original string
+                    // This handles cases where input is a plain string, not JSON
+                }
+            }
+            requestData.input = parsedInput;
+        }
+        // Store messages array (actual messages sent to LLM provider)
+        const messagesToStore = parsedSnapshot.messages ?? rawSnapshot.messages;
+        if (messagesToStore !== undefined) {
+            requestData.messages = messagesToStore;
+        }
+        if (rawSnapshot.workingMemory !== undefined) {
+            requestData.workingMemory = rawSnapshot.workingMemory;
+        }
+        // Add skill-specific request structure
+        if (rawSnapshot.workingMemory || rawSnapshot.context) {
+            requestData.skill = {
+                variables: rawSnapshot.workingMemory,
+                context: rawSnapshot.context
+            };
+        }
+        // Only attach if any field is present
+        const hasRequest = (requestData.raw &&
+            (requestData.raw.instructions !== undefined ||
+                requestData.raw.context !== undefined ||
+                requestData.raw.prompt !== undefined)) ||
+            (requestData.parsed &&
+                (requestData.parsed.instructions !== undefined ||
+                    requestData.parsed.context !== undefined ||
+                    requestData.parsed.prompt !== undefined)) ||
+            requestData.messages !== undefined ||
+            requestData.workingMemory !== undefined ||
+            requestData.skill !== undefined;
+        if (hasRequest) {
+            activityMetadata.request = requestData;
+        }
+        Object.assign(activityMetadata, buildActivixStartIo(aiRequestId, 'skill-execution', activityMetadata.request));
+        // Start skill execution activity with error handling
+        // Activix requires explicit collection selection.
+        try {
+            const startedResult = await this.activix.startRecord(activityMetadata, {
+                collection: this.skillExecutionsCollectionName
+            });
+            const started = {
+                ...startedResult.record,
+                activityId: startedResult.activityId,
+                recordId: startedResult.recordId
+            };
+            this.logger.info('Skill execution activity tracking start recorded', {
+                aiRequestId,
+                skillId,
+                activityId: started?.activityId,
+                collection: 'skill-executions',
+                hasMasterSkillActivityId: !!aiRequest.masterSkillActivityId,
+                hasMasterSkillId: !!aiRequest.masterSkillId
+            });
+            return started;
+        }
+        catch (error) {
+            this.logger.error('Failed to start skill execution activity tracking', {
+                aiRequestId,
+                skillId,
+                error: error instanceof Error ? error.message : String(error),
+                errorName: error instanceof Error ? error.name : 'UnknownError',
+                errorStack: error instanceof Error ? error.stack : undefined,
+                note: 'Skill execution activity tracking failed but request will continue'
+            });
+            return 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)
+     */
+    async logSuccess(activity, details) {
+        if (!this.activix || !activity) {
+            return;
+        }
+        if (this.initPromise) {
+            await this.initPromise;
+        }
+        if (!this.activix) {
+            return;
+        }
+        const collection = activity.activityType === 'skill-execution'
+            ? this.skillExecutionsCollectionName
+            : activity.activityType === 'bad-request'
+                ? this.badRequestsCollectionName ?? this.mainCollectionName
+                : this.mainCollectionName;
+        // Enhanced logging to diagnose activity update issues
+        const activityId = activity.activityId || 'MISSING';
+        this.logger.info('Activity tracking updating (success)', {
+            aiRequestId: activity.aiRequestId,
+            activityId: activityId,
+            hasActivityId: !!activity.activityId,
+            endTime: details.endTime,
+            duration: details.duration,
+            activityKeys: Object.keys(activity).join(', ')
+        });
+        // Only send response/timing data - ActivityTracker will update the same record
+        // identified by the unique identifier (_id/recordId) in the activity object.
+        // jobId is just metadata for grouping - multiple activities can share the same jobId.
+        // Request data is NOT re-sent here.
+        // Log the full response structure being sent
+        this.logger.debug('Calling ActivityTracker.logSuccess', {
+            aiRequestId: activity.aiRequestId,
+            activityId: activityId,
+            cost: details.cost,
+            hasResponse: !!details.response,
+            responseStructure: {
+                hasRaw: !!details.response?.raw,
+                hasParsed: !!details.response?.parsed,
+                hasMetadata: !!details.response?.metadata,
+                hasContent: !!details.response?.content,
+                rawContentPreview: details.response?.raw?.content?.substring(0, 100),
+                parsedContentExists: !!details.response?.parsed?.parsedContent,
+                metadataKeys: details.response?.metadata ? Object.keys(details.response.metadata).slice(0, 10) : []
+            },
+            fullResponseKeys: details.response ? Object.keys(details.response) : [],
+            endTime: details.endTime,
+            duration: details.duration
+        });
+        try {
+            if (!activity.activityId || !collection) {
+                this.logger.warn('Skipping activity completion: missing activityId/collection', {
+                    aiRequestId: activity.aiRequestId,
+                    activityId: activityId,
+                    activityType: activity.activityType,
+                    collection
+                });
+                return;
+            }
+            await this.activix.completeRecord(activity.activityId, {
+                cost: details.cost,
+                response: details.response,
+                outer: {
+                    output: details.response,
+                    metadata: {}
+                },
+                endTime: details.endTime,
+                duration: details.duration
+            }, { collection });
+            this.logger.debug('Activix.completeRecord completed', {
+                aiRequestId: activity.aiRequestId,
+                activityId: activityId
+            });
+        }
+        catch (error) {
+            // Note: With silent error handling, Activix may not throw, but if it does, we want to log it.
+            this.logger.error('Failed to log success activity (non-blocking)', {
+                aiRequestId: activity.aiRequestId,
+                activityId: activityId,
+                error: error instanceof Error ? error.message : String(error),
+                errorName: error instanceof Error ? error.name : 'UnknownError',
+                errorStack: error instanceof Error ? error.stack : undefined
+            });
+        }
+    }
+    /**
+     * 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)
+     */
+    async logFailure(activity, error, details) {
+        if (!this.activix || !activity) {
+            return;
+        }
+        if (this.initPromise) {
+            await this.initPromise;
+        }
+        if (!this.activix) {
+            return;
+        }
+        const collection = activity.activityType === 'skill-execution'
+            ? this.skillExecutionsCollectionName
+            : activity.activityType === 'bad-request'
+                ? this.badRequestsCollectionName ?? this.mainCollectionName
+                : this.mainCollectionName;
+        this.logger.info('Activity tracking updating (failure)', {
+            aiRequestId: activity.aiRequestId,
+            activityId: activity.activityId,
+            endTime: details.endTime,
+            duration: details.duration,
+            error: details.error,
+            failureType: details.failureType,
+            failureSubtype: details.failureSubtype,
+            hasResponse: !!details.response
+        });
+        // Only send error/timing data - ActivityTracker will update the same record
+        // identified by the unique identifier (_id/recordId) in the activity object.
+        // jobId is just metadata for grouping - multiple activities can share the same jobId.
+        // Request data is NOT re-sent here.
+        // Include failureType and failureSubtype in error details for activity tracking
+        // For response-parsing-failure, also include response data so we can see what failed
+        const errorDetails = {
+            endTime: details.endTime,
+            duration: details.duration,
+            error: details.error
+        };
+        if (details.failureType) {
+            errorDetails.failureType = details.failureType;
+        }
+        if (details.failureSubtype) {
+            errorDetails.failureSubtype = details.failureSubtype;
+        }
+        // For response-parsing-failure, include response data so we can see what failed
+        if (details.failureType === 'response-parsing-failure' && details.response) {
+            errorDetails.response = details.response;
+            errorDetails.outer = {
+                output: details.response,
+                metadata: {}
+            };
+            this.logger.debug('Including response data in failure log (response-parsing-failure)', {
+                aiRequestId: activity.aiRequestId,
+                hasRawContent: !!details.response.raw?.content,
+                hasParsedContent: !!details.response.parsed?.content
+            });
+        }
+        try {
+            if (!activity.activityId || !collection) {
+                this.logger.warn('Skipping activity failure: missing activityId/collection', {
+                    aiRequestId: activity.aiRequestId,
+                    activityId: activity.activityId,
+                    activityType: activity.activityType,
+                    collection
+                });
+                return;
+            }
+            await this.activix.failRecord(activity.activityId, error, errorDetails, { collection, upsertIfMissing: false });
+            this.logger.debug('Activix.failRecord completed', {
+                aiRequestId: activity.aiRequestId,
+                activityId: activity.activityId
+            });
+        }
+        catch (trackingError) {
+            // Log error so we can see when ActivityTracker.logFailure fails
+            // Note: With silent error handling, ActivityTracker may not throw, but if it does, we want to log it
+            this.logger.error('Failed to log failure activity (non-blocking)', {
+                aiRequestId: activity.aiRequestId,
+                activityId: activity.activityId,
+                error: trackingError instanceof Error ? trackingError.message : String(trackingError),
+                errorName: trackingError instanceof Error ? trackingError.name : 'UnknownError',
+                errorStack: trackingError instanceof Error ? trackingError.stack : undefined,
+                originalError: error.message
+            });
+        }
+    }
+    /**
+     * 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
+     */
+    async logBadRequest(request, error, details, startTime) {
+        const identity = ensureGatewayRequestIdentity(request);
+        const aiRequestId = identity.aiRequestId;
+        const endTime = details.endTime;
+        const duration = details.duration;
+        if (!this.activix) {
+            return;
+        }
+        if (this.initPromise) {
+            await this.initPromise;
+        }
+        if (!this.activix) {
+            return;
+        }
+        this.logger.info('Logging bad request to activities', {
+            aiRequestId,
+            error: details.error,
+            errorType: details.errorType,
+            failureType: details.failureType,
+            hasDiagnosticInfo: !!details.diagnosticInfo
+        });
+        // Create a minimal activity metadata for bad requests
+        // Start with 'started' status, then logFailure will update it to 'failed'
+        const badRequestMetadata = {
+            activityType: 'bad-request',
+            aiRequestId,
+            jobTypeId: request.jobTypeId,
+            agentId: request.agentId,
+            taskId: request.taskId,
+            taskTypeId: request.taskTypeId,
+            startTime,
+            status: 'started',
+            runContext: identity
+        };
+        // Include request data if available
+        const requestData = {};
+        if (request.instructions !== undefined) {
+            requestData.raw = {
+                instructions: typeof request.instructions === 'string'
+                    ? request.instructions.substring(0, 2000) // Limit size
+                    : request.instructions
+            };
+        }
+        // Input field has been removed - use workingMemory.input instead
+        if (request.workingMemory !== undefined && request.workingMemory !== null) {
+            requestData.workingMemory = request.workingMemory;
+        }
+        if (Object.keys(requestData).length > 0) {
+            badRequestMetadata.request = requestData;
+        }
+        // Include config if available
+        if (request.config !== undefined) {
+            badRequestMetadata.config = {
+                model: request.config.model,
+                provider: request.config.provider,
+                temperature: request.config.temperature,
+                maxTokens: request.config.maxTokens,
+                rawConfig: request.config
+            };
+        }
+        // Add error details
+        const errorDetails = {
+            endTime,
+            duration,
+            error: details.error
+        };
+        if (details.errorType) {
+            errorDetails.errorType = details.errorType;
+        }
+        if (details.failureType) {
+            errorDetails.failureType = details.failureType;
+        }
+        // Include diagnostic info if provided
+        if (details.diagnosticInfo) {
+            errorDetails.diagnosticInfo = details.diagnosticInfo;
+        }
+        Object.assign(badRequestMetadata, buildActivixStartIo(aiRequestId, 'bad-request', badRequestMetadata.request));
+        try {
+            const collection = this.badRequestsCollectionName ?? this.mainCollectionName;
+            if (!collection) {
+                this.logger.warn('Skipping bad request tracking: missing bad requests collection');
+                return;
+            }
+            const startedResult = await this.activix.startRecord(badRequestMetadata, { collection });
+            const activity = {
+                ...startedResult.record,
+                activityId: startedResult.activityId,
+                recordId: startedResult.recordId
+            };
+            if (!activity.activityId) {
+                this.logger.warn('Skipping bad request failure tracking: missing activityId', { aiRequestId });
+                return;
+            }
+            await this.activix.failRecord(activity.activityId, error, errorDetails, {
+                collection,
+                upsertIfMissing: false
+            });
+            this.logger.debug('Bad request logged to activities', {
+                aiRequestId,
+                activityId: activity.activityId,
+                collection
+            });
+        }
+        catch (trackingError) {
+            // Don't fail if activity tracking fails for bad requests
+            this.logger.error('Failed to log bad request to activities (non-blocking)', {
+                aiRequestId,
+                error: trackingError instanceof Error ? trackingError.message : String(trackingError),
+                errorName: trackingError instanceof Error ? trackingError.name : 'UnknownError',
+                errorStack: trackingError instanceof Error ? trackingError.stack : undefined,
+                badRequestsCollectionName: this.badRequestsCollectionName
+            });
+        }
+    }
+    /**
+     * Gets the underlying activity tracker instance
+     *
+     * @returns Activix instance or undefined if not enabled
+     */
+    getTracker() {
+        return this.activix;
+    }
+    /**
+     * Get status of activity tracker
+     */
+    getStatus() {
+        return {
+            activityTracking: {
+                enabled: !!this.activix,
+                tracker: this.activix ? { type: 'Activix' } : undefined
+            }
+        };
+    }
+    /**
+     * Shutdown tracker
+     */
+    async shutdown() {
+        this.logger.info('Shutting down ActivityManager');
+        const ax = this.activix;
+        this.activix = undefined;
+        this.initPromise = undefined;
+        if (ax) {
+            try {
+                await ax.close();
+            }
+            catch (error) {
+                this.logger.warn('ActivityManager shutdown: Activix.close failed (non-blocking)', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    }
+}