@aws-blocks/bb-agent 0.1.0 → 0.1.2

package/README.md

@@ -96,6 +96,34 @@ Returned by `stream()`. Provides the Realtime channel and convenience methods:
 | `channel` | `Promise<RealtimeChannel>` | Realtime channel handle — `await` it, then call `.subscribe(handler)`. |
 | `complete()` | `Promise<AgentStreamChunk>` | Wait for the done chunk (full text + token usage). |
 
+### AgentStreamChunk
+
+Each chunk published to the Realtime channel has a `type` and type-specific fields:
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| `text-delta` | `text: string` | Incremental text token (in `'token'` streaming mode) or full block (in `'block'` mode). |
+| `tool-call` | `toolName: string`, `input: JSONValue` | Agent is calling a tool. |
+| `tool-result` | `toolName: string`, `text: string` | Tool returned a result. |
+| `done` | `text: string`, `usage: TokenUsage` | Agent finished. `text` contains the full response. `usage` has `{ inputTokens, outputTokens, totalTokens }`. |
+| `error` | `error: string` | Agent encountered an error. |
+| `interrupt` | `interrupts: Array<{ id, name, reason }>` | Agent paused for approval. See [Tool Approval](#tool-approval-human-in-the-loop). |
+
+### Message Roles
+
+Messages stored in conversation history use these roles:
+
+| Role | Description |
+|------|-------------|
+| `user` | User message. |
+| `assistant` | Agent response text. |
+| `tool-call` | Record of a tool invocation (stored for audit). |
+| `tool-result` | Record of a tool's return value. |
+| `approval` | User's approval/denial response to an interrupt. |
+| `interrupt` | Agent paused — snapshot of pending interrupts. |
+
+The `useChat` hook only surfaces `user`, `assistant`, and `approval` messages to the UI. Use `agent.getConversation()` directly to access the full history including tool-call/tool-result records.
+
 ### AgentConfig
 
 | Option | Type | Description |
@@ -630,7 +658,7 @@ const chat = useChat({
     resume: (chId, responses, convId) => api.resume(chId, responses, convId),
   },
   subscribe: async (channelId, handler) => {
-    const { channel } = await api.getChannel(channelId);
+    const channel = await api.getChannel(channelId);
     return channel.subscribe(handler);
   },
   onMessagesChange: (msgs) => renderMessages(msgs),

package/dist/index.test.js

@@ -716,13 +716,17 @@ describe('checkModelHealth', () => {
         assert.strictEqual(await checkModelHealth({ provider: 'canned' }, log), true);
     });
     test('bedrock foundation model found returns true', async () => {
-        const mockClient = { send: async () => ({ modelDetails: { modelId: 'anthropic.claude-3-haiku' } }) };
+        let callCount = 0;
+        const mockClient = { send: async () => {
+                callCount++;
+                if (callCount === 1)
+                    throw new Error('not an inference profile');
+                return { modelDetails: { modelId: 'anthropic.claude-3-haiku' } };
+            } };
         assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'anthropic.claude-3-haiku' }, log, mockClient), true);
     });
-    test('bedrock foundation model not found returns false', async () => {
-        const err = new Error('not found');
-        err.name = 'ValidationException';
-        const mockClient = { send: async () => { throw err; } };
+    test('bedrock model not found returns false', async () => {
+        const mockClient = { send: async () => { throw new Error('not found'); } };
         assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'bad.model' }, log, mockClient), false);
     });
     test('bedrock credential error returns false', async () => {
@@ -731,15 +735,13 @@ describe('checkModelHealth', () => {
         const mockClient = { send: async () => { throw err; } };
         assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'anthropic.claude-3-haiku' }, log, mockClient), false);
     });
-    test('bedrock cross-region inference profile found returns true', async () => {
+    test('bedrock inference profile found returns true', async () => {
         const mockClient = { send: async () => ({ inferenceProfileName: 'US Claude Sonnet' }) };
         assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'us.anthropic.claude-sonnet-4' }, log, mockClient), true);
     });
-    test('bedrock cross-region inference profile error returns false', async () => {
-        const err = new Error('access denied');
-        err.name = 'AccessDeniedException';
-        const mockClient = { send: async () => { throw err; } };
-        assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'us.anthropic.claude-sonnet-4' }, log, mockClient), false);
+    test('bedrock global inference profile found returns true', async () => {
+        const mockClient = { send: async () => ({ inferenceProfileName: 'Global Claude Opus' }) };
+        assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'global.anthropic.claude-opus-4-8-v1' }, log, mockClient), true);
     });
     test('openai-api with unreachable endpoint returns false', async () => {
         assert.strictEqual(await checkModelHealth({ provider: 'openai-api', modelId: 'gpt-4', endpoint: 'http://localhost:19999/v1' }, log), false);

package/dist/model-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-factory.d.ts","sourceRoot":"","sources":["../src/model-factory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C;;;;;;;GAOG;AACH,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IACnC,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACjC;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CA6IjI;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAkDjH"}
+{"version":3,"file":"model-factory.d.ts","sourceRoot":"","sources":["../src/model-factory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C;;;;;;;GAOG;AACH,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IACnC,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACjC;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAqHjI;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAkDjH"}

package/dist/model-factory.js

@@ -16,35 +16,24 @@ export async function checkModelHealth(config, log, _testClient) {
     }
     log.info(`Checking model health: ${config.provider}${config.modelId ? ` (${config.modelId})` : ''}`);
     if (config.provider === 'bedrock') {
-        const isCrossRegionProfile = config.modelId && /^(us-gov|us|eu|apac)\./.test(config.modelId);
-        const getClient = async () => {
-            if (_testClient)
-                return _testClient;
-            const { BedrockClient } = await import('@aws-sdk/client-bedrock');
-            return new BedrockClient({});
-        };
-        // Cross-region inference profiles use GetInferenceProfile instead of GetFoundationModel.
-        if (isCrossRegionProfile) {
-            try {
-                const client = await getClient();
-                const command = _testClient
-                    ? { inferenceProfileIdentifier: config.modelId }
-                    : new (await import('@aws-sdk/client-bedrock')).GetInferenceProfileCommand({ inferenceProfileIdentifier: config.modelId });
-                const res = await client.send(command);
-                if (res.inferenceProfileName) {
-                    log.info(`Inference profile '${config.modelId}' available`);
-                    return true;
-                }
-                return false;
-            }
-            catch (err) {
-                const e = err;
-                log.warn(`Inference profile health check failed for '${config.modelId}': ${e.name ?? e.message}`, { provider: config.provider, modelId: config.modelId });
-                return false;
+        const client = _testClient ?? new (await import('@aws-sdk/client-bedrock')).BedrockClient({});
+        // Try GetInferenceProfile first (covers cross-region and global profiles).
+        try {
+            const command = _testClient
+                ? { inferenceProfileIdentifier: config.modelId }
+                : new (await import('@aws-sdk/client-bedrock')).GetInferenceProfileCommand({ inferenceProfileIdentifier: config.modelId });
+            const res = await client.send(command);
+            if (res.inferenceProfileName) {
+                log.info(`Inference profile '${config.modelId}' available`);
+                return true;
             }
         }
+        catch (err) {
+            const e = err;
+            log.debug?.(`Not an inference profile: ${e.name ?? e.message}`, { modelId: config.modelId });
+        }
+        // Try GetFoundationModel (covers base model IDs).
         try {
-            const client = await getClient();
             const command = _testClient
                 ? { modelIdentifier: config.modelId }
                 : new (await import('@aws-sdk/client-bedrock')).GetFoundationModelCommand({ modelIdentifier: config.modelId });
@@ -53,29 +42,14 @@ export async function checkModelHealth(config, log, _testClient) {
                 log.info(`Bedrock model '${config.modelId}' exists in catalog`);
                 return true;
             }
-            return false;
         }
         catch (err) {
             const e = err;
-            // GetFoundationModel throws for unknown models (ValidationException / ResourceNotFoundException).
-            if (e.name === 'ValidationException' || e.name === 'ResourceNotFoundException') {
-                try {
-                    const client = await getClient();
-                    const listCommand = _testClient
-                        ? {}
-                        : new (await import('@aws-sdk/client-bedrock')).ListFoundationModelsCommand({});
-                    const list = await client.send(listCommand);
-                    const available = list.modelSummaries?.map((m) => m.modelId).filter(Boolean) ?? [];
-                    log.warn(`Bedrock model '${config.modelId}' not found. Available: ${available.slice(0, 10).join(', ')}${available.length > 10 ? ` (+${available.length - 10} more)` : ''}`);
-                }
-                catch {
-                    log.warn(`Bedrock model '${config.modelId}' not found. Could not list available models.`);
-                }
-                return false;
-            }
-            log.warn(`Bedrock health check failed: ${e.name ?? e.message}. Verify AWS credentials are configured.`, { provider: config.provider, modelId: config.modelId });
-            return false;
+            log.debug?.(`Not a foundation model: ${e.name ?? e.message}`, { modelId: config.modelId });
         }
+        // Both failed — model not found.
+        log.warn(`Bedrock model '${config.modelId}' not found as inference profile or foundation model. Verify the model ID and AWS credentials.`, { provider: config.provider, modelId: config.modelId });
+        return false;
     }
     if (config.provider === 'openai-api') {
         const endpoint = config.endpoint ?? 'https://api.openai.com/v1';

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "Agent";
-export declare const BB_VERSION = "0.1.0";
+export declare const BB_VERSION = "0.1.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'Agent';
-export const BB_VERSION = '0.1.0';
+export const BB_VERSION = '0.1.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/bb-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
@@ -33,12 +33,12 @@
     "test": "node --test dist/index.test.js"
   },
   "dependencies": {
-    "@aws-blocks/bb-async-job": "^0.1.0",
-    "@aws-blocks/bb-distributed-table": "^0.1.0",
-    "@aws-blocks/bb-file-bucket": "^0.1.0",
-    "@aws-blocks/bb-logger": "^0.1.0",
-    "@aws-blocks/bb-realtime": "^0.1.0",
-    "@aws-blocks/core": "^0.1.0",
+    "@aws-blocks/bb-async-job": "^0.1.1",
+    "@aws-blocks/bb-distributed-table": "^0.1.1",
+    "@aws-blocks/bb-file-bucket": "^0.1.1",
+    "@aws-blocks/bb-logger": "^0.1.1",
+    "@aws-blocks/bb-realtime": "^0.1.1",
+    "@aws-blocks/core": "^0.1.1",
     "@aws-sdk/client-bedrock": "^3.700.0",
     "@strands-agents/sdk": "~1.3.0",
     "openai": "^6.7.0",

package/src/index.test.ts

@@ -844,13 +844,17 @@ describe('checkModelHealth', () => {
 	});
 
 	test('bedrock foundation model found returns true', async () => {
-		const mockClient = { send: async () => ({ modelDetails: { modelId: 'anthropic.claude-3-haiku' } }) };
+		let callCount = 0;
+		const mockClient = { send: async () => {
+			callCount++;
+			if (callCount === 1) throw new Error('not an inference profile');
+			return { modelDetails: { modelId: 'anthropic.claude-3-haiku' } };
+		} };
 		assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'anthropic.claude-3-haiku' }, log, mockClient), true);
 	});
 
-	test('bedrock foundation model not found returns false', async () => {
-		const err = new Error('not found'); err.name = 'ValidationException';
-		const mockClient = { send: async () => { throw err; } };
+	test('bedrock model not found returns false', async () => {
+		const mockClient = { send: async () => { throw new Error('not found'); } };
 		assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'bad.model' }, log, mockClient), false);
 	});
 
@@ -860,15 +864,14 @@ describe('checkModelHealth', () => {
 		assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'anthropic.claude-3-haiku' }, log, mockClient), false);
 	});
 
-	test('bedrock cross-region inference profile found returns true', async () => {
+	test('bedrock inference profile found returns true', async () => {
 		const mockClient = { send: async () => ({ inferenceProfileName: 'US Claude Sonnet' }) };
 		assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'us.anthropic.claude-sonnet-4' }, log, mockClient), true);
 	});
 
-	test('bedrock cross-region inference profile error returns false', async () => {
-		const err = new Error('access denied'); err.name = 'AccessDeniedException';
-		const mockClient = { send: async () => { throw err; } };
-		assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'us.anthropic.claude-sonnet-4' }, log, mockClient), false);
+	test('bedrock global inference profile found returns true', async () => {
+		const mockClient = { send: async () => ({ inferenceProfileName: 'Global Claude Opus' }) };
+		assert.strictEqual(await checkModelHealth({ provider: 'bedrock', modelId: 'global.anthropic.claude-opus-4-8-v1' }, log, mockClient), true);
 	});
 
 	test('openai-api with unreachable endpoint returns false', async () => {

package/src/model-factory.ts

@@ -36,36 +36,25 @@ export async function checkModelHealth(config: ModelConfig, log: ChildLogger, _t
 	}
 	log.info(`Checking model health: ${config.provider}${config.modelId ? ` (${config.modelId})` : ''}`);
 	if (config.provider === 'bedrock') {
-		const isCrossRegionProfile = config.modelId && /^(us-gov|us|eu|apac)\./.test(config.modelId);
-
-		const getClient = async (): Promise<BedrockHealthClient> => {
-			if (_testClient) return _testClient;
-			const { BedrockClient } = await import('@aws-sdk/client-bedrock');
-			return new BedrockClient({});
-		};
-
-		// Cross-region inference profiles use GetInferenceProfile instead of GetFoundationModel.
-		if (isCrossRegionProfile) {
-			try {
-				const client = await getClient();
-				const command = _testClient
-					? { inferenceProfileIdentifier: config.modelId }
-					: new (await import('@aws-sdk/client-bedrock')).GetInferenceProfileCommand({ inferenceProfileIdentifier: config.modelId });
-				const res = await client.send(command);
-				if (res.inferenceProfileName) {
-					log.info(`Inference profile '${config.modelId}' available`);
-					return true;
-				}
-				return false;
-			} catch (err: unknown) {
-				const e = err as { name?: string; message?: string };
-				log.warn(`Inference profile health check failed for '${config.modelId}': ${e.name ?? e.message}`, { provider: config.provider, modelId: config.modelId });
-				return false;
+		const client: BedrockHealthClient = _testClient ?? new (await import('@aws-sdk/client-bedrock')).BedrockClient({});
+
+		// Try GetInferenceProfile first (covers cross-region and global profiles).
+		try {
+			const command = _testClient
+				? { inferenceProfileIdentifier: config.modelId }
+				: new (await import('@aws-sdk/client-bedrock')).GetInferenceProfileCommand({ inferenceProfileIdentifier: config.modelId });
+			const res = await client.send(command);
+			if (res.inferenceProfileName) {
+				log.info(`Inference profile '${config.modelId}' available`);
+				return true;
 			}
+		} catch (err: unknown) {
+			const e = err as { name?: string; message?: string };
+			log.debug?.(`Not an inference profile: ${e.name ?? e.message}`, { modelId: config.modelId });
 		}
 
+		// Try GetFoundationModel (covers base model IDs).
 		try {
-			const client = await getClient();
 			const command = _testClient
 				? { modelIdentifier: config.modelId }
 				: new (await import('@aws-sdk/client-bedrock')).GetFoundationModelCommand({ modelIdentifier: config.modelId });
@@ -74,27 +63,14 @@ export async function checkModelHealth(config: ModelConfig, log: ChildLogger, _t
 				log.info(`Bedrock model '${config.modelId}' exists in catalog`);
 				return true;
 			}
-			return false;
 		} catch (err: unknown) {
 			const e = err as { name?: string; message?: string };
-			// GetFoundationModel throws for unknown models (ValidationException / ResourceNotFoundException).
-			if (e.name === 'ValidationException' || e.name === 'ResourceNotFoundException') {
-				try {
-					const client = await getClient();
-					const listCommand = _testClient
-						? {}
-						: new (await import('@aws-sdk/client-bedrock')).ListFoundationModelsCommand({});
-					const list = await client.send(listCommand);
-					const available = list.modelSummaries?.map((m: { modelId?: string }) => m.modelId).filter(Boolean) ?? [];
-					log.warn(`Bedrock model '${config.modelId}' not found. Available: ${available.slice(0, 10).join(', ')}${available.length > 10 ? ` (+${available.length - 10} more)` : ''}`);
-				} catch {
-					log.warn(`Bedrock model '${config.modelId}' not found. Could not list available models.`);
-				}
-				return false;
-			}
-			log.warn(`Bedrock health check failed: ${e.name ?? e.message}. Verify AWS credentials are configured.`, { provider: config.provider, modelId: config.modelId });
-			return false;
+			log.debug?.(`Not a foundation model: ${e.name ?? e.message}`, { modelId: config.modelId });
 		}
+
+		// Both failed — model not found.
+		log.warn(`Bedrock model '${config.modelId}' not found as inference profile or foundation model. Verify the model ID and AWS credentials.`, { provider: config.provider, modelId: config.modelId });
+		return false;
 	}
 
 	if (config.provider === 'openai-api') {

package/src/version.ts

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'Agent';
-export const BB_VERSION = '0.1.0';
+export const BB_VERSION = '0.1.2';