fix(payments): blockers from deep review — gate completeness, secrets, regex, recovery

- F-01-1: gate payment env-var injection + IAM grants by language (Python)
  and protocol (HTTP). New helper isPaymentEligibleRuntime is used in
  PaymentManagerPrimitive.add, the vended cdk-stack.ts payment loop, and
  dev/payment-env.ts so non-Python or non-HTTP runtimes never get env vars
  they cannot consume.
- F-01-2: emit hooks=[ConfigBundleHook()] alongside plugins= in both the
  template and the regex-emitted Agent block. Prevents existing config-bundle
  customers from silently losing system-prompt injection when adding payments.
- R-13-1: insert the payment import at the top of main.py (after the file
  docstring and any from __future__ imports). Removes a regex that could
  splice the new import inside a parenthesised multi-line from x import (...)
  block and produce a SyntaxError.
- R-13-2: tighten the agent-replacement regexes — allow trailing # type: ignore
  comments, allow typed-annotation _agent: Agent | None = None form, and
  abort cleanly when the call site is replaced but the singleton has an
  unrecognised shape rather than shipping corrupted code.
- S-02-1: re-add after remove now correctly patches main.py. The previous
  early-return short-circuited the whole flow when remove() left payments.py
  behind.
- D-12-2: when CFN succeeds but the post-deploy state-write fails, surface
  the stack name + region + recovery commands so the user can fix the local
  I/O issue or manually delete the orphan stack.
- C-05-3: exclude .env / .env.local / .env.* files from the deploy zip at
  any depth. Closes a footgun for BYO projects with --code-location . where
  agentcore/.env.local could otherwise be packaged into S3.

Tests: 8 new cases covering paren-aware imports, docstring + future,
type-ignore comments, typed annotations, abort path, re-add cycle, and
.env exclusion at any depth.

Author: aidandaly24

src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -326,6 +326,22 @@ function toCdkId(name: string): string {
   return name.replace(/_/g, '');
 }
 
+/**
+ * Decide whether a deployed runtime should receive payment env vars + IAM grants.
+ * Payments today only ships a runtime shim for Python HTTP runtimes; injecting
+ * AGENTCORE_PAYMENT_* env vars into TypeScript / MCP / A2A / AGUI runtimes
+ * would surface env vars they cannot consume and would dilute least-privilege
+ * IAM grants for runtimes that never call ProcessPayment.
+ */
+function isPaymentEligibleAgent(agent: { entrypoint?: string; protocol?: string }): boolean {
+  if (agent.protocol && agent.protocol !== 'HTTP') {
+    return false;
+  }
+  const entrypoint = typeof agent.entrypoint === 'string' ? agent.entrypoint : '';
+  const entrypointFile = entrypoint.split(':')[0] ?? '';
+  return entrypointFile.endsWith('.py');
+}
+
 /**
  * CDK Stack that deploys AgentCore infrastructure.
  *
@@ -372,8 +388,14 @@ export class AgentCoreStack extends Stack {
 
         const prefix = \`AGENTCORE_PAYMENT_\${payment.name.toUpperCase().replace(/-/g, '_')}\`;
 
-        // Wire env vars from construct output tokens into all agent environments
+        // Wire env vars from construct output tokens into eligible agent environments only.
+        // See isPaymentEligibleAgent — non-Python or non-HTTP runtimes have no shim that
+        // can consume these env vars, and giving them sts:AssumeRole on the
+        // ProcessPaymentRole would broaden the privilege surface unnecessarily.
         for (const env of this.application.environments.values()) {
+          if (!isPaymentEligibleAgent(env.agent)) {
+            continue;
+          }
           env.runtime.addEnvironmentVariable(\`\${prefix}_MANAGER_ARN\`, manager.paymentManagerArn);
           env.runtime.addEnvironmentVariable(\`\${prefix}_PROCESS_PAYMENT_ROLE_ARN\`, manager.processPaymentRoleArn);
 
@@ -412,9 +434,10 @@ export class AgentCoreStack extends Stack {
             credentialProviderArn: connector.credentialProviderArn,
           });
 
-          // Wire first connector's ID as env var
+          // Wire first connector's ID as env var (eligible agents only)
           if (connector === payment.connectors[0]) {
             for (const env of this.application.environments.values()) {
+              if (!isPaymentEligibleAgent(env.agent)) continue;
               env.runtime.addEnvironmentVariable(\`\${prefix}_CONNECTOR_ID\`, conn.paymentConnectorId);
             }
           }
@@ -5003,7 +5026,8 @@ async def invoke(payload, context):
         session_manager=get_memory_session_manager(mem_session_id, mem_user_id),
         system_prompt=DEFAULT_SYSTEM_PROMPT + PAYMENT_SYSTEM_PROMPT,
         tools=tools,
-        plugins=plugins,
+        plugins=plugins,{{#if hasConfigBundle}}
+        hooks=[ConfigBundleHook()],{{/if}}
     )
 {{else}}
     session_id = getattr(context, 'session_id', 'default-session')
@@ -5016,7 +5040,8 @@ async def invoke(payload, context):
         model=load_model(),
         system_prompt=DEFAULT_SYSTEM_PROMPT + PAYMENT_SYSTEM_PROMPT,
         tools=tools,
-        plugins=plugins,
+        plugins=plugins,{{#if hasConfigBundle}}
+        hooks=[ConfigBundleHook()],{{/if}}
     )
 {{else}}
 {{#if hasConfigBundle}}

src/assets/cdk/lib/cdk-stack.ts

@@ -51,6 +51,22 @@ function toCdkId(name: string): string {
   return name.replace(/_/g, '');
 }
 
+/**
+ * Decide whether a deployed runtime should receive payment env vars + IAM grants.
+ * Payments today only ships a runtime shim for Python HTTP runtimes; injecting
+ * AGENTCORE_PAYMENT_* env vars into TypeScript / MCP / A2A / AGUI runtimes
+ * would surface env vars they cannot consume and would dilute least-privilege
+ * IAM grants for runtimes that never call ProcessPayment.
+ */
+function isPaymentEligibleAgent(agent: { entrypoint?: string; protocol?: string }): boolean {
+  if (agent.protocol && agent.protocol !== 'HTTP') {
+    return false;
+  }
+  const entrypoint = typeof agent.entrypoint === 'string' ? agent.entrypoint : '';
+  const entrypointFile = entrypoint.split(':')[0] ?? '';
+  return entrypointFile.endsWith('.py');
+}
+
 /**
  * CDK Stack that deploys AgentCore infrastructure.
  *
@@ -97,8 +113,14 @@ export class AgentCoreStack extends Stack {
 
         const prefix = `AGENTCORE_PAYMENT_${payment.name.toUpperCase().replace(/-/g, '_')}`;
 
-        // Wire env vars from construct output tokens into all agent environments
+        // Wire env vars from construct output tokens into eligible agent environments only.
+        // See isPaymentEligibleAgent — non-Python or non-HTTP runtimes have no shim that
+        // can consume these env vars, and giving them sts:AssumeRole on the
+        // ProcessPaymentRole would broaden the privilege surface unnecessarily.
         for (const env of this.application.environments.values()) {
+          if (!isPaymentEligibleAgent(env.agent)) {
+            continue;
+          }
           env.runtime.addEnvironmentVariable(`${prefix}_MANAGER_ARN`, manager.paymentManagerArn);
           env.runtime.addEnvironmentVariable(`${prefix}_PROCESS_PAYMENT_ROLE_ARN`, manager.processPaymentRoleArn);
 
@@ -137,9 +159,10 @@ export class AgentCoreStack extends Stack {
             credentialProviderArn: connector.credentialProviderArn,
           });
 
-          // Wire first connector's ID as env var
+          // Wire first connector's ID as env var (eligible agents only)
           if (connector === payment.connectors[0]) {
             for (const env of this.application.environments.values()) {
+              if (!isPaymentEligibleAgent(env.agent)) continue;
               env.runtime.addEnvironmentVariable(`${prefix}_CONNECTOR_ID`, conn.paymentConnectorId);
             }
           }

src/assets/python/http/strands/base/main.py

@@ -215,7 +215,8 @@ async def invoke(payload, context):
         session_manager=get_memory_session_manager(mem_session_id, mem_user_id),
         system_prompt=DEFAULT_SYSTEM_PROMPT + PAYMENT_SYSTEM_PROMPT,
         tools=tools,
-        plugins=plugins,
+        plugins=plugins,{{#if hasConfigBundle}}
+        hooks=[ConfigBundleHook()],{{/if}}
     )
 {{else}}
     session_id = getattr(context, 'session_id', 'default-session')
@@ -228,7 +229,8 @@ async def invoke(payload, context):
         model=load_model(),
         system_prompt=DEFAULT_SYSTEM_PROMPT + PAYMENT_SYSTEM_PROMPT,
         tools=tools,
-        plugins=plugins,
+        plugins=plugins,{{#if hasConfigBundle}}
+        hooks=[ConfigBundleHook()],{{/if}}
     )
 {{else}}
 {{#if hasConfigBundle}}

src/cli/commands/deploy/actions.ts

@@ -558,7 +558,25 @@ export async function handleDeploy(options: ValidatedDeployOptions): Promise<Dep
       runtimeEndpoints,
       payments,
     });
-    await configIO.writeDeployedState(deployedState);
+    // CFN succeeded by this point — failing to persist deployed-state.json
+    // would leave AWS resources without a local pointer for teardown. Surface
+    // a recovery message that names the stack + region so the user can
+    // either teardown manually or re-run `agentcore status` once the local
+    // I/O issue is resolved.
+    try {
+      await configIO.writeDeployedState(deployedState);
+    } catch (writeErr) {
+      const msg = writeErr instanceof Error ? writeErr.message : String(writeErr);
+      logger.log(
+        `WARNING: deploy succeeded but writing agentcore/deployed-state.json failed: ${msg}.\n` +
+          `  Stack: ${stackName} (region: ${target.region})\n` +
+          `  AWS resources are running but the CLI cannot track them locally.\n` +
+          `  Recovery options:\n` +
+          `    1) Fix the local I/O problem (disk space / permissions on agentcore/) and run \`agentcore status\` to refresh.\n` +
+          `    2) If you want to teardown what was deployed: \`aws cloudformation delete-stack --stack-name ${stackName} --region ${target.region}\``
+      );
+      throw writeErr;
+    }
 
     // Show gateway URLs and target sync status
     if (Object.keys(gateways).length > 0) {

src/cli/commands/dev/browser-mode.ts

@@ -134,6 +134,11 @@ export async function runBrowserMode(opts: BrowserModeOptions): Promise<void> {
   const { workingDir, project, agentName, otelEnvVars = {}, collector } = opts;
 
   const configRoot = findConfigRoot(workingDir);
+  // Browser mode serves multiple agents; we don't know which agent will be
+  // launched until the user picks one in the web UI. Pass no runtime so
+  // payment env vars are emitted for any deployed manager and the spawned
+  // agent decides whether to consume them. Single-agent CLI dev correctly
+  // narrows by runtime via loadDevEnv(workingDir, runtime) elsewhere.
   const { envVars } = await loadDevEnv(workingDir);
 
   const supportedAgents = getDevSupportedAgents(project);

src/cli/commands/dev/command.tsx

@@ -341,7 +341,8 @@ export const registerDev = (program: Command) => {
           }
 
           const agentName = opts.runtime ?? project.runtimes[0]?.name;
-          const { envVars } = await loadDevEnv(workingDir);
+          const selectedRuntime = project.runtimes.find(r => r.name === agentName);
+          const { envVars } = await loadDevEnv(workingDir, selectedRuntime);
           const mergedEnvVars = { ...envVars, ...otelEnvVars };
           const config = getDevConfig(workingDir, project, configRoot ?? undefined, agentName);
 

src/cli/operations/dev/load-dev-env.ts

@@ -1,4 +1,5 @@
 import { findConfigRoot, readEnvFile } from '../../../lib';
+import type { AgentEnvSpec } from '../../../schema';
 import { getGatewayEnvVars } from './gateway-env.js';
 import { getMemoryEnvVars } from './memory-env.js';
 import { getPaymentEnvVars } from './payment-env.js';
@@ -13,13 +14,16 @@ export interface DevEnv {
 /**
  * Load all dev-mode environment variables: deployed-state gateway/memory/payment env vars
  * merged with the user's .env file. Deployed-state vars go first so .env can override.
+ *
+ * @param runtime The runtime being launched. When provided, payment env vars
+ * are only injected for runtimes that can consume them (Python HTTP today).
  */
-export async function loadDevEnv(workingDir: string): Promise<DevEnv> {
+export async function loadDevEnv(workingDir: string, runtime?: AgentEnvSpec): Promise<DevEnv> {
   const configRoot = findConfigRoot(workingDir);
   const dotEnvVars = configRoot ? await readEnvFile(configRoot) : {};
   const gatewayEnvVars = await getGatewayEnvVars();
   const memoryEnvVars = await getMemoryEnvVars();
-  const paymentEnvVars = await getPaymentEnvVars();
+  const paymentEnvVars = await getPaymentEnvVars(runtime);
 
   return {
     envVars: { ...gatewayEnvVars, ...memoryEnvVars, ...paymentEnvVars, ...dotEnvVars },

src/cli/operations/dev/payment-env.ts

@@ -1,6 +1,21 @@
 import { ConfigIO } from '../../../lib/index.js';
+import type { AgentEnvSpec } from '../../../schema';
+import { isPaymentEligibleRuntime } from '../../primitives/payment-eligible.js';
+
+/**
+ * Build payment env vars for a dev runtime. Mirrors the CDK stack's deploy-time
+ * injection but reads from `deployed-state.json` (so payments only "activate"
+ * locally once the project has been deployed and state is populated).
+ *
+ * @param runtime The agent runtime spec being launched. When provided and the
+ * runtime is not eligible for payments (non-Python, non-HTTP), an empty map
+ * is returned — matches the CDK behaviour of skipping ineligible runtimes.
+ */
+export async function getPaymentEnvVars(runtime?: AgentEnvSpec): Promise<Record<string, string>> {
+  if (runtime && !isPaymentEligibleRuntime(runtime)) {
+    return {};
+  }
 
-export async function getPaymentEnvVars(): Promise<Record<string, string>> {
   const configIO = new ConfigIO();
   const envVars: Record<string, string> = {};