@cdklabs/cdk-appmod-catalog-blueprints 1.13.0 → 1.14.0

package/lib/framework/agents/interactive-agent.d.ts

@@ -1,8 +1,9 @@
 import { Duration, RemovalPolicy } from 'aws-cdk-lib';
-import { RestApi } from 'aws-cdk-lib/aws-apigateway';
+import { CognitoUserPoolsAuthorizer, RestApi } from 'aws-cdk-lib/aws-apigateway';
 import { CfnRuntime } from 'aws-cdk-lib/aws-bedrockagentcore';
 import { UserPool, UserPoolClient } from 'aws-cdk-lib/aws-cognito';
-import { Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
+import { ITable } from 'aws-cdk-lib/aws-dynamodb';
+import { IGrantable, Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
 import { IKey, Key } from 'aws-cdk-lib/aws-kms';
 import { IFunction, Architecture, ILayerVersion } from 'aws-cdk-lib/aws-lambda';
 import { IBucket } from 'aws-cdk-lib/aws-s3';
@@ -59,6 +60,14 @@ export interface StreamingHttpAdapterProps {
      * @default Uses authenticator from InteractiveAgent
      */
     readonly authenticator?: IAuthenticator;
+    /**
+     * HTTP methods to allow in CORS preflight responses.
+     * Use this to enable additional methods (GET, DELETE, PUT) for custom routes
+     * added to the REST API.
+     *
+     * @default ['POST', 'OPTIONS']
+     */
+    readonly corsAllowMethods?: string[];
 }
 /**
  * Streaming HTTP adapter for real-time agent communication via SSE.
@@ -106,6 +115,10 @@ export declare class StreamingHttpAdapter implements ICommunicationAdapter {
      * The REST API Gateway.
      */
     readonly restApi?: RestApi;
+    /**
+     * The Cognito User Pools authorizer (if Cognito authentication is enabled).
+     */
+    readonly cognitoAuthorizer?: CognitoUserPoolsAuthorizer;
     /**
      * The API endpoint URL.
      */
@@ -426,6 +439,115 @@ export declare class CognitoAuthenticator implements IAuthenticator {
      */
     _setScope(scope: Construct): void;
 }
+/**
+ * Strategy interface for session index storage.
+ *
+ * Session indexes provide fast user to session lookups for listing and managing sessions.
+ * The default implementation (DynamoDBSessionIndex) uses DynamoDB for efficient queries.
+ */
+export interface ISessionIndex {
+    /**
+     * Grant read/write permissions to a grantee.
+     *
+     * @param grantee - The principal that needs access to the session index
+     */
+    grantReadWrite(grantee: IGrantable): void;
+    /**
+     * Get environment variables for Lambda configuration.
+     *
+     * @returns Environment variables to configure the session index
+     */
+    environmentVariables(): Record<string, string>;
+}
+/**
+ * Configuration properties for DynamoDBSessionIndex.
+ */
+export interface DynamoDBSessionIndexProps {
+    /**
+     * Existing DynamoDB table to use.
+     * Table must have partition key 'user_id' (String) and sort key 'session_id' (String).
+     *
+     * @default Auto-created table
+     */
+    readonly table?: ITable;
+    /**
+     * Time-to-live for session index records.
+     * When set, expired records are automatically removed by DynamoDB TTL.
+     *
+     * @default No TTL (sessions persist until explicitly deleted)
+     */
+    readonly sessionTTL?: Duration;
+    /**
+     * KMS key for table encryption.
+     *
+     * @default AWS managed encryption
+     */
+    readonly encryptionKey?: IKey;
+    /**
+     * Removal policy for the DynamoDB table.
+     *
+     * @default RemovalPolicy.DESTROY
+     */
+    readonly removalPolicy?: RemovalPolicy;
+}
+/**
+ * DynamoDB-based session index for fast user to session lookups.
+ *
+ * Creates a DynamoDB table indexed by user_id (partition key) and session_id (sort key)
+ * for efficient querying of a user's sessions. The table stores session metadata
+ * including creation time, last update time, and optional TTL for automatic cleanup.
+ *
+ * ## Table Schema
+ *
+ * - **Partition Key**: user_id (String) - User identifier from authentication
+ * - **Sort Key**: session_id (String) - Unique session identifier
+ * - **Attributes**: created_at, updated_at, last_message, expires_at (optional)
+ *
+ * ## Features
+ *
+ * - **Fast Lookups**: Query all sessions for a user in O(1) using partition key
+ * - **Automatic Expiration**: Optional TTL removes stale sessions automatically
+ * - **On-Demand Capacity**: Pay-per-request billing, no capacity planning needed
+ * - **Encryption**: AWS managed or customer-managed KMS encryption
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Asset } from 'aws-cdk-lib/aws-s3-assets';
+ * import { Duration } from 'aws-cdk-lib';
+ * import { InteractiveAgent, DynamoDBSessionIndex } from '@cdklabs/cdk-appmod-catalog-blueprints';
+ *
+ * const myPrompt = new Asset(this, 'Prompt', { path: './prompt.txt' });
+ * const sessionIndex = new DynamoDBSessionIndex(this, 'SessionIndex', {
+ *   sessionTTL: Duration.days(7)
+ * });
+ *
+ * const agent = new InteractiveAgent(this, 'Agent', {
+ *   agentName: 'ChatAgent',
+ *   agentDefinition: { bedrockModel: {}, systemPrompt: myPrompt },
+ *   sessionIndex
+ * });
+ * ```
+ */
+export declare class DynamoDBSessionIndex implements ISessionIndex {
+    /**
+     * The DynamoDB table used for session index storage.
+     */
+    readonly table: ITable;
+    /**
+     * The session TTL duration (if configured).
+     */
+    readonly sessionTTL?: Duration;
+    constructor(scope: Construct, id: string, props?: DynamoDBSessionIndexProps);
+    /**
+     * Grant read/write permissions to a grantee.
+     */
+    grantReadWrite(grantee: IGrantable): void;
+    /**
+     * Get environment variables for Lambda configuration.
+     */
+    environmentVariables(): Record<string, string>;
+}
 /**
  * No-authentication authenticator for development and testing.
  *
@@ -541,6 +663,14 @@ export interface LambdaHostingAdapterProps {
      * @default CognitoAuthenticator
      */
     readonly authenticator?: IAuthenticator;
+    /**
+     * HTTP methods to allow in CORS preflight responses.
+     * Use this to enable additional methods (GET, DELETE, PUT) for custom routes
+     * added to the REST API.
+     *
+     * @default ['POST', 'OPTIONS']
+     */
+    readonly corsAllowMethods?: string[];
     /**
      * Lambda function memory size in MB.
      *
@@ -731,6 +861,13 @@ export interface InteractiveAgentProps extends BaseAgentProps {
      * @default Duration.hours(24)
      */
     readonly sessionTTL?: Duration;
+    /**
+     * Session index for fast user to session lookups.
+     * Provides efficient querying of a user's sessions for listing and management.
+     *
+     * @default DynamoDBSessionIndex (auto-created)
+     */
+    readonly sessionIndex?: ISessionIndex;
     /**
      * Context strategy for conversation history management.
      *
@@ -755,6 +892,14 @@ export interface InteractiveAgentProps extends BaseAgentProps {
      * @default CognitoAuthenticator
      */
     readonly authenticator?: IAuthenticator;
+    /**
+     * HTTP methods to allow in CORS preflight responses.
+     * Use this to enable additional methods (GET, DELETE, PUT) for custom routes
+     * added to the REST API.
+     *
+     * @default ['POST', 'OPTIONS']
+     */
+    readonly corsAllowMethods?: string[];
     /**
      * Lambda function memory size in MB.
      *
@@ -840,6 +985,18 @@ export declare class InteractiveAgent extends BaseAgent {
     readonly apiEndpoint: string;
     readonly sessionBucket?: IBucket;
     readonly cfnRuntime?: CfnRuntime;
+    /**
+     * The session index for fast user to session lookups.
+     */
+    readonly sessionIndex?: ISessionIndex;
+    /**
+     * The REST API Gateway (only available when using LambdaHostingAdapter with StreamingHttpAdapter).
+     */
+    readonly restApi?: RestApi;
+    /**
+     * The Cognito User Pools authorizer (only available when using LambdaHostingAdapter with CognitoAuthenticator).
+     */
+    readonly cognitoAuthorizer?: CognitoUserPoolsAuthorizer;
     constructor(scope: Construct, id: string, props: InteractiveAgentProps);
     /**
      * Validates InteractiveAgent props.