fix(payments): gate auto-wiring to Strands runtimes

aidandaly24 · aidandaly24 · commit 7db4a902fd7f · 2026-05-21T15:38:19.000Z
wirePaymentCapability used to drop a Strands-shaped payments.py and
regex-rewrite main.py for every runtime, regardless of framework. On
LangGraph, GoogleADK, OpenAIAgents, and AutoGen templates the regex
either no-ops or corrupts the agent's Agent() constructor (none of
them accept plugins=). Detect the framework by import signature on
main.py and skip non-Strands runtimes cleanly. Surface a warning on
the add success path listing the skipped runtime names so the user
knows payments must be wired manually for those frameworks.

- PaymentManagerPrimitive.add: collect skippedRuntimes, return in result.
- wirePaymentCapability: read main.py first; bail before any fs writes
  if "from strands import" is absent.
- CLI add: warn when skippedRuntimes is non-empty.
- Tests: 6 new cases for non-Strands gating + missing main.py;
  existing fixtures updated to include the strands import where the
  intent was the Strands wiring path.
diff --git a/src/cli/primitives/PaymentManagerPrimitive.ts b/src/cli/primitives/PaymentManagerPrimitive.ts
@@ -47,7 +47,9 @@ export class PaymentManagerPrimitive extends BasePrimitive<AddPaymentManagerOpti
   readonly label = 'Payment Manager';
   readonly primitiveSchema = PaymentManagerSchema;
 
-  async add(options: AddPaymentManagerOptions): Promise<AddResult<{ managerName: string }>> {
+  async add(
+    options: AddPaymentManagerOptions
+  ): Promise<AddResult<{ managerName: string; skippedRuntimes?: string[] }>> {
     try {
       const project = await this.readProjectSpec();
 
@@ -84,15 +86,24 @@ export class PaymentManagerPrimitive extends BasePrimitive<AddPaymentManagerOpti
 
       await this.writeProjectSpec(project);
 
-      // Wire payment capability into all agents
+      // Wire payment capability into all agents.
+      // Only Strands runtimes get the auto-wiring today; other frameworks
+      // (LangChain/LangGraph, GoogleADK, OpenAIAgents, VercelAI) do not have
+      // a payments capability shim yet and would have their main.py corrupted
+      // by the Strands-shaped template. Non-Strands runtimes are skipped with
+      // a warning so the user knows they need to wire payments manually.
       const configRoot = findConfigRoot();
+      const skippedRuntimes: string[] = [];
       if (configRoot) {
         for (const runtime of project.runtimes) {
-          this.wirePaymentCapability(configRoot, runtime.codeLocation);
+          const wired = this.wirePaymentCapability(configRoot, runtime.codeLocation);
+          if (!wired) {
+            skippedRuntimes.push(runtime.name);
+          }
         }
       }
 
-      return { success: true, managerName: options.name };
+      return { success: true, managerName: options.name, skippedRuntimes };
     } catch (err) {
       return { success: false, error: toError(err) };
     }
@@ -359,7 +370,16 @@ export class PaymentManagerPrimitive extends BasePrimitive<AddPaymentManagerOpti
                 console.log(JSON.stringify(serializeResult(result)));
               } else if (result.success) {
                 console.log(`Added payment manager '${result.managerName}'`);
-                console.log(`\nPayment capability code has been added to your agent(s).`);
+                if (result.skippedRuntimes && result.skippedRuntimes.length > 0) {
+                  console.warn(
+                    `\nWarning: payment capability auto-wiring skipped for non-Strands runtime(s): ${result.skippedRuntimes.join(', ')}.`
+                  );
+                  console.warn(
+                    `Payments are only auto-wired into Strands agents today. You will need to wire payment plugins manually for these runtimes.`
+                  );
+                } else {
+                  console.log(`\nPayment capability code has been added to your agent(s).`);
+                }
                 console.log(
                   `Add a payment connector with \`agentcore add payment-connector --manager ${result.managerName}\``
                 );
@@ -482,28 +502,38 @@ export class PaymentManagerPrimitive extends BasePrimitive<AddPaymentManagerOpti
    * handled by the Handlebars template for new agents. For existing agents,
    * the user must manually update their entrypoint to use the factory pattern.
    */
-  private wirePaymentCapability(configRoot: string, codeLocation: string): void {
+  private wirePaymentCapability(configRoot: string, codeLocation: string): boolean {
     const projectRoot = dirname(configRoot);
     const agentDir = resolve(projectRoot, codeLocation);
     const capDir = join(agentDir, 'capabilities', 'payments');
 
-    if (existsSync(join(capDir, 'payments.py'))) return;
+    if (existsSync(join(capDir, 'payments.py'))) return true;
+
+    const mainPath = join(agentDir, 'main.py');
+    if (!existsSync(mainPath)) return false;
+
+    const main = readFileSync(mainPath, 'utf-8');
+
+    // Only Strands templates have a payments capability shim today. The
+    // shim's plugin pattern (Agent(plugins=[...])) is Strands-specific and
+    // would not work for LangChain/LangGraph, GoogleADK, OpenAIAgents, etc.
+    // Detect by import signature — the unrendered Handlebars template still
+    // contains "from strands import" so this works pre- and post-render.
+    const isStrandsAgent = /^from strands(\.|\s)/m.test(main) || main.includes('from strands import');
+    if (!isStrandsAgent) {
+      return false;
+    }
 
     const templateDir = getTemplatePath('python', 'http', 'strands', 'capabilities', 'payments');
-    if (!existsSync(templateDir)) return;
+    if (!existsSync(templateDir)) return false;
 
     mkdirSync(capDir, { recursive: true });
     copyFileSync(join(templateDir, 'payments.py'), join(capDir, 'payments.py'));
     const initPath = join(capDir, '__init__.py');
     if (!existsSync(initPath)) writeFileSync(initPath, '');
     const parentInit = join(agentDir, 'capabilities', '__init__.py');
     if (!existsSync(parentInit)) writeFileSync(parentInit, '');
-
-    const mainPath = join(agentDir, 'main.py');
-    if (!existsSync(mainPath)) return;
-
-    const main = readFileSync(mainPath, 'utf-8');
-    if (main.includes('create_payments_plugin')) return;
+    if (main.includes('create_payments_plugin')) return true;
 
     const importLine = 'from capabilities.payments.payments import create_payments_plugin, PAYMENT_SYSTEM_PROMPT';
 
@@ -568,5 +598,6 @@ export class PaymentManagerPrimitive extends BasePrimitive<AddPaymentManagerOpti
     }
 
     writeFileSync(mainPath, patched);
+    return true;
   }
 }
diff --git a/src/cli/primitives/__tests__/wirePaymentCapability.test.ts b/src/cli/primitives/__tests__/wirePaymentCapability.test.ts
@@ -294,7 +294,7 @@ describe('wirePaymentCapability (via PaymentManagerPrimitive.add)', () => {
   // Test 3 – Minimal agent: no known pattern
   // =========================================================================
   describe('minimal agent with neither get_or_create_agent nor Agent() pattern', () => {
-    const minimalMain = ['def h(e, c): pass'].join('\n');
+    const minimalMain = ['from strands import Agent', '', 'def h(e, c): pass'].join('\n');
 
     beforeEach(() => {
       mockExistsSync.mockImplementation((p: string) => {
@@ -418,10 +418,13 @@ describe('wirePaymentCapability (via PaymentManagerPrimitive.add)', () => {
       mockExistsSync.mockImplementation((p: string) => {
         if (p === TEMPLATE_DIR) return true;
         if (p === PAYMENTS_PY_DEST) return false;
-        if (p === MAIN_PY) return false; // no main.py → skip patching
+        if (p === MAIN_PY) return true;
         return false;
       });
-      mockReadFileSync.mockReturnValue('');
+      // Strands main.py — passes the framework gate; pattern doesn't match
+      // either get_or_create or Agent() so file write is skipped, but cap dir
+      // setup still runs.
+      mockReadFileSync.mockReturnValue('from strands import Agent\n\ndef h(e, c): pass\n');
     });
 
     it('creates capabilities/payments/ directory with recursive flag', async () => {
@@ -458,9 +461,11 @@ describe('wirePaymentCapability (via PaymentManagerPrimitive.add)', () => {
       mockExistsSync.mockImplementation((p: string) => {
         if (p === TEMPLATE_DIR) return true;
         if (p === PAYMENTS_PY_DEST) return false;
-        if (p === MAIN_PY) return false;
+        if (p === MAIN_PY) return true;
         return false; // init files absent
       });
+      // Strands main.py to pass the framework gate
+      mockReadFileSync.mockReturnValue('from strands import Agent\n\ndef h(e, c): pass\n');
     });
 
     it('creates capabilities/payments/__init__.py when absent', async () => {
@@ -479,11 +484,12 @@ describe('wirePaymentCapability (via PaymentManagerPrimitive.add)', () => {
       mockExistsSync.mockImplementation((p: string) => {
         if (p === TEMPLATE_DIR) return true;
         if (p === PAYMENTS_PY_DEST) return false;
-        if (p === MAIN_PY) return false;
+        if (p === MAIN_PY) return true;
         if (p === CAP_INIT) return true; // already exists
         if (p === PARENT_INIT) return true; // already exists
         return false;
       });
+      mockReadFileSync.mockReturnValue('from strands import Agent\n\ndef h(e, c): pass\n');
 
       await callAdd(primitive, makeProject(CODE_LOCATION));
 
@@ -539,24 +545,141 @@ describe('wirePaymentCapability (via PaymentManagerPrimitive.add)', () => {
       expect(between).toBe('\n');
     });
 
-    it('prepends import at top of file when there are no existing imports', async () => {
-      const noImports = ['def handler(event, context):', '    return {}'].join('\n');
+    // Note: the "no existing imports" case is no longer reachable since
+    // wirePaymentCapability requires `from strands import` to detect the
+    // framework before wiring. A main.py with zero imports cannot be a
+    // Strands template and is correctly skipped by the framework gate
+    // (covered by the framework-gate tests below).
+  });
+
+  // =========================================================================
+  // Test 8 – Framework gate: skip non-Strands runtimes
+  // =========================================================================
+  describe('framework gate (non-Strands runtimes)', () => {
+    /**
+     * Each fixture is a snippet from one of the templates we ship. The
+     * shared expectation is the same for all: when main.py is NOT a Strands
+     * agent, wirePaymentCapability must NOT touch the filesystem at all
+     * (no cap dir, no payments.py copy, no main.py rewrite). The success
+     * result still returns true and lists the runtime name in skippedRuntimes.
+     */
+    const fixtures: { framework: string; main: string }[] = [
+      {
+        framework: 'LangChain_LangGraph',
+        main: [
+          'import os',
+          'from langchain_core.messages import HumanMessage',
+          'from langgraph.prebuilt import create_react_agent',
+          'from bedrock_agentcore.runtime import BedrockAgentCoreApp',
+          '',
+          'app = BedrockAgentCoreApp()',
+          '',
+          '@app.entrypoint',
+          'async def invoke(payload, context):',
+          '    pass',
+        ].join('\n'),
+      },
+      {
+        framework: 'GoogleADK',
+        main: [
+          'import os',
+          'from google.adk.agents import Agent',
+          'from google.adk.runners import Runner',
+          'from bedrock_agentcore.runtime import BedrockAgentCoreApp',
+          '',
+          'app = BedrockAgentCoreApp()',
+        ].join('\n'),
+      },
+      {
+        framework: 'OpenAIAgents',
+        main: [
+          'import os',
+          'from agents import Agent, Runner',
+          'from bedrock_agentcore.runtime import BedrockAgentCoreApp',
+          '',
+          'app = BedrockAgentCoreApp()',
+        ].join('\n'),
+      },
+      {
+        framework: 'AutoGen',
+        main: [
+          'import os',
+          'from autogen_agentchat.agents import AssistantAgent',
+          'from bedrock_agentcore.runtime import BedrockAgentCoreApp',
+          '',
+          'app = BedrockAgentCoreApp()',
+        ].join('\n'),
+      },
+    ];
+
+    for (const fixture of fixtures) {
+      it(`does not wire payments into ${fixture.framework} main.py`, async () => {
+        mockExistsSync.mockImplementation((p: string) => {
+          if (p === TEMPLATE_DIR) return true;
+          if (p === PAYMENTS_PY_DEST) return false;
+          if (p === MAIN_PY) return true;
+          return false;
+        });
+        mockReadFileSync.mockReturnValue(fixture.main);
+
+        const result = await callAdd(primitive, makeProject(CODE_LOCATION));
+
+        // add() still succeeds — the manager goes into agentcore.json
+        expect(result.success).toBe(true);
+
+        // No filesystem mutations to the agent's source tree
+        expect(mockMkdirSync).not.toHaveBeenCalled();
+        expect(mockCopyFileSync).not.toHaveBeenCalled();
+        const mainPyWrite = mockWriteFileSync.mock.calls.find((c: unknown[]) => (c[0] as string) === MAIN_PY);
+        expect(mainPyWrite).toBeUndefined();
+        const capInitWrite = mockWriteFileSync.mock.calls.find(
+          (c: unknown[]) => (c[0] as string) === CAP_INIT || (c[0] as string) === PARENT_INIT
+        );
+        expect(capInitWrite).toBeUndefined();
+
+        // Runtime name surfaced for the CLI to warn the user
+        if (result.success) {
+          expect(result.skippedRuntimes).toContain('my-agent');
+        }
+      });
+    }
 
+    it('skips wiring when main.py is missing entirely (cannot detect framework)', async () => {
       mockExistsSync.mockImplementation((p: string) => {
         if (p === TEMPLATE_DIR) return true;
         if (p === PAYMENTS_PY_DEST) return false;
-        if (p === MAIN_PY) return true;
+        if (p === MAIN_PY) return false;
         return false;
       });
-      mockReadFileSync.mockReturnValue(noImports);
 
-      await callAdd(primitive, makeProject(CODE_LOCATION));
+      const result = await callAdd(primitive, makeProject(CODE_LOCATION));
 
-      const written: string = mockWriteFileSync.mock.calls.find(
-        (c: unknown[]) => (c[0] as string) === MAIN_PY
-      )![1] as string;
+      expect(result.success).toBe(true);
+      expect(mockMkdirSync).not.toHaveBeenCalled();
+      expect(mockCopyFileSync).not.toHaveBeenCalled();
+      if (result.success) {
+        expect(result.skippedRuntimes).toContain('my-agent');
+      }
+    });
 
-      expect(written.startsWith('from capabilities.payments.payments import create_payments_plugin')).toBe(true);
+    it('still wires when "from strands" appears in a Strands-typed main.py', async () => {
+      const strandsMain = ['from strands import Agent', '', '@app.entrypoint', 'def h(p, c):', '    pass'].join('\n');
+      mockExistsSync.mockImplementation((p: string) => {
+        if (p === TEMPLATE_DIR) return true;
+        if (p === PAYMENTS_PY_DEST) return false;
+        if (p === MAIN_PY) return true;
+        return false;
+      });
+      mockReadFileSync.mockReturnValue(strandsMain);
+
+      const result = await callAdd(primitive, makeProject(CODE_LOCATION));
+
+      expect(result.success).toBe(true);
+      expect(mockMkdirSync).toHaveBeenCalledWith(CAP_DIR, { recursive: true });
+      expect(mockCopyFileSync).toHaveBeenCalledWith(PAYMENTS_PY_SRC, PAYMENTS_PY_DEST);
+      if (result.success) {
+        expect(result.skippedRuntimes).toEqual([]);
+      }
     });
   });
 });
