fix(bb-agent): use Lambda execution region for S3Storage (#137)

Author: soberm

.changeset/fix-bb-agent-multi-region-s3storage.md

@@ -0,0 +1,7 @@
+---
+"@aws-blocks/bb-agent": patch
+---
+
+fix(bb-agent): use the Lambda execution region for S3Storage (#120)
+
+The deployed Agent constructed Strands' `S3Storage` without a `region`, so it defaulted to `us-east-1` and hard-pinned the snapshot S3 client there. Because the session bucket is created in the deploy region, any deployment outside `us-east-1` failed snapshot reads/writes with a cross-region 301 `PermanentRedirect`. `S3Storage` is now constructed with `region: process.env.AWS_REGION` — which the Lambda runtime always sets to the function's region — so snapshots resolve against the correct regional endpoint. `region` and `s3Client` are mutually exclusive in `S3StorageConfig`, so only `region` is passed.

packages/bb-agent/src/agent.aws.ts

@@ -2,13 +2,29 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import type { ScopeParent } from '@aws-blocks/core';
-import { AgentBase } from './agent.js';
+import type { FileBucket } from '@aws-blocks/bb-file-bucket';
+import type { SnapshotStorage } from '@strands-agents/sdk';
 import { S3Storage } from '@strands-agents/sdk/session/s3-storage';
+import type { S3StorageConfig } from '@strands-agents/sdk/session/s3-storage';
+import { AgentBase } from './agent.js';
 import type { AgentConfig, DefaultToolContext } from './types.js';
 import { BedrockModels } from './models.js';
 
+/**
+ * Builds the deployed Agent's snapshot storage, pinning S3Storage to the Lambda
+ * execution region (`AWS_REGION`) so non-us-east-1 deploys use the correct regional
+ * endpoint (#120). `S3StorageImpl` is injectable so tests can assert the resulting
+ * config without depending on S3Storage/AWS SDK internals; production uses the real one.
+ */
+export function createDeployedSnapshotStorage(
+	bucket: FileBucket,
+	S3StorageImpl: new (config: S3StorageConfig) => SnapshotStorage = S3Storage,
+): SnapshotStorage {
+	return new S3StorageImpl({ bucket: bucket.fullId, region: process.env.AWS_REGION });
+}
+
 export class Agent<TContext = DefaultToolContext> extends AgentBase<TContext> {
 	constructor(scope: ScopeParent, id: string, config: AgentConfig<TContext>) {
-		super(scope, id, config, config.model?.deployed ?? BedrockModels.BALANCED, (bucket) => new S3Storage({ bucket: bucket.fullId }));
+		super(scope, id, config, config.model?.deployed ?? BedrockModels.BALANCED, createDeployedSnapshotStorage);
 	}
 }

packages/bb-agent/src/index.test.ts

@@ -1052,3 +1052,75 @@ describe('OllamaModels presets', () => {
 		}
 	});
 });
+
+// ── deployed Agent S3Storage region (multi-region) ──────────────────────────
+// Regression for #120: the deployed (aws-runtime) Agent must build Strands' S3Storage
+// with the Lambda execution region (AWS_REGION). Omitting `region` defaults S3Storage to
+// us-east-1 and breaks deploys elsewhere — the session bucket lives in the deploy region,
+// so snapshots hit a cross-region 301 PermanentRedirect. index.test.ts otherwise only
+// drives the mock/local path, so this covers agent.aws.ts by spying the S3Storage ctor.
+
+import { Agent as DeployedAgent } from './index.aws.js';
+import { createDeployedSnapshotStorage } from './agent.aws.js';
+import type { SnapshotStorage, SnapshotManifest } from '@strands-agents/sdk';
+import type { S3StorageConfig } from '@strands-agents/sdk/session/s3-storage';
+
+describe('deployed Agent S3Storage region (multi-region)', () => {
+	// Type-safe stand-in for S3Storage that records every config it's constructed with,
+	// so we assert exactly what agent.aws.ts passes in — no S3Storage/AWS SDK internals.
+	function s3StorageSpy() {
+		const configs: S3StorageConfig[] = [];
+		class Spy implements SnapshotStorage {
+			constructor(config: S3StorageConfig) {
+				configs.push(config);
+			}
+			async saveSnapshot(): Promise<void> {}
+			async loadSnapshot(): Promise<null> {
+				return null;
+			}
+			async listSnapshotIds(): Promise<string[]> {
+				return [];
+			}
+			async deleteSession(): Promise<void> {}
+			async loadManifest(): Promise<SnapshotManifest> {
+				return { schemaVersion: '1.0', updatedAt: new Date().toISOString() };
+			}
+			async saveManifest(): Promise<void> {}
+		}
+		return { configs, Spy };
+	}
+
+	// Capture the S3StorageConfig the deployed factory builds for a given AWS_REGION.
+	function configForRegion(region: string, scopeId: string): S3StorageConfig {
+		const prev = process.env.AWS_REGION;
+		process.env.AWS_REGION = region;
+		try {
+			const { configs, Spy } = s3StorageSpy();
+			const bucket = new FileBucket(new Scope(scopeId), 'sn');
+			createDeployedSnapshotStorage(bucket, Spy);
+			assert.strictEqual(configs.length, 1, 'S3Storage should be constructed exactly once');
+			assert.strictEqual(configs[0].bucket, bucket.fullId, 'session bucket id should be passed through');
+			return configs[0];
+		} finally {
+			if (prev === undefined) delete process.env.AWS_REGION;
+			else process.env.AWS_REGION = prev;
+		}
+	}
+
+	test('constructs S3Storage with the Lambda execution region (eu-west-1)', () => {
+		const config = configForRegion('eu-west-1', 'test-s3-region-euw1');
+		assert.strictEqual(config.region, 'eu-west-1');
+		assert.notStrictEqual(config.region, 'us-east-1');
+	});
+
+	test('does not hard-pin us-east-1 when deployed to another region (ap-southeast-2)', () => {
+		const config = configForRegion('ap-southeast-2', 'test-s3-region-apse2');
+		assert.strictEqual(config.region, 'ap-southeast-2');
+		assert.notStrictEqual(config.region, 'us-east-1');
+	});
+
+	test('deployed Agent constructs on the aws-runtime path', () => {
+		const agent = new DeployedAgent(new Scope('test-s3-agent'), 'r', { systemPrompt: 'test', model: { deployed: { provider: 'canned' } } });
+		assert.ok(agent);
+	});
+});