feat(handlers): carry ABCA solution UA on every SDK client; trace per invocation

All ~60 client instantiations now pass abcaUserAgent() and are wrapped
withAbcaTrace() (document clients instrument the inner DynamoDBClient —
shared middleware stack). Handler entry points set the trace to their
freshly minted ulid() request id; orchestrate-task uses the task id.
Stream consumers (fanout, approval-metrics) carry no trace by design.

No behavior change beyond the UA headers; all 2031 existing tests pass
unmodified (withAbcaTrace no-ops on bare-object constructor mocks).

Task 4 of PR #338 plan. Part of #319

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: scottschreckengaust

cdk/src/handlers/approve-task.ts

@@ -27,8 +27,9 @@ import { logger } from './shared/logger';
 import { formatMinuteBucket } from './shared/rate-limit';
 import { ErrorCode, errorResponse, successResponse } from './shared/response';
 import type { ApprovalRequest, ApprovalResponse, ApprovalScope } from './shared/types';
+import { abcaUserAgent, setAbcaTrace, withAbcaTrace } from './shared/ua';
 
-const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+const ddb = DynamoDBDocumentClient.from(withAbcaTrace(new DynamoDBClient(abcaUserAgent())));
 const TASK_TABLE_NAME = process.env.TASK_TABLE_NAME;
 const TASK_APPROVALS_TABLE_NAME = process.env.TASK_APPROVALS_TABLE_NAME;
 const EVENTS_TABLE_NAME = process.env.TASK_EVENTS_TABLE_NAME;
@@ -65,6 +66,7 @@ const AUDIT_EVENT_RETENTION_DAYS = Number(process.env.TASK_RETENTION_DAYS ?? '90
  */
 export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
   const requestId = ulid();
+  setAbcaTrace(requestId);
 
   try {
     // 1. Auth

cdk/src/handlers/cancel-task.ts

@@ -28,11 +28,12 @@ import { extractUserId } from './shared/gateway';
 import { logger } from './shared/logger';
 import { ErrorCode, errorResponse, successResponse } from './shared/response';
 import type { TaskRecord } from './shared/types';
+import { abcaUserAgent, setAbcaTrace, withAbcaTrace } from './shared/ua';
 import { computeTtlEpoch } from './shared/validation';
 
-const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
-const agentCoreClient = new BedrockAgentCoreClient({});
-const ecsClient = new ECSClient({});
+const ddb = DynamoDBDocumentClient.from(withAbcaTrace(new DynamoDBClient(abcaUserAgent())));
+const agentCoreClient = withAbcaTrace(new BedrockAgentCoreClient(abcaUserAgent()));
+const ecsClient = withAbcaTrace(new ECSClient(abcaUserAgent()));
 const TABLE_NAME = process.env.TASK_TABLE_NAME!;
 const EVENTS_TABLE_NAME = process.env.TASK_EVENTS_TABLE_NAME!;
 const TASK_RETENTION_DAYS = Number(process.env.TASK_RETENTION_DAYS ?? '90');
@@ -44,6 +45,7 @@ const ECS_CLUSTER_ARN = process.env.ECS_CLUSTER_ARN;
  */
 export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
   const requestId = ulid();
+  setAbcaTrace(requestId);
 
   try {
     // 1. Extract authenticated user

cdk/src/handlers/cleanup-pending-uploads.ts

@@ -44,9 +44,10 @@ import { DeleteObjectsCommand, ListObjectVersionsCommand, S3Client } from '@aws-
 import { ulid } from 'ulid';
 import { ATTACHMENT_OBJECT_KEY_PREFIX } from '../constructs/attachments-bucket';
 import { logger } from './shared/logger';
+import { abcaUserAgent, withAbcaTrace } from './shared/ua';
 
-const ddb = new DynamoDBClient({});
-const s3 = new S3Client({});
+const ddb = withAbcaTrace(new DynamoDBClient(abcaUserAgent()));
+const s3 = withAbcaTrace(new S3Client(abcaUserAgent()));
 
 const TASK_TABLE = process.env.TASK_TABLE_NAME!;
 const EVENTS_TABLE = process.env.TASK_EVENTS_TABLE_NAME!;

cdk/src/handlers/confirm-uploads.ts

@@ -35,11 +35,12 @@ import { estimateImageTokensFromBuffer } from './shared/image-tokens';
 import { logger } from './shared/logger';
 import { ErrorCode, errorResponse, successResponse } from './shared/response';
 import { type AttachmentRecord, createAttachmentRecord, type TaskRecord, toTaskDetail } from './shared/types';
+import { abcaUserAgent, setAbcaTrace, withAbcaTrace } from './shared/ua';
 import { computeTtlEpoch } from './shared/validation';
 
-const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
-const s3Client = new S3Client({});
-const lambdaClient = process.env.ORCHESTRATOR_FUNCTION_ARN ? new LambdaClient({}) : undefined;
+const ddb = DynamoDBDocumentClient.from(withAbcaTrace(new DynamoDBClient(abcaUserAgent())));
+const s3Client = withAbcaTrace(new S3Client(abcaUserAgent()));
+const lambdaClient = process.env.ORCHESTRATOR_FUNCTION_ARN ? withAbcaTrace(new LambdaClient(abcaUserAgent())) : undefined;
 
 const TABLE_NAME = process.env.TASK_TABLE_NAME!;
 const EVENTS_TABLE_NAME = process.env.TASK_EVENTS_TABLE_NAME!;
@@ -80,6 +81,7 @@ interface S3ObjectMeta {
  */
 export async function handler(event: APIGatewayProxyEvent, context: Context): Promise<APIGatewayProxyResult> {
   const requestId = ulid();
+  setAbcaTrace(requestId);
 
   try {
     // 1. Auth
@@ -697,7 +699,7 @@ async function buildScreeningConfig(): Promise<ScreeningConfig | undefined> {
   if (!process.env.GUARDRAIL_ID || !process.env.GUARDRAIL_VERSION) return undefined;
   if (!_bedrockClient) {
     const { BedrockRuntimeClient } = await import('@aws-sdk/client-bedrock-runtime');
-    _bedrockClient = new BedrockRuntimeClient({});
+    _bedrockClient = withAbcaTrace(new BedrockRuntimeClient(abcaUserAgent()));
   }
   return {
     guardrailId: process.env.GUARDRAIL_ID,

cdk/src/handlers/create-task.ts

@@ -24,13 +24,15 @@ import { buildChannelMetadata, extractUserId } from './shared/gateway';
 import { logger } from './shared/logger';
 import { ErrorCode, errorResponse } from './shared/response';
 import type { CreateTaskRequest } from './shared/types';
+import { setAbcaTrace } from './shared/ua';
 import { parseBody } from './shared/validation';
 
 /**
  * POST /v1/tasks — Create a new task (Cognito-authenticated).
  */
 export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
   const requestId = ulid();
+  setAbcaTrace(requestId);
 
   try {
     // 1. Extract authenticated user

cdk/src/handlers/create-webhook.ts

@@ -27,10 +27,11 @@ import { extractUserId } from './shared/gateway';
 import { logger } from './shared/logger';
 import { ErrorCode, errorResponse, successResponse } from './shared/response';
 import type { CreateWebhookRequest, CreateWebhookResponse, WebhookRecord } from './shared/types';
+import { abcaUserAgent, setAbcaTrace, withAbcaTrace } from './shared/ua';
 import { isValidWebhookName, parseBody } from './shared/validation';
 
-const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
-const sm = new SecretsManagerClient({});
+const ddb = DynamoDBDocumentClient.from(withAbcaTrace(new DynamoDBClient(abcaUserAgent())));
+const sm = withAbcaTrace(new SecretsManagerClient(abcaUserAgent()));
 const TABLE_NAME = process.env.WEBHOOK_TABLE_NAME!;
 const SECRET_PREFIX = 'bgagent/webhook/';
 
@@ -39,6 +40,7 @@ const SECRET_PREFIX = 'bgagent/webhook/';
  */
 export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
   const requestId = ulid();
+  setAbcaTrace(requestId);
 
   try {
     const userId = extractUserId(event);

cdk/src/handlers/delete-webhook.ts

@@ -26,10 +26,11 @@ import { extractUserId } from './shared/gateway';
 import { logger } from './shared/logger';
 import { ErrorCode, errorResponse, successResponse } from './shared/response';
 import { type WebhookRecord, toWebhookDetail } from './shared/types';
+import { abcaUserAgent, setAbcaTrace, withAbcaTrace } from './shared/ua';
 import { computeTtlEpoch } from './shared/validation';
 
-const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
-const sm = new SecretsManagerClient({});
+const ddb = DynamoDBDocumentClient.from(withAbcaTrace(new DynamoDBClient(abcaUserAgent())));
+const sm = withAbcaTrace(new SecretsManagerClient(abcaUserAgent()));
 const TABLE_NAME = process.env.WEBHOOK_TABLE_NAME!;
 const SECRET_PREFIX = 'bgagent/webhook/';
 const WEBHOOK_RETENTION_DAYS = Number(process.env.WEBHOOK_RETENTION_DAYS ?? '30');
@@ -39,6 +40,7 @@ const WEBHOOK_RETENTION_DAYS = Number(process.env.WEBHOOK_RETENTION_DAYS ?? '30'
  */
 export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
   const requestId = ulid();
+  setAbcaTrace(requestId);
 
   try {
     const userId = extractUserId(event);

cdk/src/handlers/deny-task.ts

@@ -27,8 +27,9 @@ import { logger } from './shared/logger';
 import { formatMinuteBucket } from './shared/rate-limit';
 import { ErrorCode, errorResponse, successResponse } from './shared/response';
 import { DENY_REASON_MAX_LENGTH, type DenyRequest, type DenyResponse } from './shared/types';
+import { abcaUserAgent, setAbcaTrace, withAbcaTrace } from './shared/ua';
 
-const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+const ddb = DynamoDBDocumentClient.from(withAbcaTrace(new DynamoDBClient(abcaUserAgent())));
 const TASK_TABLE_NAME = process.env.TASK_TABLE_NAME;
 const TASK_APPROVALS_TABLE_NAME = process.env.TASK_APPROVALS_TABLE_NAME;
 const EVENTS_TABLE_NAME = process.env.TASK_EVENTS_TABLE_NAME;
@@ -63,6 +64,7 @@ const AUDIT_EVENT_RETENTION_DAYS = Number(process.env.TASK_RETENTION_DAYS ?? '90
  */
 export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
   const requestId = ulid();
+  setAbcaTrace(requestId);
 
   try {
     // 1. Auth

cdk/src/handlers/fanout-task-events.ts

@@ -53,6 +53,7 @@ import { logger } from './shared/logger';
 import { coerceNumericOrNull } from './shared/numeric';
 import { loadRepoConfig } from './shared/repo-config';
 import type { ChannelConfig, TaskNotificationsConfig, TaskRecord } from './shared/types';
+import { abcaUserAgent, withAbcaTrace } from './shared/ua';
 import { dispatchSlackEvent, SlackApiError } from './slack-notify';
 
 // Re-export the shared types so existing test imports (and any future
@@ -362,7 +363,7 @@ export function shouldFanOut(event: FanOutEvent, overrides?: TaskNotificationsCo
  * internally (the Slack API rejecting a message — e.g.
  * ``channel_not_found`` — is not recoverable by a Lambda retry).
  */
-const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+const ddb = DynamoDBDocumentClient.from(withAbcaTrace(new DynamoDBClient(abcaUserAgent())));
 
 /**
  * Slack dispatcher — hands the event to the in-module

cdk/src/handlers/get-pending.ts

@@ -26,8 +26,9 @@ import { logger } from './shared/logger';
 import { formatMinuteBucket } from './shared/rate-limit';
 import { ErrorCode, errorResponse, successResponse } from './shared/response';
 import type { GetPendingResponse, PendingApprovalSummary, Severity } from './shared/types';
+import { abcaUserAgent, setAbcaTrace, withAbcaTrace } from './shared/ua';
 
-const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+const ddb = DynamoDBDocumentClient.from(withAbcaTrace(new DynamoDBClient(abcaUserAgent())));
 const TASK_APPROVALS_TABLE_NAME = process.env.TASK_APPROVALS_TABLE_NAME;
 if (!TASK_APPROVALS_TABLE_NAME) {
   throw new Error('get-pending handler requires TASK_APPROVALS_TABLE_NAME env var');
@@ -54,6 +55,7 @@ const PENDING_LIST_LIMIT = 100;
  */
 export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
   const requestId = ulid();
+  setAbcaTrace(requestId);
 
   try {
     const userId = extractUserId(event);