feat(ai): streaming reasoning think token parser and bounded stream sanitizer (#128)

[dan-petty]

Summary of Changes

Closes #128. Addresses review comments on merged PR #240.

1. Streaming Reasoning Think Token Parser & Bounded Stream Sanitizer (#128)

• Standardized Token Processor: Implemented StreamingTokenProcessor (and StreamingReasoningSanitizer alias) in devops_cli.ai.client.streaming that cleanly extracts reasoning tokens (<think>...</think>) into a structured reasoning scratchpad while streaming sanitized markdown text to downstream callers.
• Multi-Provider Thinking Extraction: Supported inline <think> tags and discrete provider fields across Ollama, Anthropic/Claude (SSE thinking_delta), and OpenAI-compatible endpoints (reasoning_content, reasoning).
• Bounded Stream Guard & Reconnect Support: Enforced strict MAX_STREAM_BYTES (50MB) truncation boundary guards and resilient SSE line streaming with transient network reconnect handling.
• Review Runner Sanitization: Integrated strip_think_blocks into markdown review export formatting to ensure clean review reports without raw <think> blocks.
• Comprehensive Unit Testing: Added tests/test_ai_streaming.py with 31 unit tests covering split tags, multi-chunk accumulation, 50MB limits, async streams, and edge cases.

2. PR #240 Review Comment Remediation

• Ollama Prewarm Payload: Added "prompt": "" to /api/generate prewarm request payload in _preload_single_ollama_url (src/devops_cli/ai/client/ollama.py).
• Paired Typer Option: Replaced positive-only --all-nodes flag with paired --all-nodes/--single-node option in devops ai prewarm (src/devops_cli/commands/ai.py).
• Telemetry Recording: Instrumented devops ai prewarm with trace_span("ai.prewarm") and record_metric("ai.prewarm.success").
• Eviction Keep-Alive Default: Wired DEFAULT_AI_EVICT_KEEP_ALIVE into evict_models and prewarm.
• Task Record & Threads: Updated task-127 record to #240 (Merged); posted replies to all 5 review threads and marked them as resolved.

3. Concurrency Protection for Coverage Artifacts

• Race Condition Remediation: Added active pytest session guard (PYTEST_CURRENT_TEST) to _clean_coverage_artifacts in src/devops_cli/commands/ci.py to prevent background tasks or subtests from unlinking live .coverage.* worker databases during pytest execution.

Verification

• uv run devops ci: All 10 quality gates passed with 100% locally.
• uv run devops scan complexity: All touched files strictly conform to $M \le 10$ and depth $< 6$.

[Copilot]

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR adds streaming <think> parsing, reasoning extraction, provider-specific stream handling, and bounded stream utilities, alongside prewarm and CI updates.

Changes:

• Added StreamingTokenProcessor with sanitization, callbacks, scratchpad access, and byte limits.
• Added Ollama, Claude, and OpenAI extraction tests plus markdown leakage protection.
• Updated prewarm behavior, telemetry, coverage cleanup, exports, and documentation.

File summaries

File	Description
tests/test_ci.py	Updated as part of this pull request.
tests/test_ai_streaming.py	Updated as part of this pull request.
tests/test_ai_prewarm.py	Updated as part of this pull request.
src/devops_cli/commands/ci.py	Updated as part of this pull request.
src/devops_cli/commands/ai.py	Updated as part of this pull request.
src/devops_cli/ai/thinking_stream.py	Updated as part of this pull request.
src/devops_cli/ai/review/runner.py	Updated as part of this pull request.
src/devops_cli/ai/client/unified.py	Updated as part of this pull request.
src/devops_cli/ai/client/streaming.py	Updated as part of this pull request.
src/devops_cli/ai/client/ollama.py	Updated as part of this pull request.
src/devops_cli/ai/client/init.py	Updated as part of this pull request.
src/devops_cli/ai/init.py	Updated as part of this pull request.
docs/commands/ai.md	Updated as part of this pull request.
docs/CLI_REFERENCE.md	Updated as part of this pull request.
docs/agent/tasks/task-128-streaming-reasoning-think-tokens.md	Updated as part of this pull request.
docs/agent/tasks/task-127-ai-model-prewarming-vram-eviction.md	Updated as part of this pull request.

Review details

Suppressed comments (6)

docs/CLI_REFERENCE.md:2623

• This generated entry has the same stale description as the command documentation: --single-node selects only the primary configured node, not all nodes. Regenerate this reference after correcting the source help text.

| `--all-nodes`, `-a`, `--single-node` | `boolean` | `True` | Prewarm or evict model across all configured Ollama cluster nodes. |

docs/agent/tasks/task-127-ai-model-prewarming-vram-eviction.md:5

• Completed is not a supported task lifecycle value; the task template and lifecycle define the post-merge state as Done. Use **Status**: Done so project synchronization and status consumers recognize this completed task.

**Status**: Completed

docs/commands/ai.md:80

• --single-node now selects only configured_urls[0], but this generated entry still says the option targets all configured nodes. Update the source help text and regenerate both CLI references so the new negative flag documents its single-node behavior accurately.

| `--all-nodes`, `-a`, `--single-node` | `boolean` | `True` | Prewarm or evict model across all configured Ollama cluster nodes. |

src/devops_cli/ai/client/streaming.py:174

• If a stream ends after a split opening tag such as feed("<th"), _process_outside_think leaves that suffix buffered and this branch emits it verbatim during flush(). That leaks a partial <think> marker into sanitized output; discard a buffered prefix overlap with open_tag on flush instead of treating it as final content.

        elif self._buffer:
            emitted = self._emit_safe_tokens(self._buffer)

src/devops_cli/ai/client/streaming.py:63

• For custom limits below 1 MiB, this diagnostic reports 0MB because of integer division (the test uses max_stream_bytes=50). The message should report the configured byte limit or use a non-truncating formatter so users are not told the wrong boundary.

                f"Stream exceeded maximum size limit of {self.max_stream_bytes // (1024 * 1024)}MB."

src/devops_cli/commands/ci.py:132

• The new PYTEST_CURRENT_TEST early return is not exercised: both existing tests call _clean_coverage_artifacts(force=True), bypassing the branch introduced here. Add coverage for default cleanup preserving artifacts under pytest and for force=True overriding that guard, so this destructive-cleanup safeguard cannot regress silently.

    if not force and os.getenv("PYTEST_CURRENT_TEST"):
        return

• Files reviewed: 16/16 changed files
• Comments generated: 7
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.