feat(augment): multi-agent improvements, limit removal, and routing fix (#2600)

* feat(augment): multi-agent improvements, limit removal, and routing fix

Follow-up to #2555. Adds multi-agent orchestration improvements,
removes artificial limits, and fixes multi-turn agent routing.

Multi-agent orchestration:
- ADK-based orchestrator with HITL approval mirroring, tool resolver,
  conversation state management, and agent handoffs
- VectorStoreFacade lazy init and single-flight improvements
- ResponsesApiService previous_response_id fix

Limit removals (per design decision):
- Remove MAX_TOOL_OUTPUT_CHARS, MAX_MCP_PROXY_RESPONSE_BYTES,
  MAX_RESPONSE_CHAIN_DEPTH, MAX_CONTINUATION_ITERATIONS,
  MAX_MESSAGE_CONTENT_LENGTH, and all truncation logic
- Remove maxToolOutputChars and maxResponseChars config
- Keep MAX_AUTO_REAPPROVALS (Llama Stack bug workaround),
  auth constants, timeouts, and cache limits

Routing fix:
- Upgrade @augment-adk/augment-adk from 0.1.11 to 0.1.12
- Restore createContinuationState and resumeState so follow-up
  messages resume from the active agent instead of restarting
  from the router

Frontend enhancements:
- ToggleSwitch component, selectMenuProps helper
- Vector store UI and admin panel improvements

Code quality:
- McpAuthService double-map-lookup fix
- TfIdfEmbedder sort simplification

Documentation:
- CONFIG_REFERENCE.md, TROUBLESHOOTING.md

Tests:
- Comprehensive coverage (162 suites, 2644 tests passing)
- 6 resumeState continuity tests

* fix(augment): address SonarCloud quality gate findings

- Use localeCompare for string sorts (TfIdfEmbedder, BackendToolExecutor.test)
- Fix Promise-in-boolean conditionals with !== undefined (McpAuthService, VectorStoreFacade)
- Remove unnecessary non-null assertions (AdkOrchestrator, VectorStoreFacade)
- Reduce cognitive complexity by extracting helpers:
  - AdkOrchestrator: resolveAgentContinuity(), mirrorPendingApprovals()
  - chatRoutes: resolveConversationId()
  - BackendToolExecutor: processDiscoveryResults(), preserveFailedServerTools(), etc.
- Move makeMultiAgentSnapshot to outer describe scope (AdkOrchestrator.test)
- Mark ToggleSwitch props as readonly

* fix(augment): update API report and move test helper to module scope

- Remove maxResponseChars from MCPServerConfig in report.api.md
  to match the source type (field was removed in limit-removal changes)
- Move makeMultiAgentSnapshot to module scope (outside describe block)
  to satisfy SonarCloud's "no functions in nested scope" rule

* fix(augment): use https in test mock URLs for SonarCloud security hotspots

Replace http:// with https:// in test fixture data (mock baseUrl and
serverUrl values) to clear SonarCloud security hotspot warnings about
clear-text protocol usage.

Author: rrbanda

workspaces/augment/README.md

@@ -2,15 +2,70 @@
 
 This workspace contains the Augment plugin family for Red Hat Developer Hub.
 
-Augment is a configurable AI assistant with RAG, multi-agent orchestration, tool calling via MCP servers, and safety guardrails.
+Augment is a config-driven AI assistant built on [Llama Stack's OpenAI-compatible Responses API](https://developers.redhat.com/articles/2025/08/20/your-agent-your-rules-deep-dive-responses-api-llama-stack). It provides RAG-powered document search, multi-agent orchestration, tool calling via MCP servers, and safety guardrails — all running against open-source models on your own infrastructure.
+
+## Architecture
+
+Augment follows the same agent architecture as the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/multi_agent/): an agent is **not** a server-side resource — it is a client-side abstraction of `instructions + tools + model`, assembled into a `POST /v1/responses` call against Llama Stack.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Backstage Frontend (augment plugin)                     │
+│  Chat UI · Handoff visualization · Agent status panel    │
+└──────────────────────┬───────────────────────────────────┘
+                       │  SSE / REST
+┌──────────────────────▼───────────────────────────────────┐
+│  Backstage Backend (augment-backend plugin)              │
+│                                                          │
+│  ┌─────────────────────────────────────────────────────┐ │
+│  │  ResponsesApiCoordinator (multi-agent orchestrator) │ │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │ │
+│  │  │ Router   │→ │Specialist│→ │ Specialist        │  │ │
+│  │  │ Agent    │  │ Agent A  │  │ Agent B           │  │ │
+│  │  │          │  │          │  │                    │  │ │
+│  │  │ tools:   │  │ tools:   │  │ tools:            │  │ │
+│  │  │ transfer │  │ MCP svrs │  │ file_search, MCP  │  │ │
+│  │  │ _to_*    │  │          │  │                    │  │ │
+│  │  └──────────┘  └──────────┘  └──────────────────┘  │ │
+│  └─────────────────────────────────────────────────────┘ │
+│                                                          │
+│  DocumentService · ConversationManager · SafetyService   │
+└──────────────────────┬───────────────────────────────────┘
+                       │  OpenAI-compatible REST
+┌──────────────────────▼───────────────────────────────────┐
+│  Llama Stack Server                                      │
+│  /v1/responses · /v1/conversations · /v1/vector_stores   │
+│  /v1/files · /v1/models · /v1/shields                    │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Multi-Agent Orchestration
+
+Each agent in the YAML config becomes a unique `POST /v1/responses` call with its own `instructions`, `tools`, `temperature`, and `toolChoice`. Multi-agent routing uses the [OpenAI Agents SDK handoff pattern](https://openai.github.io/openai-agents-js/guides/handoffs/):
+
+- **Handoffs** (`transfer_to_{agent}`): A router agent delegates to a specialist who takes over the conversation.
+- **Agents-as-tools** (`call_{agent}`): A manager agent calls specialists as tools and retains control of the response.
+
+All agents share the same Llama Stack `conversation` ID for context continuity across handoffs.
+
+### Key APIs Used
+
+| Llama Stack API              | Purpose                                                            |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `POST /v1/responses`         | All LLM inference — each agent config becomes a parameterized call |
+| `POST /v1/conversations`     | Persistent conversation state across agent handoffs                |
+| `POST /v1/vector_stores`     | RAG document storage and retrieval                                 |
+| `POST /v1/files`             | Document upload for ingestion                                      |
+| `GET /v1/models`             | Model discovery and validation                                     |
+| `POST /v1/safety/run-shield` | Input/output safety guardrails                                     |
 
 ## Plugins
 
-| Plugin                                                                                | Description                  |
-| ------------------------------------------------------------------------------------- | ---------------------------- |
-| [@red-hat-developer-hub/backstage-plugin-augment](./plugins/augment/)                 | Frontend plugin              |
-| [@red-hat-developer-hub/backstage-plugin-augment-backend](./plugins/augment-backend/) | Backend plugin               |
-| [@red-hat-developer-hub/backstage-plugin-augment-common](./plugins/augment-common/)   | Shared types and permissions |
+| Plugin                                                                                | Description                                                        |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| [@red-hat-developer-hub/backstage-plugin-augment](./plugins/augment/)                 | Frontend — chat UI, agent handoff visualization, admin panels      |
+| [@red-hat-developer-hub/backstage-plugin-augment-backend](./plugins/augment-backend/) | Backend — multi-agent orchestrator, RAG ingestion, MCP integration |
+| [@red-hat-developer-hub/backstage-plugin-augment-common](./plugins/augment-common/)   | Shared types, permissions, and security mode definitions           |
 
 ## Development
 

workspaces/augment/app-config.yaml

@@ -36,3 +36,64 @@ augment:
   llamaStack:
     baseUrl: ${AUGMENT_LLAMA_STACK_URL:-http://localhost:8321}
     model: ${AUGMENT_MODEL:-meta-llama/Llama-3.3-70B-Instruct}
+
+  promptGroups:
+    - id: getting-started
+      title: Getting Started
+      description: Common tasks to help you get up and running
+      icon: rocket
+      color: '#9333ea'
+      order: 1
+      cards:
+        - title: Explore the Catalog
+          description: Find components, APIs, and services
+          prompt: What components and services are available in the Backstage catalog? Give me an overview.
+          icon: search
+        - title: Onboarding Guide
+          description: New to the platform? Start here
+          prompt: I'm new to this platform. Can you walk me through what's available and how to get started?
+          icon: school
+        - title: Check System Health
+          description: Get a quick status overview
+          prompt: Can you check the health and status of the platform services?
+          icon: speed
+
+    - id: development
+      title: Development
+      description: Tools and helpers for your development workflow
+      icon: code
+      color: '#0ea5e9'
+      order: 2
+      cards:
+        - title: Debug an Issue
+          description: Troubleshoot errors and failures
+          prompt: I'm running into an issue and need help debugging. Can you help me investigate?
+          icon: bug
+        - title: Review Logs
+          description: Analyze recent logs for problems
+          prompt: Can you help me review recent logs and identify any errors or warnings?
+          icon: terminal
+        - title: Code Review Help
+          description: Get feedback on code changes
+          prompt: I'd like help reviewing code changes. What best practices should I follow?
+          icon: github
+
+    - id: operations
+      title: Operations
+      description: Manage deployments, infrastructure, and configurations
+      icon: cloud
+      color: '#10b981'
+      order: 3
+      cards:
+        - title: Deployment Status
+          description: Check current deployment state
+          prompt: What is the current deployment status? Are there any recent deployments or rollouts in progress?
+          icon: rocket
+        - title: Infrastructure Overview
+          description: Review cluster and resource usage
+          prompt: Give me an overview of the infrastructure — cluster health, resource usage, and any alerts.
+          icon: storage
+        - title: Configuration Check
+          description: Review and validate configurations
+          prompt: Can you review the current configurations and flag any potential issues or misconfigurations?
+          icon: settings