Task 05: Create Tool Interface Implementation (#20)

Implement the core Tool interface (and FunctionTool implementation) and related types. The Tool interface provides a streaming execution pattern that allows tools to yield progress events during execution before returning a final result.

---------

Co-authored-by: Strands Agent <217235299+strands-agent@users.noreply.github.com>
Co-authored-by: Mackenzie Zastrow <zastrowm@users.noreply.github.com>

Author: zastrowm

.node-version

@@ -0,0 +1 @@
+20.19.0

…t/tasks/task-05-create-tool-interface.md …mpleted/task-05-create-tool-interface.md.project/tasks/task-05-create-tool-interface.md renamed to .project/tasks/completed/task-05-create-tool-interface.md .project/tasks/task-05-create-tool-interface.md renamed to .project/tasks/completed/task-05-create-tool-interface.md

@@ -232,6 +232,41 @@ export function getData(): any {
 - Use TypeScript strict mode features
 - Leverage type inference where appropriate
 
+### Class Field Naming Conventions
+
+**Private fields**: Use underscore prefix for private class fields to improve readability and distinguish them from public members.
+
+```typescript
+// ✅ Good: Private fields with underscore prefix
+export class Example {
+  private readonly _config: Config
+  private _state: State
+
+  constructor(config: Config) {
+    this._config = config
+    this._state = { initialized: false }
+  }
+
+  public getConfig(): Config {
+    return this._config
+  }
+}
+
+// ❌ Bad: No underscore for private fields
+export class Example {
+  private readonly config: Config  // Missing underscore
+
+  constructor(config: Config) {
+    this.config = config
+  }
+}
+```
+
+**Rules**:
+- Private fields MUST use underscore prefix (e.g., `_field`)
+- Public fields MUST NOT use underscore prefix
+- This convention improves code readability and makes the distinction between public and private members immediately visible
+
 ### Documentation Requirements
 
 **TSDoc format** (required for all exported functions):
@@ -457,6 +492,63 @@ describe('calculateTotal', () => {
 })
 ```
 
+### Object Assertion Best Practices
+
+**Prefer testing entire objects at once** instead of individual properties for better readability and test coverage.
+
+```typescript
+// ✅ Good: Verify entire object at once
+it('returns expected user object', () => {
+  const user = getUser('123')
+  expect(user).toEqual({
+    id: '123',
+    name: 'John Doe',
+    email: 'john@example.com',
+    isActive: true
+  })
+})
+
+// ✅ Good: Verify entire array of objects
+it('yields expected stream events', async () => {
+  const events = await collectEvents(stream)
+  expect(events).toEqual([
+    { type: 'streamEvent', data: 'Starting...' },
+    { type: 'streamEvent', data: 'Processing...' },
+    { type: 'streamEvent', data: 'Complete!' },
+  ])
+})
+
+// ❌ Bad: Testing individual properties
+it('returns expected user object', () => {
+  const user = getUser('123')
+  expect(user).toBeDefined()
+  expect(user.id).toBe('123')
+  expect(user.name).toBe('John Doe')
+  expect(user.email).toBe('john@example.com')
+  expect(user.isActive).toBe(true)
+})
+
+// ❌ Bad: Testing array elements individually in a loop
+it('yields expected stream events', async () => {
+  const events = await collectEvents(stream)
+  for (const event of events) {
+    expect(event.type).toBe('streamEvent')
+    expect(event).toHaveProperty('data')
+  }
+})
+```
+
+**Benefits of testing entire objects**:
+- **More concise**: Single assertion instead of multiple
+- **Better test coverage**: Catches unexpected additional or missing properties
+- **More readable**: Clear expectation of the entire structure
+- **Easier to maintain**: Changes to the object require updating one place
+
+**Use cases**:
+- Always use `toEqual()` for object and array comparisons
+- Use `toBe()` only for primitive values and reference equality
+- When testing error objects, verify the entire structure including message and type
+
 ### Testing Guidelines
 
 **Testing Approach:**

AGENTS.md

@@ -17,6 +17,7 @@
   },
   "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 --project unit",
     "test:watch": "vitest --project unit",

package.json

@@ -35,6 +35,12 @@ export type {
   ToolChoice,
 } from './tools/types'
 
+// Tool interface and related types
+export type { Tool, ToolContext, ToolStreamEvent, ToolStreamGenerator } from './tools/tool'
+
+// FunctionTool implementation
+export { FunctionTool } from './tools/function-tool'
+
 // Streaming event types
 export type {
   Usage,