bedrock-agentcore 0.1.1 → 0.2.2

package/dist/src/runtime/client.js

@@ -0,0 +1,319 @@
+import { defaultProvider } from '@aws-sdk/credential-provider-node';
+import { HttpRequest } from '@aws-sdk/protocol-http';
+import { SignatureV4 } from '@aws-sdk/signature-v4';
+import { Sha256 } from '@aws-crypto/sha256-js';
+import { randomUUID, randomBytes } from 'crypto';
+import { getDataPlaneEndpoint } from '../_utils/endpoints.js';
+import { DEFAULT_PRESIGNED_URL_TIMEOUT, MAX_PRESIGNED_URL_TIMEOUT } from './types.js';
+/**
+ * Client for generating WebSocket authentication for AgentCore Runtime.
+ *
+ * This client provides authentication credentials for WebSocket connections
+ * to AgentCore Runtime endpoints, allowing applications to establish
+ * bidirectional streaming connections with agent runtimes.
+ *
+ * The client is stateless and does not manage session lifecycle. Each method
+ * call is independent and takes the runtime ARN as a parameter.
+ *
+ * @example
+ * ```typescript
+ * const client = new RuntimeClient({ region: 'us-west-2' })
+ *
+ * // Generate WebSocket connection with SigV4 headers
+ * const { url, headers } = await client.generateWsConnection({
+ *   runtimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime',
+ *   endpointName: 'DEFAULT'
+ * })
+ *
+ * // Generate presigned WebSocket URL
+ * const presignedUrl = await client.generatePresignedUrl({
+ *   runtimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime',
+ *   expires: 300
+ * })
+ * ```
+ */
+export class RuntimeClient {
+    region;
+    credentialsProvider;
+    /**
+     * Creates a new RuntimeClient instance.
+     *
+     * @param config - Configuration options for the client
+     * @throws Error if region is not provided via config or AWS_REGION environment variable
+     */
+    constructor(config = {}) {
+        const region = config.region ?? process.env.AWS_REGION;
+        if (!region || !region.trim()) {
+            throw new Error('Region must be provided via config.region or AWS_REGION environment variable');
+        }
+        this.region = region;
+        this.credentialsProvider = config.credentialsProvider ?? defaultProvider();
+    }
+    /**
+     * Parses runtime ARN and extracts components.
+     *
+     * @param runtimeArn - Full runtime ARN
+     * @returns Parsed ARN components
+     * @throws Error if ARN format is invalid
+     *
+     * @internal
+     */
+    _parseRuntimeArn(runtimeArn) {
+        const arnRegex = /^arn:aws:bedrock-agentcore:([^:]+):([^:]+):runtime\/(.+)$/;
+        const match = runtimeArn.match(arnRegex);
+        if (!match) {
+            throw new Error(`Invalid runtime ARN format: ${runtimeArn}`);
+        }
+        const [, region, accountId, runtimeId] = match;
+        if (!region || !accountId || !runtimeId) {
+            throw new Error('ARN components cannot be empty');
+        }
+        return { region, accountId, runtimeId };
+    }
+    /**
+     * Builds WebSocket URL with query parameters.
+     *
+     * @param runtimeArn - Full runtime ARN
+     * @param endpointName - Optional endpoint name for qualifier param
+     * @param customHeaders - Optional custom query parameters
+     * @returns WebSocket URL with query parameters
+     *
+     * @internal
+     */
+    _buildWebSocketUrl(runtimeArn, endpointName, customHeaders) {
+        // Get the data plane endpoint and build base URL
+        const endpoint = getDataPlaneEndpoint(this.region);
+        const encodedArn = encodeURIComponent(runtimeArn);
+        const url = new URL(`${endpoint}/runtimes/${encodedArn}/ws`);
+        // Add query parameters
+        if (endpointName) {
+            url.searchParams.set('qualifier', endpointName);
+        }
+        if (customHeaders) {
+            Object.entries(customHeaders).forEach(([key, value]) => {
+                url.searchParams.set(key, value);
+            });
+        }
+        // Convert to WebSocket URL
+        return url.toString().replace('https://', 'wss://');
+    }
+    /**
+     * Generates WebSocket URL and SigV4 signed headers for runtime connection.
+     *
+     * This method creates authentication credentials for establishing a WebSocket
+     * connection to an AgentCore Runtime. The returned headers include AWS SigV4
+     * signature for authentication.
+     *
+     * @param params - Parameters for generating the connection
+     * @returns WebSocket URL and authentication headers
+     *
+     * @throws Error if runtime ARN format is invalid
+     * @throws Error if AWS credentials are not available
+     *
+     * @example
+     * ```typescript
+     * const client = new RuntimeClient({ region: 'us-west-2' })
+     *
+     * // With auto-generated session ID
+     * const { url, headers } = await client.generateWsConnection({
+     *   runtimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-runtime'
+     * })
+     *
+     * // With custom session ID and endpoint
+     * const connection = await client.generateWsConnection({
+     *   runtimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-runtime',
+     *   sessionId: 'my-session-123',
+     *   endpointName: 'DEFAULT'
+     * })
+     * ```
+     */
+    async generateWsConnection(params) {
+        this._parseRuntimeArn(params.runtimeArn);
+        const sessionId = params.sessionId ?? randomUUID();
+        const wsUrl = this._buildWebSocketUrl(params.runtimeArn, params.endpointName);
+        const credentials = await this.credentialsProvider();
+        if (!credentials) {
+            throw new Error('No AWS credentials found');
+        }
+        // Create and sign the request
+        const url = new URL(wsUrl.replace('wss://', 'https://'));
+        const signedRequest = await new SignatureV4({
+            credentials,
+            region: this.region,
+            service: 'bedrock-agentcore',
+            sha256: Sha256,
+        }).sign(new HttpRequest({
+            protocol: 'https:',
+            hostname: url.hostname,
+            path: url.pathname,
+            query: Object.fromEntries(url.searchParams.entries()),
+            method: 'GET',
+            headers: {
+                host: url.hostname,
+                'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id': sessionId,
+            },
+        }));
+        // Return WebSocket connection with signed headers + WebSocket upgrade headers
+        return {
+            url: wsUrl,
+            headers: {
+                ...signedRequest.headers,
+                Connection: 'Upgrade',
+                Upgrade: 'websocket',
+                'Sec-WebSocket-Version': '13',
+                'Sec-WebSocket-Key': randomBytes(16).toString('base64'),
+                'User-Agent': 'AgentCoreRuntimeClient/1.0',
+            },
+        };
+    }
+    /**
+     * Generates a presigned WebSocket URL for runtime connection.
+     *
+     * Presigned URLs include authentication in query parameters, allowing
+     * frontend clients to connect without managing AWS credentials.
+     *
+     * @param params - Parameters for generating the presigned URL
+     * @returns Presigned WebSocket URL with authentication in query parameters
+     *
+     * @throws Error if expires exceeds maximum (300 seconds)
+     * @throws Error if runtime ARN format is invalid
+     * @throws Error if AWS credentials are not available
+     *
+     * @example
+     * ```typescript
+     * const client = new RuntimeClient({ region: 'us-west-2' })
+     *
+     * // Basic presigned URL
+     * const url = await client.generatePresignedUrl({
+     *   runtimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-runtime'
+     * })
+     *
+     * // With custom parameters
+     * const url = await client.generatePresignedUrl({
+     *   runtimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-runtime',
+     *   sessionId: 'my-session-123',
+     *   endpointName: 'DEFAULT',
+     *   customHeaders: { 'custom-param': 'value' },
+     *   expires: 300
+     * })
+     * ```
+     */
+    async generatePresignedUrl(params) {
+        // Validate expires parameter
+        const expires = params.expires ?? DEFAULT_PRESIGNED_URL_TIMEOUT;
+        if (expires > MAX_PRESIGNED_URL_TIMEOUT) {
+            throw new Error(`Expiry timeout cannot exceed ${MAX_PRESIGNED_URL_TIMEOUT} seconds, got ${expires}`);
+        }
+        // Validate ARN
+        this._parseRuntimeArn(params.runtimeArn);
+        // Auto-generate session ID if not provided
+        const sessionId = params.sessionId ?? randomUUID();
+        // Build minimal WebSocket URL without any custom parameters
+        // This should match the working presigned URL format
+        const wsUrl = this._buildWebSocketUrl(params.runtimeArn, params.endpointName, {
+            ...params.customHeaders,
+            'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id': sessionId,
+        });
+        // Convert wss:// to https:// for signing
+        const httpsUrl = wsUrl.replace('wss://', 'https://');
+        const url = new URL(httpsUrl);
+        // Get AWS credentials
+        const credentials = await this.credentialsProvider();
+        if (!credentials) {
+            throw new Error('No AWS credentials found');
+        }
+        // Create minimal request to sign - separate path and query for presigned URLs
+        const request = new HttpRequest({
+            method: 'GET',
+            protocol: 'https:',
+            hostname: url.hostname,
+            path: url.pathname,
+            query: Object.fromEntries(url.searchParams.entries()),
+            headers: {
+                host: url.hostname,
+            },
+        });
+        // Sign the request with SigV4 (presigned URL style) following the exact pattern
+        const signer = new SignatureV4({
+            credentials,
+            region: this.region,
+            service: 'bedrock-agentcore',
+            sha256: Sha256,
+        });
+        const signedRequest = await signer.presign(request, { expiresIn: expires });
+        // Construct the full signed URL with query parameters
+        let presignedUrl = `${signedRequest.protocol}//${signedRequest.hostname}${signedRequest.path}`;
+        // Add the signature query parameters
+        if (signedRequest.query) {
+            const existingParams = presignedUrl.includes('?') ? '&' : '?';
+            const queryString = Object.entries(signedRequest.query)
+                .map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`)
+                .join('&');
+            presignedUrl += existingParams + queryString;
+        }
+        // Convert signed URL from https:// back to wss://
+        const presignedWsUrl = presignedUrl.replace('https://', 'wss://');
+        return presignedWsUrl;
+    }
+    /**
+     * Generates WebSocket URL and OAuth headers for runtime connection.
+     *
+     * This method uses OAuth bearer token authentication instead of AWS SigV4.
+     * Suitable for scenarios where OAuth tokens are used for authentication.
+     * Does NOT require AWS credentials.
+     *
+     * @param params - Parameters for generating the connection
+     * @returns WebSocket URL and OAuth authentication headers
+     *
+     * @throws Error if bearer token is empty
+     * @throws Error if runtime ARN format is invalid
+     *
+     * @example
+     * ```typescript
+     * const client = new RuntimeClient({ region: 'us-west-2' })
+     *
+     * // With OAuth bearer token
+     * const { url, headers } = await client.generateWsConnectionOAuth({
+     *   runtimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123:runtime/my-runtime',
+     *   bearerToken: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
+     *   endpointName: 'DEFAULT'
+     * })
+     *
+     * // Use with WebSocket client
+     * const ws = new WebSocket(url, { headers })
+     * ```
+     */
+    async generateWsConnectionOAuth(params) {
+        // Validate bearer token
+        if (!params.bearerToken) {
+            throw new Error('Bearer token cannot be empty');
+        }
+        // Validate ARN
+        this._parseRuntimeArn(params.runtimeArn);
+        // Auto-generate session ID if not provided
+        const sessionId = params.sessionId ?? randomUUID();
+        // Build WebSocket URL
+        const wsUrl = this._buildWebSocketUrl(params.runtimeArn, params.endpointName);
+        // Convert wss:// to https:// to get host
+        const httpsUrl = wsUrl.replace('wss://', 'https://');
+        const url = new URL(httpsUrl);
+        // Generate WebSocket key (required for OAuth connections)
+        const wsKey = randomBytes(16).toString('base64');
+        // Build OAuth headers
+        const headers = {
+            Authorization: `Bearer ${params.bearerToken}`,
+            'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id': sessionId,
+            Host: url.hostname,
+            Connection: 'Upgrade',
+            Upgrade: 'websocket',
+            'Sec-WebSocket-Key': wsKey,
+            'Sec-WebSocket-Version': '13',
+            'User-Agent': 'OAuth-WebSocket-Client/1.0',
+        };
+        return {
+            url: wsUrl,
+            headers,
+        };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/runtime/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/runtime/client.ts"],"names":[],"mappings":"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"}

package/dist/src/runtime/context.d.ts

@@ -0,0 +1,33 @@
+import type { RequestContext } from './types.js';
+/**
+ * Get the current request context.
+ *
+ * @returns The RequestContext if called within a request scope (inside runWithContext),
+ *          undefined otherwise (e.g., during app initialization or outside request handlers)
+ *
+ * @example
+ * ```typescript
+ * import { getContext } from 'bedrock-agentcore/context'
+ *
+ * const handler = async (request, context) => {
+ *   const ctx = getContext()
+ *   console.log('Request ID:', ctx?.requestId)
+ *   console.log('Session ID:', ctx?.sessionId)
+ * }
+ * ```
+ */
+export declare function getContext(): RequestContext | undefined;
+/**
+ * Run a function within a request context scope.
+ * The context will be available via getContext() throughout the entire async call chain.
+ *
+ * This function is internal to the runtime module and should not be used directly by customers.
+ * It is automatically called by BedrockAgentCoreApp to set up context for each request.
+ *
+ * @param context - The request context to make available
+ * @param fn - The function to execute within the context scope
+ * @returns The return value of the function
+ * @internal
+ */
+export declare function runWithContext<T>(context: RequestContext, fn: () => T): T;
+//# sourceMappingURL=context.d.ts.map

package/dist/src/runtime/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/runtime/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAahD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,IAAI,cAAc,GAAG,SAAS,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEzE"}

package/dist/src/runtime/context.js

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from 'async_hooks';
+/**
+ * AsyncLocalStorage instance for storing request-scoped context.
+ * This provides thread-safe, automatic context propagation across async operations.
+ *
+ * This is private to prevent misuse - all context operations should go through
+ * getContext() and runWithContext() to maintain proper isolation guarantees.
+ *
+ * Note: Requires Node.js - Uses AsyncLocalStorage from 'async_hooks' module.
+ */
+const requestContextStorage = new AsyncLocalStorage();
+/**
+ * Get the current request context.
+ *
+ * @returns The RequestContext if called within a request scope (inside runWithContext),
+ *          undefined otherwise (e.g., during app initialization or outside request handlers)
+ *
+ * @example
+ * ```typescript
+ * import { getContext } from 'bedrock-agentcore/context'
+ *
+ * const handler = async (request, context) => {
+ *   const ctx = getContext()
+ *   console.log('Request ID:', ctx?.requestId)
+ *   console.log('Session ID:', ctx?.sessionId)
+ * }
+ * ```
+ */
+export function getContext() {
+    return requestContextStorage.getStore();
+}
+/**
+ * Run a function within a request context scope.
+ * The context will be available via getContext() throughout the entire async call chain.
+ *
+ * This function is internal to the runtime module and should not be used directly by customers.
+ * It is automatically called by BedrockAgentCoreApp to set up context for each request.
+ *
+ * @param context - The request context to make available
+ * @param fn - The function to execute within the context scope
+ * @returns The return value of the function
+ * @internal
+ */
+export function runWithContext(context, fn) {
+    return requestContextStorage.run(context, fn);
+}
+// Note: runWithContext is exported for use within the runtime module (app.ts)
+// but should not be re-exported from the public API (index.ts)
+//# sourceMappingURL=context.js.map

package/dist/src/runtime/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG/C;;;;;;;;GAQG;AACH,MAAM,qBAAqB,GAAG,IAAI,iBAAiB,EAAkB,CAAA;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,qBAAqB,CAAC,QAAQ,EAAE,CAAA;AACzC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAI,OAAuB,EAAE,EAAW;IACpE,OAAO,qBAAqB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;AAC/C,CAAC;AAED,8EAA8E;AAC9E,+DAA+D"}

package/dist/src/runtime/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AgentCore Runtime module
+ */
+export { BedrockAgentCoreApp } from './app.js';
+export { RuntimeClient } from './client.js';
+export type { BedrockAgentCoreAppConfig, ContentTypeParserConfig, InvocationHandler as Handler, RequestContext, HealthStatus, HealthCheckResponse, AsyncTaskInfo, AsyncTaskStatus, RuntimeClientConfig, GenerateWsConnectionParams, GeneratePresignedUrlParams, GenerateWsConnectionOAuthParams, WebSocketConnection, ParsedRuntimeArn, } from './types.js';
+export { DEFAULT_PRESIGNED_URL_TIMEOUT, MAX_PRESIGNED_URL_TIMEOUT, DEFAULT_REGION, RuntimeArnSchema } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,YAAY,EACV,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,IAAI,OAAO,EAC5B,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,0BAA0B,EAC1B,0BAA0B,EAC1B,+BAA+B,EAC/B,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/runtime/index.js

@@ -0,0 +1,7 @@
+/**
+ * AgentCore Runtime module
+ */
+export { BedrockAgentCoreApp } from './app.js';
+export { RuntimeClient } from './client.js';
+export { DEFAULT_PRESIGNED_URL_TIMEOUT, MAX_PRESIGNED_URL_TIMEOUT, DEFAULT_REGION, RuntimeArnSchema } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/src/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAiB3C,OAAO,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA"}