@x12i/ai-gateway 7.9.1

package/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/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 {};