Merge remote-tracking branch 'upstream/main' into agent-tasks/05

# Conflicts:
#	src/__tests__/index.test.ts
#	vitest.config.ts

Author: zastrowm

.github/workflows/integration-test.yml

@@ -67,5 +67,8 @@ jobs:
       - name: Install dependencies
         run: npm install
 
+      - name: Build the package
+        run: npm run build
+
       - name: Run integration tests
         run: npm run test:integ

.github/workflows/task-implementer-agent.yml

@@ -106,7 +106,7 @@ jobs:
 
       - name: Extract issue ID from PR body
         id: extract-issue
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' || github.event_name == 'pull_request_review' || github.event_name == 'pull_request_review_comment'
         uses: actions/github-script@v7
         with:
           script: |

…-implement-aws-bedrock-model-provider.md …-implement-aws-bedrock-model-provider.md.project/tasks/task-03-implement-aws-bedrock-model-provider.md renamed to .project/tasks/completed/task-03-implement-aws-bedrock-model-provider.md .project/tasks/task-03-implement-aws-bedrock-model-provider.md renamed to .project/tasks/completed/task-03-implement-aws-bedrock-model-provider.md

@@ -17,14 +17,29 @@ This document provides guidance specifically for AI agents working on the Strand
 ```
 sdk-typescript/
 ├── src/                          # Source code (all production code)
-│   ├── __tests__/                # Unit tests (co-located with source)
-│   │   ├── hello.test.ts         # Tests for hello.ts
+│   ├── __tests__/                # Unit tests for root-level source files
+│   │   ├── errors.test.ts        # Tests for error classes
 │   │   └── index.test.ts         # Tests for main entry point
-│   ├── index.ts                  # Main SDK entry point (single export point)
-│   └── hello.ts                  # Example: Hello world function
+│   │
+│   ├── models/                   # Model provider implementations
+│   │   ├── __tests__/            # Unit tests for model providers
+│   │   │   └── bedrock.test.ts   # Tests for Bedrock model provider
+│   │   ├── bedrock.ts            # AWS Bedrock model provider
+│   │   ├── model.ts              # Base model provider interface
+│   │   └── streaming.ts          # Streaming event types
+│   │
+│   ├── tools/                    # Tool definitions and types
+│   │   └── types.ts              # Tool-related type definitions
+│   │
+│   ├── types/                    # Core type definitions
+│   │   ├── json.ts               # JSON schema and value types
+│   │   └── messages.ts           # Message and content block types
+│   │
+│   ├── errors.ts                 # Custom error classes
+│   └── index.ts                  # Main SDK entry point (single export point)
 │
 ├── tests_integ/                  # Integration tests (separate from source)
-│   └── environment.test.ts       # Environment compatibility tests
+│   └── bedrock.test.ts           # Bedrock integration tests (requires AWS credentials)
 │
 ├── .github/                      # GitHub Actions workflows
 │   ├── workflows/                # CI/CD workflows
@@ -45,7 +60,7 @@ sdk-typescript/
 │
 ├── package.json                  # Project configuration and dependencies
 ├── tsconfig.json                 # TypeScript compiler configuration
-├── vitest.config.ts              # Testing configuration
+├── vitest.config.ts              # Testing configuration (with unit/integ projects)
 ├── eslint.config.js              # Linting configuration
 ├── .prettierrc                   # Code formatting configuration
 ├── .gitignore                    # Git ignore rules
@@ -59,11 +74,16 @@ sdk-typescript/
 ### Directory Purposes
 
 - **`src/`**: All production code lives here with co-located unit tests
-- **`src/__tests__/`**: Unit tests for specific source files (tests internal functionality)
+- **`src/__tests__/`**: Unit tests for root-level source files
+- **`src/models/`**: Model provider implementations (Bedrock, future providers)
+- **`src/tools/`**: Tool definitions and types for agent tool use
+- **`src/types/`**: Core type definitions used across the SDK
 - **`tests_integ/`**: Integration tests (tests public API and external integrations)
 - **`.github/workflows/`**: CI/CD automation and quality gates
 - **`.project/`**: Task management and project tracking
 
+**IMPORTANT**: After making changes that affect the directory structure (adding new directories, moving files, or adding significant new files), you MUST update this directory structure section to reflect the current state of the repository.
+
 ## Development Workflow for Agents
 
 ### 1. Environment Setup
@@ -93,23 +113,19 @@ All checks must pass before commit is allowed.
 
 ## Coding Patterns and Best Practices
 
-### TypeScript Path Aliases
+### Import Organization
 
-Use path aliases for cleaner imports:
+Use relative imports for internal modules:
 
 ```typescript
-// Good: Use path alias
-import { hello } from '@/hello'
-import { Agent } from '@/agent'
+// Good: Relative imports for internal modules
+import { hello } from './hello'
+import { Agent } from '../agent'
 
-// Avoid: Relative paths
-import { hello } from '../hello'
-import { Agent } from '../../agent'
+// Good: External dependencies
+import { something } from 'external-package'
 ```
 
-**Configuration**: Path aliases are configured in `tsconfig.json` and `vitest.config.ts`:
-- `@/*` maps to `src/*`
-
 ### File Organization Pattern
 
 **For source files**:
@@ -133,7 +149,7 @@ Follow this nested describe pattern for consistency:
 **For functions**:
 ```typescript
 import { describe, it, expect } from 'vitest'
-import { functionName } from '@/module'
+import { functionName } from '../module'
 
 describe('functionName', () => {
   describe('when called with valid input', () => {
@@ -155,7 +171,7 @@ describe('functionName', () => {
 **For classes**:
 ```typescript
 import { describe, it, expect } from 'vitest'
-import { ClassName } from '@/module'
+import { ClassName } from '../module'
 
 describe('ClassName', () => {
   describe('methodName', () => {
@@ -274,11 +290,33 @@ export function functionName(paramName: string, optionalParam?: number): string
 }
 ```
 
+**Interface property documentation**:
+
+```typescript
+/**
+ * Interface description.
+ */
+export interface MyConfig {
+  /**
+   * Single-line description of the property.
+   */
+  propertyName: string
+
+  /**
+   * Single-line description with optional reference link.
+   * @see https://docs.example.com/property-details
+   */
+  anotherProperty?: number
+}
+```
+
 **Requirements**:
 - All exported functions, classes, and interfaces must have TSDoc
 - Include `@param` for all parameters
 - Include `@returns` for return values
 - Include `@example` for complex functionality
+- Interface properties MUST have single-line descriptions
+- Interface properties MAY include an optional `@see` link for additional details
 - TSDoc validation enforced by ESLint
 
 ### Code Style Guidelines
@@ -313,12 +351,12 @@ Organize imports in this order:
 // 1. External dependencies
 import { something } from 'external-package'
 
-// 2. Internal modules (using path aliases)
-import { Agent } from '@/agent'
-import { Tool } from '@/tools'
+// 2. Internal modules (using relative paths)
+import { Agent } from '../agent'
+import { Tool } from '../tools'
 
 // 3. Types (if separate)
-import type { Options, Config } from '@/types'
+import type { Options, Config } from '../types'
 ```
 
 ### Interface and Type Organization
@@ -519,9 +557,9 @@ it('yields expected stream events', async () => {
 
 **Example Implementation Test:**
 ```typescript
-describe('BedrockModelProvider', () => {
+describe('BedrockModel', () => {
   it('streams messages correctly', async () => {
-    const provider = new BedrockModelProvider(config)
+    const provider = new BedrockModel(config)
     const stream = provider.stream(messages)
 
     for await (const event of stream) {
@@ -536,7 +574,7 @@ describe('BedrockModelProvider', () => {
 ## Things to Do
 
 ✅ **Do**:
-- Use path aliases (`@/`) for all imports
+- Use relative imports for internal modules
 - Co-locate unit tests with source under `__tests__` directories
 - Follow nested describe pattern for test organization
 - Write explicit return types for all functions
@@ -550,7 +588,6 @@ describe('BedrockModelProvider', () => {
 
 ❌ **Don't**:
 - Use `any` type (enforced by ESLint)
-- Use relative paths like `../` when path aliases are available
 - Put unit tests in separate `tests/` directory (use `src/**/__tests__/**`)
 - Skip documentation for exported functions
 - Use semicolons (Prettier will remove them)
@@ -576,13 +613,6 @@ npm run build         # Compile TypeScript
 
 ## Troubleshooting Common Issues
 
-### Path Alias Not Resolving
-
-If `@/` imports don't work:
-1. Verify `tsconfig.json` has `baseUrl` and `paths` configured
-2. Verify `vitest.config.ts` has alias configuration
-3. Restart your IDE/editor
-
 ### Tests Not Found
 
 If tests aren't discovered:

AGENTS.md

@@ -13,6 +13,9 @@ export default [
         ecmaVersion: 2022,
         sourceType: 'module',
         project: './tsconfig.json'
+      },
+      globals: {
+        console: 'readonly'
       }
     },
     plugins: {
@@ -34,11 +37,11 @@ export default [
       parser: tsparser,
       parserOptions: {
         ecmaVersion: 2022,
-        sourceType: 'module',
-        project: './tsconfig.json'
+        sourceType: 'module'
       },
       globals: {
-        process: 'readonly'
+        process: 'readonly',
+        console: 'readonly'
       }
     },
     plugins: {

eslint.config.js

@@ -17,11 +17,12 @@
   },
   "scripts": {
     "build": "tsc",
+    "check": "npm run lint && npm run format && npm run type-check && npm run test:coverage",
     "clean": "rm -rf node_modules dist package-lock.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:integ": "vitest run tests_integ",
+    "test": "vitest run --project unit",
+    "test:watch": "vitest --project unit",
+    "test:coverage": "vitest run --coverage --project unit",
+    "test:integ": "vitest run --project integ",
     "lint": "eslint src tests_integ",
     "lint:fix": "eslint src tests_integ --fix",
     "format": "prettier --write src tests_integ",
@@ -39,6 +40,7 @@
   "author": "Strands Agents",
   "license": "Apache-2.0",
   "devDependencies": {
+    "@aws-sdk/credential-providers": "^3.913.0",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^24.6.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -61,5 +63,8 @@
   "bugs": {
     "url": "https://github.com/strands-agents/sdk-typescript/issues"
   },
-  "homepage": "https://github.com/strands-agents/sdk-typescript#readme"
+  "homepage": "https://github.com/strands-agents/sdk-typescript#readme",
+  "dependencies": {
+    "@aws-sdk/client-bedrock-runtime": "^3.911.0"
+  }
 }

package.json

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest'
+import { ContextWindowOverflowError } from '../errors'
+
+describe('ContextWindowOverflowError', () => {
+  describe('when instantiated with a message', () => {
+    it('creates an error with the correct message', () => {
+      const message = 'Context window overflow occurred'
+      const error = new ContextWindowOverflowError(message)
+
+      expect(error.message).toBe(message)
+    })
+
+    it('has the correct error name', () => {
+      const error = new ContextWindowOverflowError('test')
+
+      expect(error.name).toBe('ContextWindowOverflowError')
+    })
+
+    it('is an instance of Error', () => {
+      const error = new ContextWindowOverflowError('test')
+
+      expect(error).toBeInstanceOf(Error)
+    })
+  })
+})

src/__tests__/.gitkeep

@@ -1,7 +1,35 @@
-import { describe, it } from 'vitest'
+import { describe, it, expect } from 'vitest'
+import * as SDK from '../index'
 
-describe('index.ts', () => {
-  it('can be imported without error', async () => {
-    await import('../index')
+describe('index', () => {
+  describe('when importing from main entry point', () => {
+    it('exports error classes', () => {
+      expect(SDK.ContextWindowOverflowError).toBeDefined()
+    })
+
+    it('exports BedrockModel', () => {
+      expect(SDK.BedrockModel).toBeDefined()
+    })
+
+    it('can instantiate BedrockModel', () => {
+      const provider = new SDK.BedrockModel({ region: 'us-west-2' })
+      expect(provider).toBeInstanceOf(SDK.BedrockModel)
+      expect(provider.getConfig()).toBeDefined()
+    })
+
+    it('exports all required types', () => {
+      // This test ensures all type exports compile correctly
+      // If any exports are missing, TypeScript will error
+      const _typeCheck: {
+        // Error types
+        contextError: typeof SDK.ContextWindowOverflowError
+        // Model provider
+        provider: typeof SDK.BedrockModel
+      } = {
+        contextError: SDK.ContextWindowOverflowError,
+        provider: SDK.BedrockModel,
+      }
+      expect(_typeCheck).toBeDefined()
+    })
   })
 })

src/__tests__/errors.test.ts

@@ -0,0 +1,25 @@
+/**
+ * Error types for the Strands Agents TypeScript SDK.
+ *
+ * These error classes represent specific error conditions that can occur
+ * during agent execution and model provider interactions.
+ */
+
+/**
+ * Error thrown when input exceeds the model's context window.
+ *
+ * This error indicates that the combined length of the input (prompt, messages,
+ * system prompt, and tool definitions) exceeds the maximum context window size
+ * supported by the model.
+ */
+export class ContextWindowOverflowError extends Error {
+  /**
+   * Creates a new ContextWindowOverflowError.
+   *
+   * @param message - Error message describing the context overflow
+   */
+  constructor(message: string) {
+    super(message)
+    this.name = 'ContextWindowOverflowError'
+  }
+}