feat: stream AI responses

Co-authored-by: devmap-agent <238585242+devmap-agent@users.noreply.github.com>

Author: itsflaid

PRD.md

@@ -379,6 +379,8 @@ Question
 - Prefer 3–5 most relevant files
 - Include related files in output
 - Keep technical labels readable and consistent
+- Stream human-readable AI responses progressively
+- Keep `--json` buffered so stdout remains exactly one valid JSON document
 
 ---
 
@@ -454,6 +456,7 @@ JSON mode rules:
 - no ANSI colors, Markdown rendering, box drawing, or progress text
 - runtime errors use a stable `{ "status": "error", "error": "...", "hint": "..." }` shape
 - `init --json` is non-interactive and requires `GROQ_API_KEY` or existing config
+- AI responses are buffered instead of streamed
 - human-readable output remains the default
 - package-manager wrappers may still write their own warnings to stderr
 

docs/architecture.md

@@ -502,11 +502,31 @@ Only Groq production models should be used as public defaults.
 Users can override automatic routing with `devmap config model <model>`.
 Running `devmap config model auto` restores the defaults above.
 
-Raw provider errors should not be shown directly to users.
-
----
-
-## Prompt Strategy
+Raw provider errors should not be shown directly to users.
+
+---
+
+## Streaming AI Output
+
+Groq chat completions use server-sent events for human-readable `analyze` and
+`ask` output. The provider adapter reconstructs the complete response while
+emitting incremental deltas to the output layer.
+
+Terminal Markdown is buffered to paragraph boundaries before rendering. This
+keeps headings, lists, tables, wrapping, and inline formatting readable while
+still showing the answer before generation has fully completed.
+
+Rules:
+
+* streaming is an optional `AiClient` capability
+* commands fall back to regular completion for clients without streaming
+* the final reconstructed text is used for snapshot persistence and metadata
+* rate-limit retry and model fallback happen before consuming response deltas
+* `--json` never streams because stdout must contain one complete JSON document
+
+---
+
+## Prompt Strategy
 
 Prompt templates should be centralized.
 

docs/commands.md

@@ -234,7 +234,9 @@ Shared utilities, database access, authentication logic, and helpers.
 * Do not send the entire project source to AI
 * Snapshot must be regenerated after analyze
 * Snapshot must remain compact and deterministic
-* Raw provider errors must not be shown directly to users
+* Raw provider errors must not be shown directly to users
+* New AI interpretation streams progressively in human-readable mode
+* Cached interpretation is rendered immediately without a provider request
 
 ---
 
@@ -317,7 +319,9 @@ app/api/auth/*
 * Include related files in output
 * Keep answer readable
 * Respond in the same language as the question
-* Technical labels can remain in English
+* Technical labels can remain in English
+* Stream new AI answers progressively in human-readable mode
+* Do not stream `--json`; emit one complete JSON document instead
 
 ### Output Example
 
@@ -508,6 +512,7 @@ Contract:
 * stdout contains exactly one JSON document
 * ANSI codes and terminal decoration are disabled
 * progress sections and Markdown rendering are omitted
+* AI responses are buffered instead of streamed
 * runtime failures return a JSON object with `status`, `error`, and optional `hint`
 * `init --json` never prompts and therefore requires `GROQ_API_KEY` or an
   existing API key

docs/development-testing.md

@@ -14,3 +14,22 @@ Parse stdout directly as JSON and verify that it contains no ANSI codes or
 terminal decoration. When invoking through `npm exec` or another package
 manager, ignore wrapper-owned stderr warnings and validate DevMap stdout
 separately.
+
+## AI Streaming Output
+
+Focused verification:
+
+```bash
+pnpm --filter devmap exec tsx --test test/ai-client.test.ts test/ask-command.test.ts test/analyze-ai.test.ts test/json-output.test.ts
+```
+
+With a live Groq key, run:
+
+```bash
+devmap analyze --fresh
+devmap ask "explain the main architecture"
+devmap ask "explain the main architecture" --json
+```
+
+Human output should appear progressively without raw Markdown markers. JSON
+output should wait for completion and remain one parseable document.

docs/for-me-personal/PROGRESS.md

@@ -1,6 +1,24 @@
 # Progress DevMap
 
-Terakhir diperbarui: 2026-06-14
+Terakhir diperbarui: 2026-06-15
+
+## Update 2026-06-15
+
+### AI Response Streaming
+
+- Human-readable `devmap ask` dan AI interpretation pada `devmap analyze`
+  sekarang memakai Groq server-sent events.
+- Delta response direkonstruksi menjadi hasil lengkap untuk token metadata,
+  snapshot persistence, dan cache.
+- Output ditampilkan progresif per paragraf agar heading, list, table, wrapping,
+  dan inline Markdown tetap rapi.
+- Provider yang belum memiliki method streaming tetap memakai regular
+  completion tanpa mengubah public command behavior.
+- Retry rate limit dan model fallback tetap berjalan sebelum stream dibaca.
+- `--json` sengaja tidak memakai streaming agar stdout tetap satu dokumen JSON.
+- Automated test mencakup SSE yang terpecah antar-network chunk, command
+  streaming, snapshot persistence, dan JSON non-streaming.
+- Automated test saat ini berjumlah 65 dan seluruhnya lulus.
 
 ## Update 2026-06-14
 

docs/for-me-personal/TEST.md

@@ -101,6 +101,39 @@ Expected:
 - API keys are never included;
 - packed package E2E verifies JSON output after tarball installation.
 
+## AI Response Streaming
+
+Focused automated test:
+
+```powershell
+pnpm --filter devmap exec tsx --test test/ai-client.test.ts test/ask-command.test.ts test/analyze-ai.test.ts test/json-output.test.ts
+```
+
+Coverage penting:
+
+- SSE event tetap terbaca ketika JSON event terpecah pada network chunk;
+- delta dikirim berurutan dan hasil lengkap dikembalikan provider;
+- `ask` dan fresh AI interpretation `analyze` memakai streaming jika tersedia;
+- hasil lengkap `analyze` tetap disimpan ke snapshot;
+- `--json` memakai completion penuh dan tidak memanggil streaming.
+
+Manual live check:
+
+```powershell
+$env:GROQ_API_KEY="gsk_your_key"
+pnpm dev:cli -- analyze --fresh
+pnpm dev:cli -- ask "explain the main architecture"
+pnpm dev:cli -- ask "explain the main architecture" --json | ConvertFrom-Json
+Remove-Item Env:GROQ_API_KEY
+```
+
+Expected:
+
+- human output mulai tampil sebelum seluruh AI response selesai;
+- Markdown tidak tampil mentah;
+- model dan token usage tetap muncul setelah stream selesai;
+- JSON baru dicetak setelah response lengkap dan dapat diparse langsung.
+
 ## Urutan Testing Yang Direkomendasikan
 
 Untuk development harian:

docs/roadmap.md

@@ -34,7 +34,7 @@ adding AI on top. If the foundation is wrong, AI output will be wrong too.
 - Groq integration with provider abstraction layer
 - Prompt templates for analyze and ask
 - Context Builder — keyword search + file ranking
-- Streaming output
+- [x] Streaming output for human `analyze` and `ask` responses
 - Retry logic + model fallback
 - Token-aware context trimming (max 5 files, max 200 lines each)
 - Cache integration — skip AI for unchanged files
@@ -120,4 +120,4 @@ Not planned. Not scheduled. Revisit when Phase 5 ships.
 | 1.2.0 | 2 | Express support solidified |
 | 2.0.0 | 3 | `devmap docs` + `devmap onboard` |
 | 3.0.0 | 4 | `devmap deadcode` + `devmap flow` + `devmap report` |
-| 4.0.0 | 5 | OpenAI + Gemini support |
+| 4.0.0 | 5 | OpenAI + Gemini support |

packages/cli/src/ai/completion.ts

@@ -0,0 +1,42 @@
+import { output } from "../utils/output.js";
+import type {
+  AiClient,
+  AiCompletionRequest,
+  AiCompletionResult
+} from "./types.js";
+
+export type AiCompletionExecution = {
+  result: AiCompletionResult;
+  streamed: boolean;
+};
+
+export async function completeWithOptionalStreaming(
+  client: AiClient,
+  request: AiCompletionRequest,
+  enabled: boolean,
+  onStreamStart?: () => void
+): Promise<AiCompletionExecution> {
+  if (!enabled || !client.stream) {
+    return {
+      result: await client.complete(request),
+      streamed: false
+    };
+  }
+
+  const renderer = output.markdownStream();
+  let started = false;
+  try {
+    const result = await client.stream(request, (delta) => {
+      if (!started) {
+        onStreamStart?.();
+        started = true;
+      }
+      renderer.write(delta);
+    });
+    renderer.end();
+    return { result, streamed: true };
+  } catch (error) {
+    renderer.end();
+    throw error;
+  }
+}