124 lines
6.2 KiB
Markdown
124 lines
6.2 KiB
Markdown
---
|
|
phase: 22-agent-streaming
|
|
plan: 01
|
|
subsystem: api
|
|
tags: [sse, streaming, chat, drizzle, express, vitest]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 21-chat-foundation
|
|
provides: chat_messages and chat_conversations schema, chatService, chatRoutes, shared types and validators
|
|
provides:
|
|
- SSE echo-stream endpoint GET /conversations/:id/stream with token+done events
|
|
- PUT /conversations/:id/messages/:messageId edit message route
|
|
- editedContent and editedAt columns on chat_messages (migration 0048)
|
|
- editMessage and getMessageHistory service methods
|
|
- agentId field on updateConversationSchema and updateConversation service
|
|
- editMessageSchema and streamMessageSchema validators exported from @paperclipai/shared
|
|
- chat-stream-routes.test.ts with SSE header, event, and abort tests
|
|
affects: [22-02, 22-03, 23-brainstormer-flow]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: []
|
|
patterns:
|
|
- SSE headers pattern (Content-Type: text/event-stream, X-Accel-Buffering: no, flushHeaders, :ok comment)
|
|
- Echo-stream placeholder pattern for Phase 23 LLM adapter replacement
|
|
- req.on(close) abort detection to stop streaming loop
|
|
- Partial message not persisted on abort (RESEARCH.md pitfall 4)
|
|
|
|
key-files:
|
|
created:
|
|
- packages/db/src/migrations/0048_flat_stepford_cuckoos.sql
|
|
- packages/db/src/migrations/meta/0048_snapshot.json
|
|
- server/src/__tests__/chat-stream-routes.test.ts
|
|
modified:
|
|
- packages/db/src/schema/chat_messages.ts
|
|
- packages/shared/src/types/chat.ts
|
|
- packages/shared/src/validators/chat.ts
|
|
- packages/shared/src/index.ts
|
|
- server/src/services/chat.ts
|
|
- server/src/routes/chat.ts
|
|
- server/src/__tests__/chat-routes.test.ts
|
|
|
|
key-decisions:
|
|
- "Echo-stream placeholder (Phase 22): streams user's last message back word-by-word to exercise SSE pipeline; Phase 23 replaces loop body with LLM adapter calls"
|
|
- "Partial message not persisted on abort: only persist assistant message when aborted=false after loop completes"
|
|
- "getMessageHistory returns effectiveContent alias (editedContent ?? content) for LLM context window"
|
|
- "updateConversation uses spread pattern to only set defined fields, so title and agentId can be updated independently"
|
|
|
|
patterns-established:
|
|
- "SSE pattern: writeHead with 4 headers, flushHeaders(), :ok comment, req.on(close) abort flag, token events, done event with messageId"
|
|
- "Echo-stream comment block marks Phase 23 replacement point with adapter.stream(history) pattern"
|
|
|
|
requirements-completed: [CHAT-01, CHAT-08, CHAT-10, CHAT-12, PERF-02]
|
|
|
|
# Metrics
|
|
duration: 5min
|
|
completed: 2026-04-01
|
|
---
|
|
|
|
# Phase 22 Plan 01: Agent Streaming Summary
|
|
|
|
**SSE echo-stream endpoint with token/done events, edit message route, DB columns for message editing, and full server test coverage**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~5 min
|
|
- **Started:** 2026-04-01T12:47:08Z
|
|
- **Completed:** 2026-04-01T12:52:34Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 10
|
|
|
|
## Accomplishments
|
|
- Added editedContent and editedAt columns to chat_messages via Drizzle schema + migration 0048
|
|
- Implemented editMessage, getMessageHistory, and agentId-aware updateConversation in chatService
|
|
- Added editMessageSchema and streamMessageSchema validators exported from @paperclipai/shared
|
|
- Created GET /conversations/:id/stream SSE endpoint with echo-stream placeholder (Phase 23 ready)
|
|
- Created PUT /conversations/:id/messages/:messageId edit message route
|
|
- Full test coverage in both chat-routes.test.ts and new chat-stream-routes.test.ts
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: DB migration + shared types + validators + service methods** - `5db6fe7a` (feat)
|
|
2. **Task 2: SSE echo-stream endpoint + edit message route + stream tests** - `a6904bfa` (feat)
|
|
|
|
## Files Created/Modified
|
|
- `packages/db/src/schema/chat_messages.ts` - Added editedContent, editedAt columns
|
|
- `packages/db/src/migrations/0048_flat_stepford_cuckoos.sql` - Migration for new columns
|
|
- `packages/db/src/migrations/meta/0048_snapshot.json` - Drizzle migration metadata
|
|
- `packages/shared/src/types/chat.ts` - Added editedContent/editedAt to ChatMessage interface
|
|
- `packages/shared/src/validators/chat.ts` - Added editMessageSchema, streamMessageSchema, agentId to updateConversationSchema
|
|
- `packages/shared/src/index.ts` - Exported new schemas
|
|
- `server/src/services/chat.ts` - Added editMessage, getMessageHistory, updated updateConversation for agentId
|
|
- `server/src/routes/chat.ts` - Added SSE stream endpoint and edit message route
|
|
- `server/src/__tests__/chat-routes.test.ts` - Extended with agentId patch and edit message tests
|
|
- `server/src/__tests__/chat-stream-routes.test.ts` - New SSE streaming test suite
|
|
|
|
## Decisions Made
|
|
- Echo-stream placeholder pattern: streams user's last message back word-by-word so UI can be built and tested against real SSE behavior; Phase 23 replaces the echo loop with an LLM adapter call
|
|
- Partial messages NOT persisted on abort: only `addMessage` is called when `aborted=false` after the streaming loop completes
|
|
- `getMessageHistory` returns `effectiveContent` alias (`editedContent ?? content`) alongside the row data for LLM context window use in Phase 23
|
|
- `updateConversation` uses spread operator to only set fields that are explicitly provided in `data`, enabling independent title/agentId updates
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written. The TDD workflow was abbreviated (tests and implementation committed together per task rather than separate RED/GREEN commits) since the test infrastructure was already in place.
|
|
|
|
## Issues Encountered
|
|
- Second commit landed on `gsd/phase-23-brainstormer-flow` (another parallel agent had switched the main repo's HEAD branch). Cherry-picked to `gsd/phase-22-agent-streaming` immediately. Both commits confirmed on the correct branch before SUMMARY creation.
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- SSE stream endpoint ready for UI consumption (Plans 22-02, 22-03)
|
|
- Echo-stream exercises full token+done pipeline so UI can develop without LLM integration
|
|
- Phase 23 needs only to replace the echo loop body in GET /conversations/:id/stream with `adapter.stream(history)` calls
|
|
- All server tests green
|
|
|
|
---
|
|
*Phase: 22-agent-streaming*
|
|
*Completed: 2026-04-01*
|