@hienlh/ppm 0.9.0-beta.2 → 0.9.0-beta.4

package/docs/system-architecture.md

@@ -205,7 +205,47 @@ interface AIProvider {
 **Implementations:**
 - **claude-agent-sdk** (Primary) — @anthropic-ai/claude-agent-sdk, streaming, tool use. Reads model/effort/maxTurns/budget/thinking from config. Settings refreshed per query. Windows CLI fallback for Bun subprocess pipe issues. .env poisoning mitigation. **Multi-account support:** Injects account API token from AccountService instead of relying on ANTHROPIC_API_KEY env var when accounts configured.
 - **mock-provider** (Testing) — Returns canned responses
-- **Note:** CLI provider removed (v2); agent SDK is sole AI provider with Windows CLI fallback
+- **cursor-cli** (CLI-based) — Spawns `cursor-agent` CLI binary with NDJSON streaming. Extends `CliProvider` base class.
+- **codex/gemini** (Planned) — Pluggable via `CliProvider` extension (~100-150 lines each)
+
+#### Multi-Provider Architecture (v0.8.61+)
+
+PPM supports multiple AI providers through a generic `AIProvider` interface and extensible base classes:
+
+**Provider Types:**
+1. **SDK-based** (claude-agent-sdk) — Uses Anthropic SDK for rich features (approvals, thinking blocks)
+2. **CLI-based** (cursor-cli, codex, gemini) — Spawns external binary with NDJSON streaming
+
+**Base Classes:**
+- `AIProvider` interface — Defines required methods (createSession, sendMessage) + optional capabilities (abortQuery, getMessages, listSessionsByDir, ensureProjectPath)
+- `CliProvider` abstract class — Shared spawn/parse/abort logic for all CLI-spawning providers
+- Provider-specific subclasses implement: `buildArgs()`, `mapEvent()`, `extractSessionId()`, `isAvailable()`
+
+**Streaming Infrastructure:**
+- `parseNdjsonLines()` utility — Async generator that buffers partial TCP packets, yields complete JSON lines
+- `ChatEvent` union type — Normalized event format across all providers (text, tool_use, thinking, approval_request, system, done, error)
+- Event mappers translate provider-specific JSON → ChatEvent (e.g., Cursor's `reasoning` type → `thinking` event)
+
+**Provider Registration & Bootstrap:**
+- `ProviderRegistry` maintains active provider instances
+- `bootstrapProviders()` async function checks `isAvailable()` on CLI providers before registering
+- Graceful fallback: if Cursor binary not found, provider skips registration (no crash, logged as info)
+- Config type `AIProviderConfig.type` union: `"agent-sdk" | "cli" | "mock"`
+
+**CLI-Provider Features:**
+- **Session capture** — Extract session ID from provider's init event, re-key process tracking
+- **Workspace trust auto-retry** — Detect trust prompts in stderr, retry once with `--trust` flag
+- **Process lifecycle** — Track active processes per session, escalate SIGTERM → SIGKILL on abort
+- **History loading** — Override `listSessions()` to read native provider history (e.g., Cursor SQLite DAG)
+- **Graceful degradation** — Missing binary → provider skipped, not fatal
+
+**New Files (v0.8.61):**
+- `src/utils/ndjson-line-parser.ts` — NDJSON streaming parser
+- `src/providers/cli-provider-base.ts` — Abstract base class for CLI providers
+- `src/providers/cursor-cli/cursor-provider.ts` — CursorCliProvider implementation
+- `src/providers/cursor-cli/cursor-event-mapper.ts` — NDJSON → ChatEvent mapping
+- `src/providers/cursor-cli/cursor-history.ts` — SQLite DAG reader for Cursor history
+- `src/web/components/chat/provider-selector.tsx` — UI component for provider selection
 
 ---
 
@@ -453,7 +493,27 @@ Returns full updated config. Validates ranges/enums before writing.
 
 ---
 
-## Chat Streaming Flow
+## Chat Streaming Flow (Persistent AsyncGenerator Sessions)
+
+### Architecture Overview (v0.8.55+)
+
+PPM uses a **persistent streaming session** model instead of per-message query execution:
+
+**Key Changes:**
+- Provider maintains **long-lived AsyncGenerator streaming input** per chat session (not per message)
+- Follow-up messages **push into the existing generator** instead of abort-and-replace
+- **Single streaming loop** per session decoupled from WebSocket message handler
+- Message priority support: `now` (interrupt current), `next` (queue first), `later` (queue at end)
+- Supports image attachments in messages
+
+**Design Benefits:**
+- Continuous context preservation — multi-turn conversations flow naturally
+- No SDK subprocess restarts between messages (faster)
+- Clean separation: BE owns Claude connection, FE disconnect doesn't abort
+- Message buffering on reconnect — clients that lose WS connection sync turn events
+- Tool approvals don't restart the query — integrated into streaming loop
+
+### Message Flow
 
 ```
 User types: "Debug this function"
@@ -462,18 +522,26 @@ MessageInput.tsx calls useChat.sendMessage()
     ↓
 useChat opens WebSocket: WS /ws/project/:name/chat/:sessionId
     ↓
-Sends: { type: "message", content: "Debug..." }
+Sends: { type: "message", content: "Debug...", priority?: "now"|"next"|"later" }
+    ↓
+WS handler in chat.ts receives message
     ↓
-Server routes to ChatService.streamMessage()
+If already streaming with different content → abort previous + wait cleanup
+If streaming, new message priority determines queue behavior:
+    • priority: "now" → abort current, restart with new content
+    • priority: "next" → push into pending queue (higher priority)
+    • priority: "later" → push to end of queue (FIFO)
+    ↓
+runStreamLoop() executes in detached async context
     ↓
 ChatService calls provider.sendMessage() (async generator)
     ↓
-Provider (Claude SDK) streams response:
-    1. Yields: { type: "text", content: "Here's what..." }
-    2. Yields: { type: "text", content: " happens..." }
-    3. Yields: { type: "tool_use", tool: "read_file", input: {...} }
+Provider (Claude SDK) yields events:
+    1. { type: "text", content: "Here's what..." }
+    2. { type: "text", content: " happens..." }
+    3. { type: "tool_use", tool: "read_file", input: {...} }
     ↓
-ChatService wraps as WebSocket messages:
+Stream loop buffers + broadcasts to all connected clients:
     { type: "text", content: "Here's what..." }
     { type: "text", content: " happens..." }
     { type: "tool_use", tool: "read_file", input: {...} }
@@ -485,15 +553,112 @@ User sees tool approval prompt, clicks "Approve"
     ↓
 Client sends: { type: "approval_response", requestId, approved: true }
     ↓
-ChatService.onToolApproval() executes tool (file_read, git commands, etc.)
+Provider continues streaming with tool result (no restart)
     ↓
-Provider continues streaming with tool result
+If multiple messages queued, next message processes after done event
     ↓
 Final response streamed, then: { type: "done", sessionId }
     ↓
-useChat closes WebSocket, saves message to store
+Phase transitions to idle, clients can send new message
+    ↓
+useChat saves message to store, displays in chat history
 ```
 
+### Session State Management
+
+**Session Entry** (BE-owned, persists across FE disconnections):
+```typescript
+interface SessionEntry {
+  providerId: string;              // Which AI provider (e.g., "claude")
+  clients: Set<ChatWsSocket>;      // Connected FE clients (may be empty)
+  abort?: AbortController;         // Current stream abort handle
+  projectPath?: string;            // Project context
+  projectName?: string;
+  pingIntervals: Map<...>;         // Per-client keepalive
+  phase: SessionPhase;             // "initializing" | "connecting" | "thinking" | "streaming" | "idle"
+  cleanupTimer?: ReturnType<...>;  // Auto-cleanup if no FE reconnects (5min)
+  pendingApprovalEvent?: {...};    // Current tool approval waiting
+  turnEvents: unknown[];           // Buffered events (for reconnect sync)
+  streamPromise?: Promise<void>;   // Track ongoing runStreamLoop
+  permissionMode?: string;         // Sticky permission mode for session
+}
+```
+
+**Client Connection States:**
+- **Active streaming + FE connected** → Events broadcast to all clients in real-time
+- **Active streaming + FE disconnected** → Events buffered in turnEvents array, BE stream continues
+- **FE reconnects** → Receive session_state + buffered turnEvents, resync with stream
+- **Idle (no query running)** → Phase is "idle", ready for next message
+- **Idle + no FE for 5min** → Cleanup timer removes session from memory
+
+### Follow-up Messages
+
+**Abort-and-Replace Pattern:**
+```typescript
+if (entry.phase !== "idle" && entry.abort) {
+  console.log(`[chat] aborting current query for new message`);
+  entry.abort.abort();
+  await entry.streamPromise;  // Wait for cleanup
+  // Re-fetch entry — may have been mutated during cleanup
+  entry = activeSessions.get(sessionId)!;
+}
+```
+
+**Multiple Message Queueing:**
+- First message: immediately starts runStreamLoop
+- Second message (while streaming): abort current, wait, start new runStreamLoop
+- Priority modes (future): could queue messages for intelligent interleaving
+
+### WebSocket Reconnection Sync
+
+```
+FE WebSocket closes (network issue, tab closes)
+    ↓
+BE keeps session alive, streaming continues
+    ↓
+FE reconnects: WS /ws/project/:name/chat/:sessionId
+    ↓
+open() handler checks activeSessions.get(sessionId)
+    ↓
+If exists (entry found):
+    1. Clear cleanup timer (FE is back)
+    2. Send session_state with current phase + pendingApproval
+    3. If phase !== "idle", send buffered turnEvents
+    4. Add WS to clients Set
+    ↓
+FE processes session_state, renders current phase
+    ↓
+FE applies buffered events to rebuild turn state
+    ↓
+FE displays: "reconnected, current phase: streaming" etc.
+```
+
+### Phase Transitions
+
+```
+idle → initializing → connecting → thinking/streaming ↔ thinking/streaming → idle
+  ^                                      ↑                                    ↓
+  └──────────────────────────────────────────────────────────────────────────┘
+```
+
+**Phase Descriptions:**
+- **idle** — No query running, ready to accept new message
+- **initializing** — Preparing (permission checks, session resume)
+- **connecting** — Waiting for first SDK event (heartbeat: "connecting" with elapsed time every 5s)
+- **thinking** — Receiving thinking content (extended thinking)
+- **streaming** — Receiving text/tool_use content (dynamic switch between thinking/streaming)
+
+### Image Attachment Support
+
+Messages can now include images:
+```typescript
+type ChatWsClientMessage =
+  | { type: "message"; content: string; images?: { id: string; data: string }[]; priority?: string }
+  | ...
+```
+
+Images are passed to provider's message context and included in tool input/output.
+
 ---
 
 ## Terminal Flow

package/package.json

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

package/src/providers/claude-agent-sdk.ts

@@ -10,6 +10,7 @@ import type {
   SessionInfo,
   ChatEvent,
   ChatMessage,
+  ModelOption,
 } from "./provider.interface.ts";
 import { configService } from "../services/config.service.ts";
 import { updateFromSdkEvent } from "../services/claude-usage.service.ts";
@@ -239,6 +240,14 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     this.forkSources.set(sessionId, sourceSessionId);
   }
 
+  async listModels(): Promise<ModelOption[]> {
+    return [
+      { value: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },
+      { value: "claude-opus-4-6", label: "Claude Opus 4.6" },
+      { value: "claude-haiku-4-5", label: "Claude Haiku 4.5" },
+    ];
+  }
+
   /**
    * Resolve a pending approval from FE (tool approval or AskUserQuestion answer).
    * Called by WS handler when client sends approval_response.

package/src/providers/cli-provider-base.ts

@@ -0,0 +1,238 @@
+import type {
+  AIProvider,
+  Session,
+  SessionConfig,
+  SessionInfo,
+  ChatEvent,
+  SendMessageOpts,
+} from "./provider.interface.ts";
+import { spawn, type ChildProcess } from "node:child_process";
+import { parseNdjsonLines } from "../utils/ndjson-line-parser.ts";
+import { configService } from "../services/config.service.ts";
+
+/**
+ * Abstract base class for CLI-spawning AI providers.
+ * Handles process lifecycle, NDJSON streaming, abort, and cleanup.
+ * Subclasses only implement event mapping + arg building.
+ */
+export abstract class CliProvider implements AIProvider {
+  abstract readonly id: string;
+  abstract readonly name: string;
+  abstract readonly cliCommand: string;
+
+  /** Build CLI args for a given message/session */
+  abstract buildArgs(params: {
+    sessionId?: string;
+    message: string;
+    model?: string;
+    permissionMode?: string;
+    isResume: boolean;
+  }): string[];
+
+  /** Map a raw JSON object from CLI stdout → ChatEvent[] */
+  abstract mapEvent(raw: unknown, sessionId: string): ChatEvent[];
+
+  /** Extract session ID from CLI init event (provider-specific) */
+  abstract extractSessionId(raw: unknown): string | null;
+
+  /** Check if CLI binary exists on this machine */
+  abstract isAvailable(): Promise<boolean>;
+
+  // --- Shared state ---
+  protected sessions = new Map<string, Session>();
+  protected activeProcesses = new Map<string, ChildProcess>();
+  private messageCount = new Map<string, number>();
+
+  // --- Session lifecycle ---
+
+  async createSession(config: SessionConfig): Promise<Session> {
+    const id = crypto.randomUUID();
+    const session: Session = {
+      id,
+      providerId: this.id,
+      title: config.title ?? "New Chat",
+      projectName: config.projectName,
+      projectPath: config.projectPath,
+      createdAt: new Date().toISOString(),
+    };
+    this.sessions.set(id, session);
+    this.messageCount.set(id, 0);
+    return session;
+  }
+
+  async resumeSession(sessionId: string): Promise<Session> {
+    const existing = this.sessions.get(sessionId);
+    if (existing) return existing;
+    const session: Session = {
+      id: sessionId,
+      providerId: this.id,
+      title: "Resumed Chat",
+      createdAt: new Date().toISOString(),
+    };
+    this.sessions.set(sessionId, session);
+    this.messageCount.set(sessionId, 1);
+    return session;
+  }
+
+  async listSessions(): Promise<SessionInfo[]> {
+    return Array.from(this.sessions.values()).map((s) => ({
+      id: s.id,
+      providerId: s.providerId,
+      title: s.title,
+      projectName: s.projectName,
+      createdAt: s.createdAt,
+    }));
+  }
+
+  async deleteSession(sessionId: string): Promise<void> {
+    this.sessions.delete(sessionId);
+    this.messageCount.delete(sessionId);
+  }
+
+  // --- Streaming ---
+
+  async *sendMessage(
+    sessionId: string,
+    message: string,
+    opts?: SendMessageOpts,
+  ): AsyncIterable<ChatEvent> {
+    if (!this.sessions.has(sessionId)) {
+      await this.resumeSession(sessionId);
+    }
+    const meta = this.sessions.get(sessionId)!;
+
+    if (meta.title === "New Chat") {
+      meta.title = message.slice(0, 50) + (message.length > 50 ? "..." : "");
+    }
+
+    const count = this.messageCount.get(sessionId) ?? 0;
+    const isResume = count > 0;
+    this.messageCount.set(sessionId, count + 1);
+
+    const config = this.getProviderConfig();
+    const args = this.buildArgs({
+      sessionId: isResume ? sessionId : undefined,
+      message,
+      model: config?.model,
+      permissionMode: opts?.permissionMode || config?.permission_mode,
+      isResume,
+    });
+
+    const cwd = meta.projectPath || process.cwd();
+    let capturedSessionId = isResume ? sessionId : null;
+
+    const proc = this.spawnProcess(args, cwd);
+    const processKey = sessionId;
+    this.activeProcesses.set(processKey, proc);
+
+    try {
+      for await (const raw of parseNdjsonLines(proc.stdout!)) {
+        if (!capturedSessionId) {
+          const extracted = this.extractSessionId(raw);
+          if (extracted) {
+            capturedSessionId = extracted;
+            if (capturedSessionId !== processKey) {
+              this.activeProcesses.delete(processKey);
+              this.activeProcesses.set(capturedSessionId, proc);
+              // Migrate session metadata to the real CLI-assigned ID
+              // so listSessions/getMessages use the correct key
+              const meta = this.sessions.get(processKey);
+              if (meta) {
+                this.sessions.delete(processKey);
+                meta.id = capturedSessionId;
+                this.sessions.set(capturedSessionId, meta);
+              }
+              const cnt = this.messageCount.get(processKey) ?? 0;
+              this.messageCount.delete(processKey);
+              this.messageCount.set(capturedSessionId, cnt);
+              // Notify frontend about the session ID change
+              yield { type: "session_migrated", oldSessionId: processKey, newSessionId: capturedSessionId } as ChatEvent;
+            }
+          }
+        }
+
+        const events = this.mapEvent(raw, capturedSessionId || sessionId);
+        for (const event of events) {
+          yield event;
+        }
+      }
+
+      const exitCode = await waitForExit(proc);
+      yield {
+        type: "done",
+        sessionId: capturedSessionId || sessionId,
+        resultSubtype: exitCode === 0 ? "success" : "error_during_execution",
+      };
+    } catch (err) {
+      yield {
+        type: "error",
+        message: err instanceof Error ? err.message : String(err),
+      };
+      yield {
+        type: "done",
+        sessionId: capturedSessionId || sessionId,
+        resultSubtype: "error_during_execution",
+      };
+    } finally {
+      this.activeProcesses.delete(capturedSessionId || processKey);
+    }
+  }
+
+  // --- Abort ---
+
+  abortQuery(sessionId: string): void {
+    const proc = this.activeProcesses.get(sessionId);
+    if (!proc) return;
+    console.log(`[${this.id}] Aborting session: ${sessionId}`);
+    proc.kill("SIGTERM");
+    setTimeout(() => {
+      try { proc.kill("SIGKILL"); } catch { /* already dead */ }
+    }, 2000);
+    this.activeProcesses.delete(sessionId);
+  }
+
+  // --- Helpers ---
+
+  protected spawnProcess(args: string[], cwd: string): ChildProcess {
+    console.log(`[${this.id}] spawn: ${this.cliCommand} ${args.join(" ")} (cwd=${cwd})`);
+    const proc = spawn(this.cliCommand, args, {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env },
+    });
+    proc.stdin?.end();
+
+    proc.stderr?.on("data", (data: Buffer) => {
+      const text = data.toString().trim();
+      if (text) console.error(`[${this.id}] stderr: ${text}`);
+    });
+
+    return proc;
+  }
+
+  /** Read provider config from PPM settings */
+  protected getProviderConfig() {
+    try {
+      const ai = configService.get("ai");
+      return ai.providers[this.id] ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Kill all active processes (cleanup on server start) */
+  cleanupAll(): void {
+    for (const [sessionId, proc] of this.activeProcesses) {
+      console.log(`[${this.id}] cleanup: killing orphaned process for session ${sessionId}`);
+      try { proc.kill("SIGTERM"); } catch { /* ignore */ }
+    }
+    this.activeProcesses.clear();
+  }
+}
+
+function waitForExit(proc: ChildProcess): Promise<number> {
+  return new Promise((resolve, reject) => {
+    proc.on("close", (code) => resolve(code ?? 1));
+    proc.on("error", (err) => reject(err));
+  });
+}

package/src/providers/cursor-cli/cursor-event-mapper.ts

@@ -0,0 +1,85 @@
+import type { ChatEvent } from "../provider.interface.ts";
+
+interface CursorRawEvent {
+  type: string;
+  subtype?: string;
+  session_id?: string;
+  model?: string;
+  message?: {
+    content?: Array<{
+      type?: string;
+      text?: string;
+      toolName?: string;
+      name?: string;
+      args?: unknown;
+      input?: unknown;
+      toolCallId?: string;
+      id?: string;
+    }>;
+  };
+  result?: string;
+}
+
+/**
+ * Map a single Cursor NDJSON line → ChatEvent[].
+ * Returns empty array for events we don't care about.
+ */
+export function mapCursorEvent(raw: unknown, sessionId: string): ChatEvent[] {
+  const event = raw as CursorRawEvent;
+  if (!event?.type) return [];
+
+  switch (event.type) {
+    case "system":
+      if (event.subtype === "init") {
+        return [{ type: "system", subtype: "init" }];
+      }
+      return [];
+
+    case "user":
+      return [];
+
+    case "assistant": {
+      const events: ChatEvent[] = [];
+      const content = event.message?.content;
+      if (!Array.isArray(content)) return [];
+
+      for (const part of content) {
+        if (!part) continue;
+
+        if (part.type === "text" && part.text) {
+          events.push({ type: "text", content: part.text });
+        }
+
+        if (part.type === "reasoning" && part.text) {
+          events.push({ type: "thinking", content: part.text });
+        }
+
+        if (part.type === "tool-call" || part.type === "tool_use") {
+          const toolName = normalizeToolName(part.toolName || part.name || "Unknown");
+          const toolId = part.toolCallId || part.id || crypto.randomUUID();
+          events.push({
+            type: "tool_use",
+            tool: toolName,
+            input: part.args || part.input || {},
+            toolUseId: toolId,
+          });
+        }
+      }
+      return events;
+    }
+
+    case "result":
+      return [];
+
+    default:
+      return [];
+  }
+}
+
+/** Normalize Cursor tool names to PPM standard */
+function normalizeToolName(name: string): string {
+  switch (name) {
+    case "ApplyPatch": return "Edit";
+    default: return name;
+  }
+}