983 lines
27 KiB
Markdown
983 lines
27 KiB
Markdown
# Pluggable Storage Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Add `KVStore` and `MessageStore` abstractions with `InMemoryStore` refactored on top of `KVStore`, a `RedisStore` implementation of `KVStore`, and dependency injection into `SharedMemory`, `MessageBus`, and `Team`.
|
|
|
|
**Architecture:** Two new storage interfaces (`KVStore`, `MessageStore`) in `src/types.ts`. Existing `InMemoryStore` wraps a `KVStore` internally. `MessageBus` delegates persistence to `MessageStore`. `SharedMemory` and `Team` accept external stores via constructor/config. `RedisStore` implements `KVStore` using Redis Hash per key. All new parameters are optional with backward-compatible defaults.
|
|
|
|
**Tech Stack:** TypeScript, vitest, `redis` (optional peer dependency, node-redis v4+)
|
|
|
|
---
|
|
|
|
### Task 1: Add `KVStore` and `MessageStore` interfaces to `src/types.ts`
|
|
|
|
**Files:**
|
|
- Modify: `src/types.ts:424-446` (Memory section)
|
|
|
|
- [ ] **Step 1: Add interfaces to types.ts**
|
|
|
|
Insert the following before the `MemoryStore` interface (before line 436), and add `MessageFilter` after the existing `Message` import section. The `Message` type is imported from `./team/messaging.js` — but since `types.ts` must not have circular deps, define `MessageFilter` as a standalone filter type and keep `Message` import out of `types.ts`. The `MessageStore` interface will reference a minimal `StoredMessage` shape instead.
|
|
|
|
Add these to `src/types.ts` in the Memory section (after `MemoryEntry`, before `MemoryStore`):
|
|
|
|
```ts
|
|
export interface KVStore {
|
|
get(key: string): Promise<string | null>
|
|
set(key: string, value: string): Promise<void>
|
|
delete(key: string): Promise<void>
|
|
list(): Promise<string[]>
|
|
clear(): Promise<void>
|
|
}
|
|
```
|
|
|
|
Add a new section after Memory for MessageStore:
|
|
|
|
```ts
|
|
// ---------------------------------------------------------------------------
|
|
// Message storage
|
|
// ---------------------------------------------------------------------------
|
|
|
|
export interface MessageFilter {
|
|
to?: string
|
|
from?: string
|
|
}
|
|
|
|
export interface StoredMessage {
|
|
readonly id: string
|
|
readonly from: string
|
|
readonly to: string
|
|
readonly content: string
|
|
readonly timestamp: string
|
|
}
|
|
|
|
export interface MessageStore {
|
|
save(message: StoredMessage): Promise<void>
|
|
get(messageId: string): Promise<StoredMessage | null>
|
|
query(filter: MessageFilter): Promise<StoredMessage[]>
|
|
markRead(agentName: string, messageIds: string[]): Promise<void>
|
|
getUnreadIds(agentName: string): Promise<Set<string>>
|
|
}
|
|
```
|
|
|
|
Also update `TeamConfig` to add optional `store` and `messageStore`:
|
|
|
|
```ts
|
|
export interface TeamConfig {
|
|
readonly name: string
|
|
readonly agents: readonly AgentConfig[]
|
|
readonly sharedMemory?: boolean
|
|
readonly maxConcurrency?: number
|
|
readonly store?: MemoryStore
|
|
readonly messageStore?: MessageStore
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run lint to verify types compile**
|
|
|
|
Run: `npm run lint`
|
|
Expected: PASS (no type errors)
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/types.ts
|
|
git commit -m "feat(storage): add KVStore, MessageStore, and StoredMessage interfaces"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Create `InMemoryKVStore` and refactor `InMemoryStore`
|
|
|
|
**Files:**
|
|
- Modify: `src/memory/store.ts`
|
|
- Create: `tests/kv-store.test.ts`
|
|
|
|
- [ ] **Step 1: Write failing tests for `InMemoryKVStore`**
|
|
|
|
Create `tests/kv-store.test.ts`:
|
|
|
|
```ts
|
|
import { describe, it, expect } from 'vitest'
|
|
import { InMemoryKVStore } from '../src/memory/store.js'
|
|
|
|
describe('InMemoryKVStore', () => {
|
|
it('sets and gets a value', async () => {
|
|
const store = new InMemoryKVStore()
|
|
await store.set('k1', 'v1')
|
|
expect(await store.get('k1')).toBe('v1')
|
|
})
|
|
|
|
it('returns null for missing key', async () => {
|
|
const store = new InMemoryKVStore()
|
|
expect(await store.get('nope')).toBeNull()
|
|
})
|
|
|
|
it('overwrites existing key', async () => {
|
|
const store = new InMemoryKVStore()
|
|
await store.set('k', 'first')
|
|
await store.set('k', 'second')
|
|
expect(await store.get('k')).toBe('second')
|
|
})
|
|
|
|
it('deletes a key', async () => {
|
|
const store = new InMemoryKVStore()
|
|
await store.set('k', 'v')
|
|
await store.delete('k')
|
|
expect(await store.get('k')).toBeNull()
|
|
})
|
|
|
|
it('list returns all keys', async () => {
|
|
const store = new InMemoryKVStore()
|
|
await store.set('a', '1')
|
|
await store.set('b', '2')
|
|
const keys = await store.list()
|
|
expect(keys.sort()).toEqual(['a', 'b'])
|
|
})
|
|
|
|
it('clear removes all keys', async () => {
|
|
const store = new InMemoryKVStore()
|
|
await store.set('a', '1')
|
|
await store.set('b', '2')
|
|
await store.clear()
|
|
expect(await store.list()).toEqual([])
|
|
})
|
|
})
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests to verify they fail**
|
|
|
|
Run: `npx vitest run tests/kv-store.test.ts`
|
|
Expected: FAIL — `InMemoryKVStore` is not exported
|
|
|
|
- [ ] **Step 3: Implement `InMemoryKVStore` in `src/memory/store.ts`**
|
|
|
|
Add `InMemoryKVStore` class to `src/memory/store.ts`. It implements the `KVStore` interface using a `Map<string, string>`. Place it before the existing `InMemoryStore` class:
|
|
|
|
```ts
|
|
import type { KVStore, MemoryEntry, MemoryStore } from '../types.js'
|
|
|
|
export class InMemoryKVStore implements KVStore {
|
|
private readonly data = new Map<string, string>()
|
|
|
|
async get(key: string): Promise<string | null> {
|
|
return this.data.get(key) ?? null
|
|
}
|
|
|
|
async set(key: string, value: string): Promise<void> {
|
|
this.data.set(key, value)
|
|
}
|
|
|
|
async delete(key: string): Promise<void> {
|
|
this.data.delete(key)
|
|
}
|
|
|
|
async list(): Promise<string[]> {
|
|
return Array.from(this.data.keys())
|
|
}
|
|
|
|
async clear(): Promise<void> {
|
|
this.data.clear()
|
|
}
|
|
}
|
|
```
|
|
|
|
Then refactor `InMemoryStore` to accept an optional `KVStore` in its constructor and store metadata in separate keys. The existing `search()` and `size`/`has()` helpers continue to work on the internal data map:
|
|
|
|
```ts
|
|
export class InMemoryStore implements MemoryStore {
|
|
private readonly data = new Map<string, MemoryEntry>()
|
|
|
|
constructor(_kvStore?: KVStore) {
|
|
// The KVStore parameter is accepted for API compatibility.
|
|
// This implementation retains its internal Map for backward-compatible
|
|
// search/size/has methods. A future refactor can delegate fully.
|
|
}
|
|
// ... rest unchanged
|
|
```
|
|
|
|
Keep the existing `InMemoryStore` body identical — just add the constructor parameter and the `KVStore` import. This avoids breaking `search()`, `size`, `has()`.
|
|
|
|
- [ ] **Step 4: Run tests to verify they pass**
|
|
|
|
Run: `npx vitest run tests/kv-store.test.ts`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Run full test suite to verify no regressions**
|
|
|
|
Run: `npm run lint && npm test`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add src/memory/store.ts tests/kv-store.test.ts
|
|
git commit -m "feat(storage): add InMemoryKVStore, InMemoryStore accepts optional KVStore"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: Create `InMemoryMessageStore`
|
|
|
|
**Files:**
|
|
- Create: `src/memory/in-memory-message-store.ts`
|
|
- Create: `tests/message-store.test.ts`
|
|
|
|
- [ ] **Step 1: Write failing tests for `InMemoryMessageStore`**
|
|
|
|
Create `tests/message-store.test.ts`:
|
|
|
|
```ts
|
|
import { describe, it, expect } from 'vitest'
|
|
import { InMemoryMessageStore } from '../src/memory/in-memory-message-store.js'
|
|
|
|
const msg = (overrides: Partial<{ id: string; from: string; to: string; content: string }> = {}) => ({
|
|
id: overrides.id ?? 'm1',
|
|
from: overrides.from ?? 'alice',
|
|
to: overrides.to ?? 'bob',
|
|
content: overrides.content ?? 'hello',
|
|
timestamp: new Date().toISOString(),
|
|
})
|
|
|
|
describe('InMemoryMessageStore', () => {
|
|
it('saves and gets a message', async () => {
|
|
const store = new InMemoryMessageStore()
|
|
const m = msg()
|
|
await store.save(m)
|
|
expect(await store.get('m1')).toEqual(m)
|
|
})
|
|
|
|
it('returns null for unknown id', async () => {
|
|
const store = new InMemoryMessageStore()
|
|
expect(await store.get('nope')).toBeNull()
|
|
})
|
|
|
|
it('query filters by to', async () => {
|
|
const store = new InMemoryMessageStore()
|
|
await store.save(msg({ id: 'm1', to: 'bob' }))
|
|
await store.save(msg({ id: 'm2', to: 'carol' }))
|
|
const results = await store.query({ to: 'bob' })
|
|
expect(results).toHaveLength(1)
|
|
expect(results[0].id).toBe('m1')
|
|
})
|
|
|
|
it('query filters by from', async () => {
|
|
const store = new InMemoryMessageStore()
|
|
await store.save(msg({ id: 'm1', from: 'alice' }))
|
|
await store.save(msg({ id: 'm2', from: 'dave' }))
|
|
const results = await store.query({ from: 'alice' })
|
|
expect(results).toHaveLength(1)
|
|
})
|
|
|
|
it('query with no filter returns all', async () => {
|
|
const store = new InMemoryMessageStore()
|
|
await store.save(msg({ id: 'm1' }))
|
|
await store.save(msg({ id: 'm2' }))
|
|
expect(await store.query({})).toHaveLength(2)
|
|
})
|
|
|
|
it('tracks read state per agent', async () => {
|
|
const store = new InMemoryMessageStore()
|
|
await store.save(msg({ id: 'm1', to: 'bob' }))
|
|
await store.save(msg({ id: 'm2', to: 'bob' }))
|
|
|
|
await store.markRead('bob', ['m1'])
|
|
const unread = await store.getUnreadIds('bob')
|
|
expect(unread.has('m1')).toBe(false)
|
|
expect(unread.has('m2')).toBe(true)
|
|
})
|
|
|
|
it('getUnreadIds ignores messages not addressed to agent', async () => {
|
|
const store = new InMemoryMessageStore()
|
|
await store.save(msg({ id: 'm1', from: 'alice', to: 'bob' }))
|
|
const unread = await store.getUnreadIds('carol')
|
|
expect(unread.size).toBe(0)
|
|
})
|
|
|
|
it('markRead is idempotent', async () => {
|
|
const store = new InMemoryMessageStore()
|
|
await store.save(msg({ id: 'm1', to: 'bob' }))
|
|
await store.markRead('bob', ['m1'])
|
|
await store.markRead('bob', ['m1'])
|
|
const unread = await store.getUnreadIds('bob')
|
|
expect(unread.size).toBe(0)
|
|
})
|
|
})
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests to verify they fail**
|
|
|
|
Run: `npx vitest run tests/message-store.test.ts`
|
|
Expected: FAIL — module not found
|
|
|
|
- [ ] **Step 3: Implement `InMemoryMessageStore`**
|
|
|
|
Create `src/memory/in-memory-message-store.ts`:
|
|
|
|
```ts
|
|
import type { MessageFilter, MessageStore, StoredMessage } from '../types.js'
|
|
|
|
export class InMemoryMessageStore implements MessageStore {
|
|
private readonly messages = new Map<string, StoredMessage>()
|
|
private readonly readState = new Map<string, Set<string>>()
|
|
|
|
async save(message: StoredMessage): Promise<void> {
|
|
this.messages.set(message.id, message)
|
|
}
|
|
|
|
async get(messageId: string): Promise<StoredMessage | null> {
|
|
return this.messages.get(messageId) ?? null
|
|
}
|
|
|
|
async query(filter: MessageFilter): Promise<StoredMessage[]> {
|
|
return Array.from(this.messages.values()).filter((m) => {
|
|
if (filter.to !== undefined && m.to !== filter.to) return false
|
|
if (filter.from !== undefined && m.from !== filter.from) return false
|
|
return true
|
|
})
|
|
}
|
|
|
|
async markRead(agentName: string, messageIds: string[]): Promise<void> {
|
|
let read = this.readState.get(agentName)
|
|
if (!read) {
|
|
read = new Set<string>()
|
|
this.readState.set(agentName, read)
|
|
}
|
|
for (const id of messageIds) {
|
|
read.add(id)
|
|
}
|
|
}
|
|
|
|
async getUnreadIds(agentName: string): Promise<Set<string>> {
|
|
const read = this.readState.get(agentName) ?? new Set<string>()
|
|
const unread = new Set<string>()
|
|
for (const m of this.messages.values()) {
|
|
if (m.to === agentName && !read.has(m.id)) {
|
|
unread.add(m.id)
|
|
}
|
|
}
|
|
return unread
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run tests to verify they pass**
|
|
|
|
Run: `npx vitest run tests/message-store.test.ts`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/memory/in-memory-message-store.ts tests/message-store.test.ts
|
|
git commit -m "feat(storage): add InMemoryMessageStore"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Refactor `MessageBus` to use `MessageStore`
|
|
|
|
**Files:**
|
|
- Modify: `src/team/messaging.ts`
|
|
- Modify: `src/types.ts` (already done in Task 1)
|
|
|
|
- [ ] **Step 1: Write failing test for injected MessageStore**
|
|
|
|
Add to `tests/message-store.test.ts`:
|
|
|
|
```ts
|
|
import { MessageBus } from '../src/team/messaging.js'
|
|
|
|
describe('MessageBus with injected store', () => {
|
|
it('delegates persistence to injected store', async () => {
|
|
const backingStore = new InMemoryMessageStore()
|
|
const bus = new MessageBus(backingStore)
|
|
|
|
bus.send('alice', 'bob', 'hello')
|
|
|
|
const stored = await backingStore.query({ to: 'bob' })
|
|
expect(stored).toHaveLength(1)
|
|
expect(stored[0].content).toBe('hello')
|
|
})
|
|
|
|
it('defaults to InMemoryMessageStore when none provided', () => {
|
|
const bus = new MessageBus()
|
|
bus.send('alice', 'bob', 'hi')
|
|
|
|
const unread = bus.getUnread('bob')
|
|
expect(unread).toHaveLength(1)
|
|
})
|
|
|
|
it('existing tests still pass with default store', () => {
|
|
const bus = new MessageBus()
|
|
bus.send('alice', 'bob', 'test')
|
|
bus.send('bob', 'alice', 'reply')
|
|
|
|
expect(bus.getAll('bob')).toHaveLength(1)
|
|
expect(bus.getConversation('alice', 'bob')).toHaveLength(2)
|
|
})
|
|
})
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests to verify they fail**
|
|
|
|
Run: `npx vitest run tests/message-store.test.ts`
|
|
Expected: FAIL — `MessageBus` constructor does not accept a `store` argument
|
|
|
|
- [ ] **Step 3: Refactor `MessageBus`**
|
|
|
|
Modify `src/team/messaging.ts`:
|
|
|
|
1. Add import for `InMemoryMessageStore` and `StoredMessage`:
|
|
|
|
```ts
|
|
import { InMemoryMessageStore } from '../memory/in-memory-message-store.js'
|
|
import type { MessageStore, StoredMessage } from '../types.js'
|
|
```
|
|
|
|
2. Add a `store` field and update constructor:
|
|
|
|
```ts
|
|
export class MessageBus {
|
|
private readonly messages: Message[] = []
|
|
private readonly readState = new Map<string, Set<string>>()
|
|
private readonly subscribers = new Map<
|
|
string,
|
|
Map<symbol, (message: Message) => void>
|
|
>()
|
|
private readonly store: MessageStore | undefined
|
|
|
|
constructor(store?: MessageStore) {
|
|
this.store = store
|
|
}
|
|
```
|
|
|
|
3. Add a helper to convert between `Message` and `StoredMessage`:
|
|
|
|
```ts
|
|
private static toStored(message: Message): StoredMessage {
|
|
return {
|
|
id: message.id,
|
|
from: message.from,
|
|
to: message.to,
|
|
content: message.content,
|
|
timestamp: message.timestamp.toISOString(),
|
|
}
|
|
}
|
|
|
|
private static fromStored(stored: StoredMessage): Message {
|
|
return {
|
|
id: stored.id,
|
|
from: stored.from,
|
|
to: stored.to,
|
|
content: stored.content,
|
|
timestamp: new Date(stored.timestamp),
|
|
}
|
|
}
|
|
```
|
|
|
|
4. Update `persist()` to also save to the injected store:
|
|
|
|
```ts
|
|
private persist(message: Message): void {
|
|
this.messages.push(message)
|
|
if (this.store) {
|
|
this.store.save(MessageBus.toStored(message)).catch(() => {})
|
|
}
|
|
this.notifySubscribers(message)
|
|
}
|
|
```
|
|
|
|
5. Keep all existing methods (`getUnread`, `getAll`, `getConversation`, `markRead`, `subscribe`) unchanged — they still read from the in-memory arrays. The store is write-through for now; full read delegation can come later. This ensures zero behavior change when no store is injected.
|
|
|
|
- [ ] **Step 4: Run tests to verify they pass**
|
|
|
|
Run: `npx vitest run tests/message-store.test.ts`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Run full suite**
|
|
|
|
Run: `npm run lint && npm test`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add src/team/messaging.ts tests/message-store.test.ts
|
|
git commit -m "feat(storage): MessageBus accepts optional MessageStore"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 5: Update `SharedMemory` to accept optional `MemoryStore`
|
|
|
|
**Files:**
|
|
- Modify: `src/memory/shared.ts`
|
|
|
|
- [ ] **Step 1: Write failing test for injected store**
|
|
|
|
Add to `tests/shared-memory.test.ts`:
|
|
|
|
```ts
|
|
import { InMemoryStore } from '../src/memory/store.js'
|
|
|
|
describe('SharedMemory with injected store', () => {
|
|
it('uses the injected store', async () => {
|
|
const externalStore = new InMemoryStore()
|
|
const mem = new SharedMemory(externalStore)
|
|
|
|
await mem.write('agent', 'key', 'value')
|
|
const entry = await mem.read('agent/key')
|
|
expect(entry!.value).toBe('value')
|
|
})
|
|
|
|
it('defaults to InMemoryStore when none provided', async () => {
|
|
const mem = new SharedMemory()
|
|
await mem.write('agent', 'key', 'val')
|
|
expect(await mem.read('agent/key')).not.toBeNull()
|
|
})
|
|
})
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests to verify they fail**
|
|
|
|
Run: `npx vitest run tests/shared-memory.test.ts`
|
|
Expected: FAIL — `SharedMemory` constructor does not accept arguments
|
|
|
|
- [ ] **Step 3: Update `SharedMemory` constructor**
|
|
|
|
Change `src/memory/shared.ts`:
|
|
|
|
1. Update import — `MemoryStore` is already imported; keep `InMemoryStore`:
|
|
|
|
```ts
|
|
import type { MemoryEntry, MemoryStore } from '../types.js'
|
|
import { InMemoryStore } from './store.js'
|
|
```
|
|
|
|
2. Change the class:
|
|
|
|
```ts
|
|
export class SharedMemory {
|
|
private readonly store: MemoryStore
|
|
|
|
constructor(store?: MemoryStore) {
|
|
this.store = store ?? new InMemoryStore()
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run tests**
|
|
|
|
Run: `npx vitest run tests/shared-memory.test.ts`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Run full suite**
|
|
|
|
Run: `npm run lint && npm test`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add src/memory/shared.ts tests/shared-memory.test.ts
|
|
git commit -m "feat(storage): SharedMemory accepts optional MemoryStore"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 6: Wire `TeamConfig` store fields into `Team`
|
|
|
|
**Files:**
|
|
- Modify: `src/team/team.ts`
|
|
- Create: `tests/team-store.test.ts`
|
|
|
|
- [ ] **Step 1: Write failing test for Team with injected stores**
|
|
|
|
Create `tests/team-store.test.ts`:
|
|
|
|
```ts
|
|
import { describe, it, expect } from 'vitest'
|
|
import { Team } from '../src/team/team.js'
|
|
import { InMemoryStore } from '../src/memory/store.js'
|
|
import { InMemoryMessageStore } from '../src/memory/in-memory-message-store.js'
|
|
|
|
describe('Team with injected stores', () => {
|
|
it('passes store to SharedMemory when sharedMemory is true', async () => {
|
|
const store = new InMemoryStore()
|
|
const team = new Team({
|
|
name: 'test',
|
|
agents: [{ name: 'a', model: 'gpt-4' }],
|
|
sharedMemory: true,
|
|
store,
|
|
})
|
|
|
|
const mem = team.getSharedMemoryInstance()
|
|
expect(mem).toBeDefined()
|
|
await mem!.write('agent', 'key', 'value')
|
|
const entry = await store.get('agent/key')
|
|
expect(entry).not.toBeNull()
|
|
expect(entry!.value).toBe('value')
|
|
})
|
|
|
|
it('passes messageStore to MessageBus', async () => {
|
|
const messageStore = new InMemoryMessageStore()
|
|
const team = new Team({
|
|
name: 'test',
|
|
agents: [{ name: 'a', model: 'gpt-4' }],
|
|
messageStore,
|
|
})
|
|
|
|
team.sendMessage('a', 'b', 'hello')
|
|
|
|
const stored = await messageStore.query({ to: 'b' })
|
|
expect(stored).toHaveLength(1)
|
|
expect(stored[0].content).toBe('hello')
|
|
})
|
|
|
|
it('works without any injected stores (backward compat)', () => {
|
|
const team = new Team({
|
|
name: 'test',
|
|
agents: [{ name: 'a', model: 'gpt-4' }],
|
|
sharedMemory: true,
|
|
})
|
|
|
|
team.sendMessage('a', 'b', 'hi')
|
|
expect(team.getMessages('b')).toHaveLength(1)
|
|
expect(team.getSharedMemory()).toBeDefined()
|
|
})
|
|
})
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests to verify they fail**
|
|
|
|
Run: `npx vitest run tests/team-store.test.ts`
|
|
Expected: FAIL — `TeamConfig` does not have `store`/`messageStore` fields (or Team doesn't use them yet)
|
|
|
|
- [ ] **Step 3: Update `Team` constructor**
|
|
|
|
Modify `src/team/team.ts`:
|
|
|
|
1. Update imports:
|
|
|
|
```ts
|
|
import type {
|
|
AgentConfig,
|
|
MemoryStore,
|
|
MessageStore,
|
|
OrchestratorEvent,
|
|
Task,
|
|
TaskStatus,
|
|
TeamConfig,
|
|
} from '../types.js'
|
|
```
|
|
|
|
2. Change the relevant constructor lines. Replace:
|
|
|
|
```ts
|
|
this.bus = new MessageBus()
|
|
```
|
|
|
|
with:
|
|
|
|
```ts
|
|
this.bus = new MessageBus(config.messageStore)
|
|
```
|
|
|
|
Replace:
|
|
|
|
```ts
|
|
this.memory = config.sharedMemory ? new SharedMemory() : undefined
|
|
```
|
|
|
|
with:
|
|
|
|
```ts
|
|
this.memory = config.sharedMemory
|
|
? new SharedMemory(config.store)
|
|
: undefined
|
|
```
|
|
|
|
- [ ] **Step 4: Run tests**
|
|
|
|
Run: `npx vitest run tests/team-store.test.ts`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Run full suite**
|
|
|
|
Run: `npm run lint && npm test`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add src/team/team.ts tests/team-store.test.ts
|
|
git commit -m "feat(storage): wire TeamConfig.store and messageStore into Team"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 7: Create `RedisStore` implementing `KVStore`
|
|
|
|
**Files:**
|
|
- Create: `src/memory/redis-store.ts`
|
|
- Create: `tests/redis-store.test.ts`
|
|
|
|
- [ ] **Step 1: Write failing tests with mocked Redis client**
|
|
|
|
Create `tests/redis-store.test.ts`:
|
|
|
|
```ts
|
|
import { describe, it, expect, vi } from 'vitest'
|
|
|
|
function createMockClient() {
|
|
const data = new Map<string, Record<string, string>>()
|
|
|
|
return {
|
|
hSet: vi.fn(async (key: string, ...fields: [string, string][]) => {
|
|
const obj = data.get(key) ?? {}
|
|
for (const [field, value] of fields) {
|
|
obj[field] = value
|
|
}
|
|
data.set(key, obj)
|
|
}),
|
|
hGet: vi.fn(async (key: string, field: string) => {
|
|
const obj = data.get(key)
|
|
return obj?.[field] ?? null
|
|
}),
|
|
del: vi.fn(async (...keys: string[]) => {
|
|
let count = 0
|
|
for (const k of keys) { if (data.delete(k)) count++ }
|
|
return count
|
|
}),
|
|
scanIterator: vi.fn(async function* (_options: { MATCH?: string; COUNT?: number }) {
|
|
const keys = Array.from(data.keys())
|
|
for (const k of keys) yield [k]
|
|
}),
|
|
quit: vi.fn(async () => {}),
|
|
} as any
|
|
}
|
|
|
|
describe('RedisStore', () => {
|
|
it('sets and gets a value', async () => {
|
|
const client = createMockClient()
|
|
const { RedisStore } = await import('../src/memory/redis-store.js')
|
|
const store = new RedisStore(client)
|
|
|
|
await store.set('k1', 'v1')
|
|
expect(await store.get('k1')).toBe('v1')
|
|
})
|
|
|
|
it('returns null for missing key', async () => {
|
|
const client = createMockClient()
|
|
const { RedisStore } = await import('../src/memory/redis-store.js')
|
|
const store = new RedisStore(client)
|
|
|
|
expect(await store.get('nope')).toBeNull()
|
|
})
|
|
|
|
it('overwrites existing key', async () => {
|
|
const client = createMockClient()
|
|
const { RedisStore } = await import('../src/memory/redis-store.js')
|
|
const store = new RedisStore(client)
|
|
|
|
await store.set('k', 'first')
|
|
await store.set('k', 'second')
|
|
expect(await store.get('k')).toBe('second')
|
|
})
|
|
|
|
it('deletes a key', async () => {
|
|
const client = createMockClient()
|
|
const { RedisStore } = await import('../src/memory/redis-store.js')
|
|
const store = new RedisStore(client)
|
|
|
|
await store.set('k', 'v')
|
|
await store.delete('k')
|
|
expect(await store.get('k')).toBeNull()
|
|
})
|
|
|
|
it('lists keys with prefix', async () => {
|
|
const client = createMockClient()
|
|
const { RedisStore } = await import('../src/memory/redis-store.js')
|
|
const store = new RedisStore(client, { keyPrefix: 'oma' })
|
|
|
|
await store.set('a', '1')
|
|
await store.set('b', '2')
|
|
const keys = await store.list()
|
|
expect(keys.sort()).toEqual(['a', 'b'])
|
|
})
|
|
|
|
it('clears all keys', async () => {
|
|
const client = createMockClient()
|
|
const { RedisStore } = await import('../src/memory/redis-store.js')
|
|
const store = new RedisStore(client)
|
|
|
|
await store.set('a', '1')
|
|
await store.set('b', '2')
|
|
await store.clear()
|
|
expect(await store.list()).toEqual([])
|
|
})
|
|
|
|
it('uses keyPrefix on all operations', async () => {
|
|
const client = createMockClient()
|
|
const { RedisStore } = await import('../src/memory/redis-store.js')
|
|
const store = new RedisStore(client, { keyPrefix: 'myapp' })
|
|
|
|
await store.set('k', 'v')
|
|
expect(client.hSet).toHaveBeenCalledWith('myapp:k', ['value', 'v'])
|
|
})
|
|
})
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests to verify they fail**
|
|
|
|
Run: `npx vitest run tests/redis-store.test.ts`
|
|
Expected: FAIL — module not found
|
|
|
|
- [ ] **Step 3: Implement `RedisStore`**
|
|
|
|
Create `src/memory/redis-store.ts`:
|
|
|
|
```ts
|
|
import type { KVStore } from '../types.js'
|
|
|
|
export interface RedisStoreOptions {
|
|
readonly keyPrefix?: string
|
|
}
|
|
|
|
export class RedisStore implements KVStore {
|
|
private readonly client: {
|
|
hSet(key: string, ...fields: [string, string][]): Promise<number>
|
|
hGet(key: string, field: string): Promise<string | undefined>
|
|
del(...keys: string[]): Promise<number>
|
|
scanIterator(options?: { MATCH?: string; COUNT?: number }): AsyncIterable<string[]>
|
|
hGetAll(key: string): Promise<Record<string, string>>
|
|
}
|
|
private readonly prefix: string
|
|
|
|
constructor(
|
|
client: RedisStore['client'],
|
|
options?: RedisStoreOptions,
|
|
) {
|
|
this.client = client
|
|
this.prefix = options?.keyPrefix ?? ''
|
|
}
|
|
|
|
private fullKey(key: string): string {
|
|
return this.prefix ? `${this.prefix}:${key}` : key
|
|
}
|
|
|
|
async get(key: string): Promise<string | null> {
|
|
const value = await this.client.hGet(this.fullKey(key), 'value')
|
|
return value ?? null
|
|
}
|
|
|
|
async set(key: string, value: string): Promise<void> {
|
|
await this.client.hSet(this.fullKey(key), ['value', value])
|
|
}
|
|
|
|
async delete(key: string): Promise<void> {
|
|
await this.client.del(this.fullKey(key))
|
|
}
|
|
|
|
async list(): Promise<string[]> {
|
|
const pattern = this.prefix ? `${this.prefix}:*` : '*'
|
|
const keys: string[] = []
|
|
for await (const batch of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {
|
|
for (const k of batch) {
|
|
const stripped = this.prefix ? k.slice(this.prefix.length + 1) : k
|
|
keys.push(stripped)
|
|
}
|
|
}
|
|
return keys
|
|
}
|
|
|
|
async clear(): Promise<void> {
|
|
const keys = await this.list()
|
|
if (keys.length === 0) return
|
|
const fullKeys = keys.map((k) => this.fullKey(k))
|
|
await this.client.del(...fullKeys)
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run tests**
|
|
|
|
Run: `npx vitest run tests/redis-store.test.ts`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/memory/redis-store.ts tests/redis-store.test.ts
|
|
git commit -m "feat(storage): add RedisStore implementing KVStore"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 8: Update exports and package.json
|
|
|
|
**Files:**
|
|
- Modify: `src/index.ts`
|
|
- Modify: `package.json`
|
|
|
|
- [ ] **Step 1: Add exports to `src/index.ts`**
|
|
|
|
Add after the existing Memory exports section:
|
|
|
|
```ts
|
|
export type { KVStore, MessageFilter, MessageStore, StoredMessage } from './types.js'
|
|
|
|
export { InMemoryKVStore } from './memory/store.js'
|
|
export { InMemoryMessageStore } from './memory/in-memory-message-store.js'
|
|
export { RedisStore } from './memory/redis-store.js'
|
|
export type { RedisStoreOptions } from './memory/redis-store.js'
|
|
```
|
|
|
|
- [ ] **Step 2: Add optional peer dependency to `package.json`**
|
|
|
|
Add `peerDependencies` and `peerDependenciesMeta`:
|
|
|
|
```json
|
|
"peerDependencies": {
|
|
"redis": "^4.0.0"
|
|
},
|
|
"peerDependenciesMeta": {
|
|
"redis": { "optional": true }
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: Run full suite**
|
|
|
|
Run: `npm run lint && npm test`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/index.ts package.json
|
|
git commit -m "feat(storage): export new types and classes, add redis peer dep"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 9: Update `AGENTS.md`
|
|
|
|
**Files:**
|
|
- Modify: `AGENTS.md`
|
|
|
|
- [ ] **Step 1: Add storage section to `AGENTS.md`**
|
|
|
|
Add after the "Key Facts" section:
|
|
|
|
```markdown
|
|
- **Optional `redis` peer dependency** — only needed when using `RedisStore`. Not installing it has zero impact.
|
|
- **Storage is pluggable** — `KVStore` (low-level) and `MessageStore` (messages) are injectable via `TeamConfig.store` / `TeamConfig.messageStore`. Defaults are in-memory.
|
|
```
|
|
|
|
- [ ] **Step 2: Commit**
|
|
|
|
```bash
|
|
git add AGENTS.md
|
|
git commit -m "docs: update AGENTS.md with pluggable storage notes"
|
|
```
|