fix: custom header support for invoke and dev commands

Three fixes for custom header handling:

1. Allow empty requestHeaderAllowlist in add-agent flows: the TextInput
   for header allowlist now accepts empty input (allowEmpty) so users
   can press Enter to skip, matching the prompt text.

2. Add -H/--header flag to invoke command: repeatable flag that accepts
   "Name: Value" pairs, normalizes header names with the AgentCore
   prefix, and injects them via SDK middleware for deployed invocations.
   Works for HTTP, MCP, and A2A protocols in both CLI and TUI modes.

3. Add -H/--header flag to dev command: same flag format, threaded
   through all local dev invoke paths (streaming, non-streaming, MCP
   tool calls, A2A) in both non-interactive and TUI modes.

Author: tejaskash

src/cli/aws/agentcore.ts

@@ -6,8 +6,34 @@ import {
   InvokeAgentRuntimeCommand,
   StopRuntimeSessionCommand,
 } from '@aws-sdk/client-bedrock-agentcore';
+import type { HttpRequest } from '@smithy/protocol-http';
 import type { DocumentType } from '@smithy/types';
 
+/**
+ * Create a BedrockAgentCoreClient with optional custom header injection middleware.
+ */
+function createAgentCoreClient(region: string, headers?: Record<string, string>): BedrockAgentCoreClient {
+  const client = new BedrockAgentCoreClient({
+    region,
+    credentials: getCredentialProvider(),
+  });
+
+  if (headers && Object.keys(headers).length > 0) {
+    client.middlewareStack.add(
+      next => async args => {
+        const request = args.request as HttpRequest;
+        for (const [name, value] of Object.entries(headers)) {
+          request.headers[name] = value;
+        }
+        return next(args);
+      },
+      { step: 'build', name: 'addCustomHeaders' }
+    );
+  }
+
+  return client;
+}
+
 /** Logger interface for SSE events */
 export interface SSELogger {
   logSSEEvent(rawLine: string): void;
@@ -25,6 +51,8 @@ export interface InvokeAgentRuntimeOptions {
   userId?: string;
   /** Optional logger for SSE event debugging */
   logger?: SSELogger;
+  /** Custom headers to forward to the agent runtime */
+  headers?: Record<string, string>;
 }
 
 export interface InvokeAgentRuntimeResult {
@@ -109,10 +137,7 @@ export function extractResult(text: string): string {
  * Returns an object with the stream generator and session ID.
  */
 export async function invokeAgentRuntimeStreaming(options: InvokeAgentRuntimeOptions): Promise<StreamingInvokeResult> {
-  const client = new BedrockAgentCoreClient({
-    region: options.region,
-    credentials: getCredentialProvider(),
-  });
+  const client = createAgentCoreClient(options.region, options.headers);
 
   const command = new InvokeAgentRuntimeCommand({
     agentRuntimeArn: options.runtimeArn,
@@ -205,10 +230,7 @@ export async function invokeAgentRuntimeStreaming(options: InvokeAgentRuntimeOpt
  * Invoke an AgentCore Runtime and return the response.
  */
 export async function invokeAgentRuntime(options: InvokeAgentRuntimeOptions): Promise<InvokeAgentRuntimeResult> {
-  const client = new BedrockAgentCoreClient({
-    region: options.region,
-    credentials: getCredentialProvider(),
-  });
+  const client = createAgentCoreClient(options.region, options.headers);
 
   const command = new InvokeAgentRuntimeCommand({
     agentRuntimeArn: options.runtimeArn,
@@ -349,6 +371,8 @@ export interface McpInvokeOptions {
   userId?: string;
   mcpSessionId?: string;
   logger?: SSELogger;
+  /** Custom headers to forward to the agent runtime */
+  headers?: Record<string, string>;
 }
 
 export interface McpToolDef {
@@ -372,10 +396,7 @@ interface McpRpcResult {
 
 /** Send a JSON-RPC payload through InvokeAgentRuntime and return the parsed response. */
 async function mcpRpcCall(options: McpInvokeOptions, body: Record<string, unknown>): Promise<McpRpcResult> {
-  const client = new BedrockAgentCoreClient({
-    region: options.region,
-    credentials: getCredentialProvider(),
-  });
+  const client = createAgentCoreClient(options.region, options.headers);
 
   options.logger?.logSSEEvent(`MCP request: ${JSON.stringify(body)}`);
 
@@ -420,10 +441,7 @@ async function mcpRpcCallStrict(options: McpInvokeOptions, body: Record<string,
 
 /** Send a JSON-RPC notification (no id, no response expected). */
 async function mcpRpcNotify(options: McpInvokeOptions, body: Record<string, unknown>): Promise<void> {
-  const client = new BedrockAgentCoreClient({
-    region: options.region,
-    credentials: getCredentialProvider(),
-  });
+  const client = createAgentCoreClient(options.region, options.headers);
 
   const command = new InvokeAgentRuntimeCommand({
     agentRuntimeArn: options.runtimeArn,
@@ -592,6 +610,8 @@ export interface A2AInvokeOptions {
   runtimeArn: string;
   userId?: string;
   logger?: SSELogger;
+  /** Custom headers to forward to the agent runtime */
+  headers?: Record<string, string>;
 }
 
 let a2aRequestId = 1;
@@ -601,10 +621,7 @@ let a2aRequestId = 1;
  * Streams text parts from the response artifacts.
  */
 export async function invokeA2ARuntime(options: A2AInvokeOptions, message: string): Promise<StreamingInvokeResult> {
-  const client = new BedrockAgentCoreClient({
-    region: options.region,
-    credentials: getCredentialProvider(),
-  });
+  const client = createAgentCoreClient(options.region, options.headers);
 
   const body = {
     jsonrpc: '2.0',

src/cli/commands/dev/command.tsx

@@ -1,4 +1,5 @@
 import { findConfigRoot, getWorkingDirectory, readEnvFile } from '../../../lib';
+import { parseHeaderFlags } from '../shared/header-utils';
 import { getErrorMessage } from '../../errors';
 import { ExecLogger } from '../../logging';
 import {
@@ -29,16 +30,16 @@ const ENTER_ALT_SCREEN = '\x1B[?1049h\x1B[H';
 const EXIT_ALT_SCREEN = '\x1B[?1049l';
 const SHOW_CURSOR = '\x1B[?25h';
 
-async function invokeDevServer(port: number, prompt: string, stream: boolean): Promise<void> {
+async function invokeDevServer(port: number, prompt: string, stream: boolean, headers?: Record<string, string>): Promise<void> {
   try {
     if (stream) {
       // Stream response to stdout
-      for await (const chunk of invokeAgentStreaming(port, prompt)) {
+      for await (const chunk of invokeAgentStreaming({ port, message: prompt, headers })) {
         process.stdout.write(chunk);
       }
       process.stdout.write('\n');
     } else {
-      const response = await invokeAgent(port, prompt);
+      const response = await invokeAgent({ port, message: prompt, headers });
       console.log(response);
     }
   } catch (err) {
@@ -52,9 +53,9 @@ async function invokeDevServer(port: number, prompt: string, stream: boolean): P
   }
 }
 
-async function invokeA2ADevServer(port: number, prompt: string): Promise<void> {
+async function invokeA2ADevServer(port: number, prompt: string, headers?: Record<string, string>): Promise<void> {
   try {
-    for await (const chunk of invokeForProtocol('A2A', { port, message: prompt })) {
+    for await (const chunk of invokeForProtocol('A2A', { port, message: prompt, headers })) {
       process.stdout.write(chunk);
     }
     process.stdout.write('\n');
@@ -69,10 +70,10 @@ async function invokeA2ADevServer(port: number, prompt: string): Promise<void> {
   }
 }
 
-async function handleMcpInvoke(port: number, invokeValue: string, toolName?: string, input?: string): Promise<void> {
+async function handleMcpInvoke(port: number, invokeValue: string, toolName?: string, input?: string, headers?: Record<string, string>): Promise<void> {
   try {
     if (invokeValue === 'list-tools') {
-      const { tools } = await listMcpTools(port);
+      const { tools } = await listMcpTools(port, undefined, headers);
       if (tools.length === 0) {
         console.log('No tools available.');
         return;
@@ -89,7 +90,7 @@ async function handleMcpInvoke(port: number, invokeValue: string, toolName?: str
         process.exit(1);
       }
       // Initialize session first, then call tool with the session ID
-      const { sessionId } = await listMcpTools(port);
+      const { sessionId } = await listMcpTools(port, undefined, headers);
       let args: Record<string, unknown> = {};
       if (input) {
         try {
@@ -100,7 +101,7 @@ async function handleMcpInvoke(port: number, invokeValue: string, toolName?: str
           process.exit(1);
         }
       }
-      const result = await callMcpTool(port, toolName, args, sessionId);
+      const result = await callMcpTool(port, toolName, args, sessionId, undefined, headers);
       console.log(result);
     } else {
       console.error(`Error: Unknown MCP invoke command "${invokeValue}"`);
@@ -132,10 +133,17 @@ export const registerDev = (program: Command) => {
     .option('-l, --logs', 'Run dev server with logs to stdout [non-interactive]')
     .option('--tool <name>', 'MCP tool name (used with --invoke call-tool)')
     .option('--input <json>', 'MCP tool arguments as JSON (used with --invoke call-tool)')
+    .option('-H, --header <header>', 'Custom header to forward to the agent (format: "Name: Value", repeatable)', (val: string, prev: string[]) => [...prev, val], [] as string[])
     .action(async opts => {
       try {
         const port = parseInt(opts.port, 10);
 
+        // Parse custom headers
+        let headers: Record<string, string> | undefined;
+        if (opts.header && opts.header.length > 0) {
+          headers = parseHeaderFlags(opts.header);
+        }
+
         // If --invoke provided, call the dev server and exit
         if (opts.invoke) {
           const invokeProject = await loadProjectConfig(getWorkingDirectory());
@@ -166,11 +174,11 @@ export const registerDev = (program: Command) => {
 
           // Protocol-aware dispatch
           if (protocol === 'MCP') {
-            await handleMcpInvoke(invokePort, opts.invoke, opts.tool, opts.input);
+            await handleMcpInvoke(invokePort, opts.invoke, opts.tool, opts.input, headers);
           } else if (protocol === 'A2A') {
-            await invokeA2ADevServer(invokePort, opts.invoke);
+            await invokeA2ADevServer(invokePort, opts.invoke, headers);
           } else {
-            await invokeDevServer(invokePort, opts.invoke, opts.stream ?? false);
+            await invokeDevServer(invokePort, opts.invoke, opts.stream ?? false, headers);
           }
           return;
         }
@@ -308,6 +316,7 @@ export const registerDev = (program: Command) => {
               workingDir={workingDir}
               port={port}
               agentName={opts.agent}
+              headers={headers}
             />
           </LayoutProvider>
         );

src/cli/commands/invoke/action.ts

@@ -95,6 +95,7 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
       region: targetConfig.region,
       runtimeArn: agentState.runtimeArn,
       userId: options.userId,
+      headers: options.headers,
     };
 
     // list-tools: list available MCP tools
@@ -167,7 +168,7 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
   if (agentSpec.protocol === 'A2A') {
     try {
       const a2aResult = await invokeA2ARuntime(
-        { region: targetConfig.region, runtimeArn: agentState.runtimeArn, userId: options.userId },
+        { region: targetConfig.region, runtimeArn: agentState.runtimeArn, userId: options.userId, headers: options.headers },
         options.prompt
       );
       let response = '';
@@ -214,6 +215,7 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
         sessionId: options.sessionId,
         userId: options.userId,
         logger, // Pass logger for SSE event debugging
+        headers: options.headers,
       });
 
       for await (const chunk of result.stream) {
@@ -245,6 +247,7 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
     payload: options.prompt,
     sessionId: options.sessionId,
     userId: options.userId,
+    headers: options.headers,
   });
 
   logger.logResponse(response.content);

src/cli/commands/invoke/command.tsx

@@ -2,6 +2,7 @@ import { getErrorMessage } from '../../errors';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireProject } from '../../tui/guards';
 import { InvokeScreen } from '../../tui/screens/invoke';
+import { parseHeaderFlags } from '../shared/header-utils';
 import { handleInvoke, loadInvokeConfig } from './action';
 import type { InvokeOptions } from './types';
 import { validateInvokeOptions } from './validate';
@@ -103,6 +104,7 @@ export const registerInvoke = (program: Command) => {
     .option('--stream', 'Stream response in real-time (TUI streams by default) [non-interactive]')
     .option('--tool <name>', 'MCP tool name (use with "call-tool" prompt) [non-interactive]')
     .option('--input <json>', 'MCP tool arguments as JSON (use with --tool) [non-interactive]')
+    .option('-H, --header <header>', 'Custom header to forward to the agent (format: "Name: Value", repeatable)', (val: string, prev: string[]) => [...prev, val], [] as string[])
     .action(
       async (
         positionalPrompt: string | undefined,
@@ -116,13 +118,20 @@ export const registerInvoke = (program: Command) => {
           stream?: boolean;
           tool?: string;
           input?: string;
+          header?: string[];
         }
       ) => {
         try {
           requireProject();
           // --prompt flag takes precedence over positional argument
           const prompt = cliOptions.prompt ?? positionalPrompt;
 
+          // Parse custom headers
+          let headers: Record<string, string> | undefined;
+          if (cliOptions.header && cliOptions.header.length > 0) {
+            headers = parseHeaderFlags(cliOptions.header);
+          }
+
           // CLI mode if any CLI-specific options provided (follows deploy command pattern)
           if (
             prompt ||
@@ -142,15 +151,17 @@ export const registerInvoke = (program: Command) => {
               stream: cliOptions.stream,
               tool: cliOptions.tool,
               input: cliOptions.input,
+              headers,
             });
           } else {
-            // No CLI options - interactive TUI mode
+            // No CLI options - interactive TUI mode (headers still passed if provided)
             const { waitUntilExit } = render(
               <InvokeScreen
                 isInteractive={true}
                 onExit={() => process.exit(0)}
                 initialSessionId={cliOptions.sessionId}
                 initialUserId={cliOptions.userId}
+                initialHeaders={headers}
               />
             );
             await waitUntilExit();

src/cli/commands/invoke/types.ts

@@ -10,6 +10,8 @@ export interface InvokeOptions {
   tool?: string;
   /** MCP tool arguments as JSON string (used with --tool) */
   input?: string;
+  /** Custom headers to forward to the agent runtime (key-value pairs) */
+  headers?: Record<string, string>;
 }
 
 export interface InvokeResult {