@hienlh/ppm 0.9.19 → 0.9.21

package/docs/streaming-input-guide.md

@@ -0,0 +1,267 @@
+# Streaming Input Migration Quick Reference (v0.8.55+)
+
+## What Changed?
+
+**Before (v0.8.54):** Each message triggered a new SDK query
+```
+Message 1 → SDK subprocess spawn → generate response → close
+Message 2 → SDK subprocess spawn → generate response → close
+(Slow, context resets between messages)
+```
+
+**After (v0.8.55):** Single persistent streaming session
+```
+Session created → AsyncGenerator streaming input opened
+Message 1 → Push into generator → process events
+Message 2 → Push into same generator → continue streaming
+(Fast, continuous context, no SDK restarts)
+```
+
+## Key Concepts
+
+### Session State (BE-Owned)
+The backend maintains a `SessionEntry` per chat session:
+- Tracks connected clients (can be zero if FE disconnected)
+- Maintains streaming phase (idle, connecting, thinking, streaming)
+- Buffers events for reconnection sync
+- Auto-cleans after 5 minutes of FE inactivity
+
+### Message Priority (v0.8.55+)
+```typescript
+// Send message with priority
+ws.send({
+  type: "message",
+  content: "Debug this code",
+  priority: "now"  // "now" | "next" | "later"
+})
+```
+- **"now"** — Abort current query, restart with this message
+- **"next"** — Queue after current, run next
+- **"later"** — Append to queue, run last
+
+### Event Buffering on Reconnect
+When FE WS reconnects after disconnect:
+1. BE sends `session_state` with current phase + pending approval
+2. BE sends `turn_events` with all buffered events since last connection
+3. FE rebuilds chat UI state from buffered events
+4. No message loss (unless session cleaned up after 5min)
+
+## Common Patterns
+
+### Frontend: Send Message
+```typescript
+// In useChat hook or message input handler
+ws.send(JSON.stringify({
+  type: "message",
+  content: userInput,
+  priority: "now",  // Optional
+  images: [{ id: "img1", data: "base64..." }]  // Optional
+}));
+```
+
+### Frontend: Handle Reconnection
+```typescript
+function handleReconnect() {
+  // 1. WS open fires
+  // 2. Server sends session_state
+  const sessionState = JSON.parse(msg);
+  // 3. Server sends turn_events
+  const turnEvents = JSON.parse(msg);
+
+  // 4. FE rebuilds state from buffered events
+  turnEvents.events.forEach(event => {
+    chatStore.addEvent(event);
+  });
+
+  // 5. FE is now synced with BE
+}
+```
+
+### Backend: Session Lifecycle
+```typescript
+// 1. FE connects
+open(ws) {
+  const entry = activeSessions.get(sessionId);
+  if (!entry) {
+    // Create new session entry
+    activeSessions.set(sessionId, {
+      phase: "idle",
+      clients: new Set([ws]),
+      turnEvents: []
+    });
+  } else {
+    // Reconnect: clear cleanup timer, add client
+    entry.clients.add(ws);
+  }
+}
+
+// 2. FE sends message
+message(ws, data) {
+  const parsed = JSON.parse(data);
+  if (parsed.type === "message") {
+    // Abort current if streaming, wait for cleanup
+    if (entry.phase !== "idle") {
+      entry.abort.abort();
+      await entry.streamPromise;
+    }
+    // Start new streaming loop (detached)
+    entry.streamPromise = runStreamLoop(...);
+  }
+}
+
+// 3. Streaming loop runs independently
+async function runStreamLoop() {
+  for await (const event of chatService.sendMessage(...)) {
+    bufferAndBroadcast(sessionId, event);  // To all connected clients
+  }
+  setPhase(sessionId, "idle");  // Back to idle when done
+  if (entry.clients.size === 0) {
+    startCleanupTimer(sessionId);  // 5-min cleanup
+  }
+}
+
+// 4. FE disconnects
+close(ws) {
+  entry.clients.delete(ws);
+  // Stream continues! (BE owns the connection)
+  // Timer started if no more clients
+}
+```
+
+## Phase State Machine
+
+```
+     ┌─ initializing  (setup, session resume)
+     ↓
+  idle ←→ connecting  (waiting for first SDK event, heartbeat)
+     ↑         ↓
+     │    ┌──→ thinking  (extended thinking)
+     │    ↓  ↓
+     └─── streaming  (text/tool_use content)
+          ↑     ↓
+          └─────┘ (dynamic switch)
+```
+
+**Transitions:**
+- Heartbeat: `connecting` → (5s elapsed updates) → `thinking` (when content arrives)
+- Content: `thinking` → `streaming` (first text event)
+- Dynamic: `streaming` ↔ `thinking` (based on event types)
+- Done: Any → `idle` (stream complete, ready for next message)
+
+## WebSocket Messages (v0.8.55+)
+
+### Client → Server
+```typescript
+// Send message
+{ type: "message"; content: string; priority?: string; images?: {...}[] }
+
+// Approve tool
+{ type: "approval_response"; requestId: string; approved: boolean }
+
+// Cancel current
+{ type: "cancel" }
+
+// Handshake after open
+{ type: "ready" }
+```
+
+### Server → Client
+```typescript
+// Content
+{ type: "text"; content: string }
+{ type: "thinking"; content: string }
+
+// Tool execution
+{ type: "tool_use"; tool: string; input: unknown }
+{ type: "tool_result"; output: string; isError?: boolean }
+
+// User approval request
+{ type: "approval_request"; requestId: string; tool: string; input: unknown }
+
+// Session state (sent on open/ready)
+{ type: "session_state"; sessionId: string; phase: SessionPhase; pendingApproval: {...} | null }
+
+// Buffered events (on reconnect)
+{ type: "turn_events"; events: unknown[] }
+
+// Metadata
+{ type: "account_info"; accountId: string; accountLabel: string }
+{ type: "phase_changed"; phase: SessionPhase; elapsed?: number }
+{ type: "title_updated"; title: string }
+
+// Completion
+{ type: "done"; sessionId: string; contextWindowPct?: number }
+
+// Error
+{ type: "error"; message: string }
+
+// Keepalive
+{ type: "ping" }
+```
+
+## Benefits
+
+| Aspect | Before (v0.8.54) | After (v0.8.55) |
+|--------|------------------|-----------------|
+| **SDK Restarts** | Per message | Once per session |
+| **Context** | Resets between messages | Persistent |
+| **Startup Time** | 2-5s per message | Instant follow-ups |
+| **Reconnection** | Message loss | Event buffering ensures sync |
+| **Concurrency** | N/A | Multiple clients per session |
+| **Tool Approvals** | Restarts query | Integrated in stream |
+
+## Troubleshooting
+
+### Session Cleaned Up (No Longer Exists)
+**Cause:** FE disconnected for >5 minutes
+**Solution:** Create new session, FE reconnects with new sessionId
+
+### Events Missing After Reconnect
+**Cause:** Server-side event buffer (10k event limit) overflowed
+**Solution:** Flush buffer periodically or increase limit if needed
+
+### Phase Stuck in "Connecting"
+**Cause:** SDK subprocess not responding (120s timeout)
+**Solution:** Check environment (ANTHROPIC_API_KEY, network), see error message for hints
+
+### Multiple Clients Out of Sync
+**Cause:** Broadcast failed for one client, others ahead
+**Solution:** Evicted client will reconnect and re-sync from buffered events
+
+## Debugging
+
+### Enable Logging
+```bash
+# Check server logs for session lifecycle
+[chat] session=abc123 phase → connecting
+[chat] session=abc123 first SDK event after 1250ms: type=text
+[chat] session=abc123 stream completed (45 events)
+[chat] session=abc123 phase → idle
+```
+
+### Check Session State
+```typescript
+// On WS message handler
+console.log(`Session entry:`, activeSessions.get(sessionId));
+// Outputs: { phase, clients.size, pendingApprovalEvent, turnEvents.length }
+```
+
+### Monitor Reconnections
+```typescript
+// In WS open handler
+console.log(`FE reconnected (phase=${existing.phase}, clients=${existing.clients.size})`);
+// Tells you: active streaming, how many clients connected
+```
+
+## Performance Notes
+
+- **No SDK overhead:** Persistent streaming eliminates subprocess spawn overhead
+- **Event buffering:** Clients see all events after reconnect (max 10k events per turn)
+- **Memory:** Session entries cleaned after 5min (bounded memory usage)
+- **Latency:** Follow-up messages start immediately (no SDK init)
+
+---
+
+**For detailed architecture:** See `docs/system-architecture.md` → "Chat Streaming Flow" section
+**For API types:** See `src/types/api.ts` and `src/types/chat.ts`
+**For implementation:** See `src/server/ws/chat.ts` and `src/providers/claude-agent-sdk.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.9.19",
+  "version": "0.9.21",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",