wp-agentic-writer/FRONTEND_AND_CHAT_FIX_SUMMARY.md

# WP Agentic Writer – Fix Summary: Chat & Frontend Build

**Date**: 2026-06-16 (original) / 2026-06-17 (updates)
**Status**: 🟢 RESOLVED

This document serves as a hands-off record of the debugging steps, root causes, and fixes applied to resolve the "empty chat response" issue and establish a proper frontend build pipeline.

---

## Updates (2026-06-17)

### Additional Backend Improvements

1. **Connection Test Caching** - Already existed in `class-provider-manager.php` (5-min TTL via transients)
2. **Cache Auto-Clear on Settings Save** - Added to `class-settings-v2.php`
   - Hooks to `updated_option` action
   - Clears connection test cache when local backend settings change
3. **Reasoning Content Parsing** - Added to `class-local-backend-provider.php`
   - Captures `reasoning_content` from thinking models
   - Debug logging included

### Build Validation ✅

| Check | Result |
|-------|--------|
| `npm run build` | ✅ Passes |
| PHP syntax (all files) | ✅ Passes |
| Build output | `dist/sidebar.js` (169 KB) |

### Important: Two sidebar.js Files

| File | Loaded by PHP? |
|------|----------------|
| `assets/js/sidebar.js` (438 KB) | ❌ Legacy, NOT loaded |
| `assets/js/dist/sidebar.js` (169 KB) | ✅ Current, loaded |

---

## Original Fixes (2026-06-16)

---

## 1. Frontend Build Pipeline Established

**Problem**: 
The PHP plugin explicitly loads `assets/js/dist/sidebar.js`. However, ongoing refactoring work was occurring in `assets/js/src/index.jsx`. Because there was no active build process, changes made in `index.jsx` were not reflecting in the application.

**Solution**:
*   Created `package.json` with `esbuild` to handle fast JSX compilation.
*   Added `scripts/build.js` configured specifically for WordPress Gutenberg (using `wp.element.createElement` and `wp.element.Fragment`).
*   **Critical Fix**: Ensured the esbuild configuration wraps the output in an anonymous IIFE (`format: "iife"`) *without* defining a `globalName: "wp"`. A named global would have caused the compiled script to overwrite WordPress's native `window.wp` object with `undefined`, breaking the editor.

**Usage**:
*   Run `npm run build` to compile `src/index.jsx` -> `dist/sidebar.js`.
*   Run `npm run build:watch` during active development.

---

## 2. Backend Fix: PHP Fatal Error on Connection Test

**Problem**: 
When the local backend provider received an HTTP 4xx/5xx error (e.g., when trying to test a connection to a rate-limited or failing model), the entire REST request crashed, resulting in a 500 server error and breaking the chat flow entirely.

**Root Cause**:
In `includes/class-local-backend-provider.php` (line 882), a double-quoted string was used for a `sprintf` format:
`__("API Error (HTTP %1$d): %2$s", "wp-agentic-writer")`
Because it was double-quoted, PHP attempted to interpolate `$d` and `$s` as variables, resolving them to empty strings. The resulting string `API Error (HTTP %1): %2` caused `sprintf` to throw a fatal `ValueError: Unknown format specifier ")"`.

**Fix**:
Changed the double quotes to single quotes to prevent PHP variable interpolation, preserving the intended positional specifiers:
`__('API Error (HTTP %1$d): %2$s', "wp-agentic-writer")`
*Scanned the rest of the codebase and confirmed this dangerous pattern does not exist anywhere else.*

---

## 3. Backend Fix: Agentic Models Returning "Empty Responses"

**Problem**:
The user experienced intermittent "empty chat response" errors even when the API connection was successful (HTTP 200). 

**Root Cause**:
The configured models (e.g., `dough/kr/claude-sonnet-4.5-thinking` and `ag/gemini-3-flash-agent`) are **agentic/tool-calling** models. When fed a large WordPress system prompt asking for plain prose, these models burned all their tokens on internal "reasoning", attempted to emit a function/tool call, failed (`finish_reason: "malformed_function_call"`), and returned **zero text content**.
Because the streaming buffer received no content, it fell back to non-streaming, which also yielded zero content, triggering a generic "empty response" error.

**Fix**:
1.  **Better Error Surfacing**: Updated the streaming and fallback logic in `class-local-backend-provider.php` to actively capture the `finish_reason` payload.
2.  If the provider returns empty content but has a finish reason of `malformed_function_call`, `tool_calls`, or `function_call`, the backend now intercepts this and throws a highly specific, actionable error:
    > *"The selected model [Model Name] returned no text (finish reason: tool/function call). This usually means an agentic/coding model is being used for prose. Choose a standard chat model (without an -agent or -agentic suffix) in Settings."*
3.  **Config Alignment**: Used WP-CLI to update the WordPress options table, switching the local backend models from the agentic variants to the standard `gemini/gemini-3-flash-preview` for all prose tasks (`chat`, `writing`, `planning`, etc.).

---

## Summary of Touched Files
*   `package.json` (New)
*   `scripts/build.js` (New)
*   `assets/js/dist/sidebar.js` (Rebuilt)
*   `includes/class-local-backend-provider.php` (Fixed string interpolation, added `finish_reason` edge-case handling, added error payload parsing).

The chat functionality is now robust, gracefully handles agentic model failures, and the React frontend can be reliably compiled from `index.jsx`.

---

## 4. Next Recommendations

With the frontend build pipeline established and the critical backend crashes resolved, the foundation is stable. Here are the recommended next steps:

1. **Complete the React File Splitting (Refactor Phase 2)** ⚠️ IN PROGRESS
   * Now that `index.jsx` compiles successfully to `dist/sidebar.js`, the massive 11,000+ line `index.jsx` should be split into modular React components.
   * **See `FRONTEND-REFACTOR-PHASE2.md` for the detailed modularization plan.**
   * The new `esbuild` setup natively supports resolving local imports, meaning you can safely extract components into a `src/components/` directory and import them into `index.jsx` without changing the PHP backend.
   * **Key clarification**: The source is `src/index.jsx`, which compiles to `dist/sidebar.js`. We are NOT creating a new `sidebar.jsx` source file - we are modularizing the existing `index.jsx`.

2. **Optimize `test_connection()` in the Provider Manager** ✅ COMPLETED
   * Implemented connection test caching using WordPress transients with 5-minute TTL in `class-provider-manager.php`.
   * Added automatic cache clearing in `class-settings-v2.php` when local backend settings are saved (URL, API key, model changes).
   * This eliminates redundant connection tests on every chat request, significantly reducing latency.

3. **Handle Reasoning Tokens for Thinking Models** ✅ COMPLETED
   * Added `reasoning_content` parsing to `chat_stream()` method in `class-local-backend-provider.php`.
   * The streaming parser now captures `chunk["choices"][0]["delta"]["reasoning_content"]` from thinking models like Claude extended thinking.
   * Reasoning content is passed through the callback so the frontend can optionally display it in a collapsible section.
   * Debug logging added to help identify when reasoning chunks are received.