Enhance AI Assistant UX: ACP & API Parity

The Challenge: Bridging the Gap in AI Assistant Experiences

In the realm of AI-powered tools, a seamless and predictable user experience is paramount. When using features like the ACP (presumably a specific AI control panel or component) and the API assistant, users expect a consistent interaction, regardless of the underlying mechanism. However, a significant disconnect has emerged. The ACP mode and the API LLM mode, while both leveraging AI, present divergent experiences in terms of inputs, outputs, data schemas, and overall UI behavior. This inconsistency creates a jarring user experience, affecting everything from the timing of streaming completions to the richness of tool logs, the clarity of plan rendering, and the functionality of the code block apply UI. Such discrepancies make it harder for users to anticipate how the assistant will behave, leading to frustration and reduced efficiency. The core problem is a lack of UX parity, where distinct technical paths result in fundamentally different user-facing outcomes. Imagine asking an AI assistant to perform a task via two different interfaces and getting vastly different feedback or functionality; this is precisely the issue we aim to resolve.

The Vision: A Unified AI Assistant Experience

To tackle the UX inconsistencies between the ACP and API assistant modes, our proposed solution is to introduce a parity layer. This innovative layer will act as a bridge, normalizing the events and data coming from both ACP and API pathways into a single, unified UI model. The goal is to abstract away the differences, presenting a consistent face to the user. A key aspect of this unification involves ensuring that both interaction paths share the same system prompts and, where feasible, the same output parsing rules. By harmonizing these fundamental elements, we can significantly reduce the behavioral divergences. This means that whether a user interacts through the ACP or directly via the API, the underlying AI model receives comparable instructions (system prompts), and the results are interpreted in a standardized manner. This approach not only simplifies the user's interaction but also makes the AI assistant's behavior more predictable and reliable across all touchpoints. Think of it as creating a universal translator for AI assistant interactions, ensuring that the message and its feedback are understood consistently by both the user and the system.

Identifying the Gaps: Where Inconsistency Creeps In

Our investigation into the current AI assistant functionality revealed several critical gaps contributing to the UX disparity between ACP and API modes. Firstly, system prompts are currently injected only for the API flow. This means the ACP flow doesn't receive the benefit of specialized prompts like PATCH, RANGE, or CHAT prompts, which are crucial for guiding the AI's behavior in specific contexts. This missing piece can lead to less tailored or effective responses within the ACP. Secondly, there's a significant difference in how streaming completions are handled. The ACP mode completes its streaming immediately after the prompt() function is called, even before receiving any actual updates from the AI. In contrast, the API mode only signals completion once an ai_response_complete event is received. This discrepancy in timing can make the ACP feel unresponsive or prematurely finished. Thirdly, the ACP does not extract code blocks effectively. Consequently, the user-friendly 'apply' UI for code blocks, which is present and functional in the API mode, is either missing or behaves inconsistently in ACP. This hinders the ability of ACP users to directly utilize AI-generated code. Fourthly, ACP's Plan updates are flattened into simple text. Instead of presenting the structured steps of a plan, as the API mode does, ACP treats them as a monolithic block of text. This eliminates the possibility of using dedicated UI components for plan visualization and interaction, making complex sequences harder to grasp. Finally, tool logs in ACP are less structured and informative compared to the API tool logs. This lack of detail and structure makes it more difficult for users to understand the AI's actions, debug issues, or gain insights from its operational process. Addressing these specific gaps is essential for achieving true UX parity.

Defining Success: Our Acceptance Criteria for Parity

To ensure that our proposed parity layer effectively unifies the ACP and API assistant experiences, we've established clear acceptance criteria. These benchmarks will guide our implementation and verification process. Firstly, both ACP and API flows must share identical system prompt injection rules. Alternatively, if direct rule sharing isn't feasible, the ACP side will implement an equivalent prompt normalizer to achieve the same outcome. This ensures the AI receives consistent foundational instructions regardless of the access method. Secondly, the trigger for streaming completion needs to be standardized. Both flows will now signal completion based on comparable end-of-stream signals, rather than the immediate dispatch of the request in ACP or the completion of a response in API. This guarantees a consistent user perception of when the AI has finished generating its output. Thirdly, code blocks must be extracted and rendered consistently across both flows. This means the UI components for handling and applying code snippets will be uniform, enabling users to seamlessly integrate AI-generated code whether they are using ACP or the API. Fourthly, plan updates and tool logs must render using the same UI components for both flows. This ensures that structured plans and detailed tool logs are presented in a comparable, understandable format, leveraging dedicated UI elements for clarity. Finally, and crucially, there should be no regression in existing API or ACP functionality. While we are improving consistency, we must ensure that all previously working features continue to operate as expected. Meeting these criteria will signify that we have successfully achieved the desired UX parity for our AI assistant.

Implementation Blueprint: The Technical Pathway to Parity

Implementing the parity layer requires a focused approach, targeting specific areas within our codebase. The primary files slated for modification include client/src/hooks/useAIConversation.ts and client/src/hooks/useAIStreaming.ts. These hooks are central to managing the conversational flow and the streaming of AI responses, making them ideal places to introduce normalization logic. We will also be refining client/src/components/ai-panel/StreamingMessage.tsx, ensuring that the UI components that display streaming messages, plans, and tool logs are capable of handling the unified data model consistently. On the ACP side, the acp/src/gateway.rs file will be crucial for mapping ACP-specific updates to the common UI schema. This will involve adapting the data structures and event handling within the ACP gateway to align with the unified model. Furthermore, changes in server/src/handlers/common.rs and server/src/handlers/ai_handler.rs will be necessary to standardize how prompts are processed and outputs are parsed at the server level, ensuring consistency before the data even reaches the client. A key architectural consideration is to potentially introduce a shared “assistant event” adapter. This adapter would serve as a central hub, translating both ACP and API events into a common schema that the UI can readily consume. This modular approach will enhance maintainability and make future updates more straightforward. The technical roadmap is clear: identify the touchpoints of divergence, implement normalization logic at these points, and ensure that the data presented to the user is consistent and meaningful, regardless of the initial interaction method.

Verification and Testing: Ensuring Seamless Integration

Rigorous testing and verification are essential to confirm that the implementation of the parity layer has successfully achieved the desired UX parity between ACP and API assistant modes. Our testing strategy will involve a direct comparison of the UI rendering for both ACP and API interfaces when presented with the exact same prompt. This side-by-side comparison will allow us to meticulously check for consistency across several key areas. First, we will scrutinize the streaming indicators. Users should perceive the AI's response generation in a similar fashion, with comparable visual cues and timing. Second, the output of tool logs will be meticulously compared. We need to ensure that the level of detail, structure, and clarity in tool logs is identical, regardless of whether the interaction originated from ACP or the API. This is vital for debugging and understanding the AI's process. Third, the plan display will be evaluated. Both modes should present structured plan steps using the same UI components, allowing for easy comprehension of multi-step tasks. Fourth, the code block apply UI will be checked for uniformity. This includes ensuring that code blocks are correctly identified, displayed, and that the 'apply' functionality works consistently and intuitively in both ACP and API contexts. By focusing on these specific comparison points, we can confidently validate that the parity layer has effectively harmonized the user experience, making our AI assistant more intuitive and predictable for all users. For further insights into best practices for AI user interface design and ensuring consistency across platforms, you can explore resources from UX Collective. Additionally, understanding API design principles and their impact on user experience can be found on Swagger's resources.