feat: add gateway exceptionLevel support and automatic Transaction Search

src/cli/commands/add/types.ts

@@ -36,6 +36,7 @@ export interface AddGatewayOptions {
   agentClientSecret?: string;
   agents?: string;
   semanticSearch?: boolean;
+  exceptionLevel?: string;
   json?: boolean;
 }
 

src/cli/commands/add/validate.ts

@@ -2,6 +2,7 @@ import { ConfigIO, findConfigRoot } from '../../../lib';
 import {
   AgentNameSchema,
   BuildTypeSchema,
+  GatewayExceptionLevelSchema,
   GatewayNameSchema,
   ModelProviderSchema,
   SDKFrameworkSchema,
@@ -208,6 +209,14 @@ export function validateAddGatewayOptions(options: AddGatewayOptions): Validatio
     return { valid: false, error: 'Agent OAuth credentials are only valid with CUSTOM_JWT authorizer' };
   }
 
+  // Validate exception level if provided
+  if (options.exceptionLevel) {
+    const levelResult = GatewayExceptionLevelSchema.safeParse(options.exceptionLevel);
+    if (!levelResult.success) {
+      return { valid: false, error: `Invalid exception level: ${options.exceptionLevel}. Use NONE or DEBUG` };
+    }
+  }
+
   return { valid: true };
 }
 

src/cli/commands/deploy/actions.ts

@@ -309,7 +309,7 @@ export async function handleDeploy(options: ValidatedDeployOptions): Promise<Dep
     }
 
     // Deploy
-    const hasGateways = mcpSpec?.agentCoreGateways && mcpSpec.agentCoreGateways.length > 0;
+    const hasGateways = (mcpSpec?.agentCoreGateways?.length ?? 0) > 0;
     const deployStepName = hasGateways ? 'Deploying gateways...' : 'Deploy to AWS';
     startStep(deployStepName);
 
@@ -419,9 +419,14 @@ export async function handleDeploy(options: ValidatedDeployOptions): Promise<Dep
     // Post-deploy: Enable CloudWatch Transaction Search (non-blocking, silent)
     const nextSteps = agentNames.length > 0 ? [...AGENT_NEXT_STEPS] : [...MEMORY_ONLY_NEXT_STEPS];
     const notes: string[] = [];
-    if (agentNames.length > 0) {
+    if (agentNames.length > 0 || hasGateways) {
       try {
-        const tsResult = await setupTransactionSearch({ region: target.region, accountId: target.account, agentNames });
+        const tsResult = await setupTransactionSearch({
+          region: target.region,
+          accountId: target.account,
+          agentNames,
+          hasGateways,
+        });
         if (tsResult.error) {
           logger.log(`Transaction search setup warning: ${tsResult.error}`, 'warn');
         } else {

src/cli/operations/deploy/__tests__/post-deploy-observability.test.ts

@@ -80,4 +80,36 @@ describe('setupTransactionSearch', () => {
 
     expect(result).toEqual({ success: false, error: 'Insufficient permissions' });
   });
+
+  it('triggers when hasGateways is true and agentNames is empty', async () => {
+    const result = await setupTransactionSearch({
+      region: 'us-west-2',
+      accountId: '111222333444',
+      agentNames: [],
+      hasGateways: true,
+    });
+    expect(mockEnableTransactionSearch).toHaveBeenCalledWith('us-west-2', '111222333444', 100);
+    expect(result).toEqual({ success: true });
+  });
+
+  it('skips when both agentNames empty and hasGateways false', async () => {
+    const result = await setupTransactionSearch({
+      region: 'us-east-1',
+      accountId: '123456789012',
+      agentNames: [],
+      hasGateways: false,
+    });
+    expect(result).toEqual({ success: true });
+    expect(mockEnableTransactionSearch).not.toHaveBeenCalled();
+  });
+
+  it('skips when agentNames empty and hasGateways undefined', async () => {
+    const result = await setupTransactionSearch({
+      region: 'us-east-1',
+      accountId: '123456789012',
+      agentNames: [],
+    });
+    expect(result).toEqual({ success: true });
+    expect(mockEnableTransactionSearch).not.toHaveBeenCalled();
+  });
 });

src/cli/operations/deploy/post-deploy-observability.ts

@@ -5,6 +5,7 @@ export interface TransactionSearchSetupOptions {
   region: string;
   accountId: string;
   agentNames: string[];
+  hasGateways?: boolean;
 }
 
 export interface TransactionSearchSetupResult {
@@ -26,7 +27,7 @@ export async function setupTransactionSearch(
 ): Promise<TransactionSearchSetupResult> {
   const { region, accountId, agentNames } = options;
 
-  if (agentNames.length === 0) {
+  if (agentNames.length === 0 && !options.hasGateways) {
     return { success: true };
   }
 

src/cli/primitives/GatewayPrimitive.ts

@@ -27,6 +27,7 @@ export interface AddGatewayOptions {
   agentClientSecret?: string;
   agents?: string;
   enableSemanticSearch?: boolean;
+  exceptionLevel?: string;
 }
 
 /**
@@ -158,6 +159,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
       .option('--agent-client-secret <secret>', 'Agent OAuth client secret')
       .option('--agents <agents>', 'Comma-separated agent names')
       .option('--no-semantic-search', 'Disable semantic search for tool discovery')
+      .option('--exception-level <level>', 'Exception verbosity level', 'NONE')
       .option('--json', 'Output as JSON')
       .action(async (rawOptions: Record<string, string | boolean | undefined>) => {
         const cliOptions = rawOptions as unknown as CLIAddGatewayOptions;
@@ -189,6 +191,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
             agentClientSecret: cliOptions.agentClientSecret,
             agents: cliOptions.agents,
             enableSemanticSearch: cliOptions.semanticSearch !== false,
+            exceptionLevel: cliOptions.exceptionLevel,
           });
 
           if (cliOptions.json) {
@@ -286,6 +289,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
       authorizerType: options.authorizerType,
       jwtConfig: undefined,
       enableSemanticSearch: options.enableSemanticSearch ?? true,
+      exceptionLevel: options.exceptionLevel === 'DEBUG' ? 'DEBUG' : 'NONE',
     };
 
     if (options.authorizerType === 'CUSTOM_JWT' && options.discoveryUrl) {
@@ -353,6 +357,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
       authorizerType: config.authorizerType,
       authorizerConfiguration: this.buildAuthorizerConfiguration(config),
       enableSemanticSearch: config.enableSemanticSearch,
+      exceptionLevel: config.exceptionLevel,
     };
 
     mcpSpec.agentCoreGateways.push(gateway);

src/cli/primitives/__tests__/GatewayPrimitive.test.ts

@@ -0,0 +1,64 @@
+import type { AgentCoreMcpSpec } from '../../../schema';
+import { GatewayPrimitive } from '../GatewayPrimitive';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { mockConfigExists, mockReadMcpSpec, mockWriteMcpSpec } = vi.hoisted(() => ({
+  mockConfigExists: vi.fn().mockReturnValue(true),
+  mockReadMcpSpec: vi.fn().mockResolvedValue({ agentCoreGateways: [] }),
+  mockWriteMcpSpec: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../../../lib', () => {
+  const MockConfigIO = vi.fn(function (this: Record<string, unknown>) {
+    this.configExists = mockConfigExists;
+    this.readMcpSpec = mockReadMcpSpec;
+    this.writeMcpSpec = mockWriteMcpSpec;
+  });
+  return {
+    ConfigIO: MockConfigIO,
+    findConfigRoot: vi.fn().mockReturnValue('/fake/root'),
+    setEnvVar: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+/** Extract the first gateway written to writeMcpSpec. */
+function getWrittenGateway() {
+  expect(mockWriteMcpSpec).toHaveBeenCalledTimes(1);
+  const spec = mockWriteMcpSpec.mock.calls[0]![0] as AgentCoreMcpSpec;
+  const gw = spec.agentCoreGateways[0];
+  expect(gw).toBeDefined();
+  return gw!;
+}
+
+describe('GatewayPrimitive', () => {
+  let primitive: GatewayPrimitive;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockReadMcpSpec.mockResolvedValue({ agentCoreGateways: [] });
+    primitive = new GatewayPrimitive();
+  });
+
+  describe('exceptionLevel', () => {
+    it('defaults to exceptionLevel NONE', async () => {
+      await primitive.add({ name: 'test-gw', authorizerType: 'NONE' });
+
+      const gw = getWrittenGateway();
+      expect(gw.exceptionLevel).toBe('NONE');
+    });
+
+    it('exceptionLevel DEBUG passes through', async () => {
+      await primitive.add({ name: 'test-gw', authorizerType: 'NONE', exceptionLevel: 'DEBUG' });
+
+      const gw = getWrittenGateway();
+      expect(gw.exceptionLevel).toBe('DEBUG');
+    });
+
+    it('invalid exceptionLevel falls back to NONE', async () => {
+      await primitive.add({ name: 'test-gw', authorizerType: 'NONE', exceptionLevel: 'VERBOSE' });
+
+      const gw = getWrittenGateway();
+      expect(gw.exceptionLevel).toBe('NONE');
+    });
+  });
+});

src/cli/tui/hooks/useCreateMcp.ts

@@ -29,6 +29,7 @@ export function useCreateGateway() {
         agentClientId: config.jwtConfig?.agentClientId,
         agentClientSecret: config.jwtConfig?.agentClientSecret,
         enableSemanticSearch: config.enableSemanticSearch,
+        exceptionLevel: config.exceptionLevel,
       });
       if (!addResult.success) {
         throw new Error(addResult.error ?? 'Failed to create gateway');

src/cli/tui/screens/deploy/useDeployFlow.ts

@@ -380,12 +380,21 @@ export function useDeployFlow(options: DeployFlowOptions = {}): DeployFlowState
           const agentNames = context?.projectSpec.agents?.map((a: { name: string }) => a.name) ?? [];
           const targetRegion = context?.awsTargets[0]?.region;
           const targetAccount = context?.awsTargets[0]?.account;
-          if (agentNames.length > 0 && targetRegion && targetAccount) {
+          let hasGateways = false;
+          try {
+            const tsConfigIO = new ConfigIO();
+            const mcpSpec = await tsConfigIO.readMcpSpec();
+            hasGateways = (mcpSpec?.agentCoreGateways?.length ?? 0) > 0;
+          } catch {
+            // No mcp.json or invalid -- no gateways
+          }
+          if ((agentNames.length > 0 || hasGateways) && targetRegion && targetAccount) {
             try {
               const tsResult = await setupTransactionSearch({
                 region: targetRegion,
                 accountId: targetAccount,
                 agentNames,
+                hasGateways,
               });
               if (tsResult.error) {
                 logger.log(`Transaction search setup warning: ${tsResult.error}`, 'warn');

src/cli/tui/screens/mcp/AddGatewayScreen.tsx

@@ -15,7 +15,12 @@ import { HELP_TEXT } from '../../constants';
 import { useListNavigation, useMultiSelectNavigation } from '../../hooks';
 import { generateUniqueName } from '../../utils';
 import type { AddGatewayConfig } from './types';
-import { AUTHORIZER_TYPE_OPTIONS, GATEWAY_STEP_LABELS, SEMANTIC_SEARCH_ITEM_ID } from './types';
+import {
+  AUTHORIZER_TYPE_OPTIONS,
+  EXCEPTION_LEVEL_ITEM_ID,
+  GATEWAY_STEP_LABELS,
+  SEMANTIC_SEARCH_ITEM_ID,
+} from './types';
 import { useAddGatewayWizard } from './useAddGatewayWizard';
 import { Box, Text } from 'ink';
 import React, { useMemo, useState } from 'react';
@@ -51,7 +56,10 @@ export function AddGatewayScreen({ onComplete, onExit, existingGateways, unassig
   );
 
   const advancedConfigItems: SelectableItem[] = useMemo(
-    () => [{ id: SEMANTIC_SEARCH_ITEM_ID, title: 'Semantic Search' }],
+    () => [
+      { id: SEMANTIC_SEARCH_ITEM_ID, title: 'Semantic Search' },
+      { id: EXCEPTION_LEVEL_ITEM_ID, title: 'Debug Exception Level' },
+    ],
     []
   );
 
@@ -83,7 +91,10 @@ export function AddGatewayScreen({ onComplete, onExit, existingGateways, unassig
     getId: item => item.id,
     initialSelectedIds: INITIAL_ADVANCED_SELECTED,
     onConfirm: selectedIds =>
-      wizard.setAdvancedConfig({ enableSemanticSearch: selectedIds.includes(SEMANTIC_SEARCH_ITEM_ID) }),
+      wizard.setAdvancedConfig({
+        enableSemanticSearch: selectedIds.includes(SEMANTIC_SEARCH_ITEM_ID),
+        exceptionLevel: selectedIds.includes(EXCEPTION_LEVEL_ITEM_ID) ? 'DEBUG' : 'NONE',
+      }),
     onExit: () => wizard.goBack(),
     isActive: isAdvancedConfigStep,
     requireSelection: false,
@@ -273,6 +284,7 @@ export function AddGatewayScreen({ onComplete, onExit, existingGateways, unassig
                     : '(none)',
               },
               { label: 'Semantic Search', value: wizard.config.enableSemanticSearch ? 'Enabled' : 'Disabled' },
+              { label: 'Exception Level', value: wizard.config.exceptionLevel === 'DEBUG' ? 'Debug' : 'None' },
             ]}
           />
         )}