From e469f2d46d0df95019a029f6f87812c6c4c74b98 Mon Sep 17 00:00:00 2001 From: gabemontero Date: Tue, 2 Jun 2026 16:54:59 -0400 Subject: [PATCH 1/8] fix(feat): initial prd, then openspec specs, for clean room re-impl of augment as part of boost Signed-off-by: gabemontero Co-Authored-By: Claude Opus 4.6 --- .../agent-creation-discovery/.openspec.yaml | 2 + .../agent-creation-discovery/design.md | 66 ++++ .../agent-creation-discovery/proposal.md | 32 ++ .../specs/agent-creation-paths/spec.md | 79 ++++ .../specs/agent-gallery/spec.md | 38 ++ .../specs/catalog-entities/spec.md | 114 ++++++ .../specs/mcp-tools/spec.md | 48 +++ .../changes/agent-creation-discovery/tasks.md | 82 +++++ .../.openspec.yaml | 2 + .../ai-chat-interaction-experience/design.md | 42 +++ .../proposal.md | 33 ++ .../specs/conversation-history/spec.md | 71 ++++ .../specs/frontend-composability/spec.md | 96 +++++ .../specs/hitl-approval/spec.md | 60 +++ .../specs/rag-knowledge/spec.md | 34 ++ .../specs/streaming-chat/spec.md | 56 +++ .../ai-chat-interaction-experience/tasks.md | 30 ++ .../.openspec.yaml | 2 + .../platform-operations-deployment/design.md | 55 +++ .../proposal.md | 34 ++ .../specs/cache-migration/spec.md | 82 +++++ .../specs/deployment/spec.md | 33 ++ .../specs/rag-pipelines/spec.md | 56 +++ .../specs/runtime-config/spec.md | 136 +++++++ .../specs/white-label/spec.md | 38 ++ .../platform-operations-deployment/tasks.md | 40 ++ .../.openspec.yaml | 2 + .../design.md | 94 +++++ .../proposal.md | 35 ++ .../specs/multi-agent-orchestration/spec.md | 56 +++ .../specs/normalized-streaming/spec.md | 38 ++ .../specs/provider-abstraction/spec.md | 73 ++++ .../specs/provider-hot-swap/spec.md | 56 +++ .../specs/provider-packaging/spec.md | 81 +++++ .../tasks.md | 69 ++++ .../security-safety-governance/.openspec.yaml | 2 + .../security-safety-governance/design.md | 59 +++ .../security-safety-governance/proposal.md | 33 ++ .../specs/access-control/spec.md | 153 ++++++++ .../specs/fine-grained-permissions/spec.md | 135 +++++++ .../specs/resilience/spec.md | 36 ++ .../specs/safety-shields/spec.md | 42 +++ .../security-safety-governance/tasks.md | 76 ++++ .../boost/specifications/boost-context.md | 155 ++++++++ .../prd/agent-creation-discovery.md | 337 +++++++++++++++++ .../prd/ai-chat-interaction-experience.md | 240 ++++++++++++ .../prd/platform-operations-deployment.md | 304 ++++++++++++++++ .../prd/pluggable-ai-platform-architecture.md | 342 ++++++++++++++++++ .../prd/security-safety-governance.md | 339 +++++++++++++++++ .../specifications/prd/use-case-index.md | 75 ++++ 50 files changed, 4193 insertions(+) create mode 100644 workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml create mode 100644 workspaces/boost/openspec/changes/agent-creation-discovery/design.md create mode 100644 workspaces/boost/openspec/changes/agent-creation-discovery/proposal.md create mode 100644 workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md create mode 100644 workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md create mode 100644 workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md create mode 100644 workspaces/boost/openspec/changes/agent-creation-discovery/specs/mcp-tools/spec.md create mode 100644 workspaces/boost/openspec/changes/agent-creation-discovery/tasks.md create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/.openspec.yaml create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/design.md create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/proposal.md create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/conversation-history/spec.md create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/hitl-approval/spec.md create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/rag-knowledge/spec.md create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/streaming-chat/spec.md create mode 100644 workspaces/boost/openspec/changes/ai-chat-interaction-experience/tasks.md create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/.openspec.yaml create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/design.md create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/proposal.md create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/specs/deployment/spec.md create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/specs/rag-pipelines/spec.md create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/specs/white-label/spec.md create mode 100644 workspaces/boost/openspec/changes/platform-operations-deployment/tasks.md create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/.openspec.yaml create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/design.md create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/proposal.md create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/multi-agent-orchestration/spec.md create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/normalized-streaming/spec.md create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-abstraction/spec.md create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-hot-swap/spec.md create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md create mode 100644 workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/tasks.md create mode 100644 workspaces/boost/openspec/changes/security-safety-governance/.openspec.yaml create mode 100644 workspaces/boost/openspec/changes/security-safety-governance/design.md create mode 100644 workspaces/boost/openspec/changes/security-safety-governance/proposal.md create mode 100644 workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md create mode 100644 workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md create mode 100644 workspaces/boost/openspec/changes/security-safety-governance/specs/resilience/spec.md create mode 100644 workspaces/boost/openspec/changes/security-safety-governance/specs/safety-shields/spec.md create mode 100644 workspaces/boost/openspec/changes/security-safety-governance/tasks.md create mode 100644 workspaces/boost/specifications/boost-context.md create mode 100644 workspaces/boost/specifications/prd/agent-creation-discovery.md create mode 100644 workspaces/boost/specifications/prd/ai-chat-interaction-experience.md create mode 100644 workspaces/boost/specifications/prd/platform-operations-deployment.md create mode 100644 workspaces/boost/specifications/prd/pluggable-ai-platform-architecture.md create mode 100644 workspaces/boost/specifications/prd/security-safety-governance.md create mode 100644 workspaces/boost/specifications/prd/use-case-index.md diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml b/workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml new file mode 100644 index 0000000000..28882f7998 --- /dev/null +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-19 diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/design.md b/workspaces/boost/openspec/changes/agent-creation-discovery/design.md new file mode 100644 index 0000000000..9c855b6e67 --- /dev/null +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/design.md @@ -0,0 +1,66 @@ +# Design: Agent Creation & Discovery + +## Context + +Boost models AI domain objects (agents, tools, models, MCP servers, vector stores) as Backstage catalog entities from the start, informed by augment's experience. Augment managed these entirely in plugin-internal caches — four separate in-memory stores with duplicate caches, no discoverability, and no catalog-level RBAC. Boost uses catalog entity providers from day one, with existing Backstage kinds (`Component`, `Resource`) and a migration path to upstream `AIContext` and `API v1alpha2` kinds when available. + +Boost implements the 4-stage agent lifecycle (Draft → Pending → Published → Archived) from the start — no legacy stage mappings needed. + +Boost integrates with an external skills marketplace (provided by a separate workspace) as a consumer, proxying browse/filter requests and handling local deployment of selected skills-based agents. + +## Goals + +- AI domain objects as Backstage catalog entities from day one (using existing kinds with upstream migration path) +- No in-memory caches for domain objects — catalog is the source of truth +- Entity providers packaged as an independent RHDH dynamic plugin module +- Toolscope as a standalone package with injectable cache adapter +- 4-stage lifecycle model with ownership semantics from the start +- Integration with external skills marketplace for agent discovery and deployment + +## Non-Goals + +- Modifying the MCP auth chain logic (only the tool schema cache) +- Building custom catalog entity pages (defer to catalog defaults) +- Lifecycle governance approval workflows (covered in Security & Governance change) + +## Decisions + +### Decision 1: Use existing kinds with fallback to upstream + +Use `kind: Component, spec.type: ai-agent` for agents and `kind: Resource, spec.type: ai-model|mcp-server|vector-store|ai-tool` for infrastructure resources. When upstream `AIContext` and `API v1alpha2` land, migrate to those kinds. Custom `CatalogProcessor` validators support both during transition. Tools are added as `kind: Resource, spec.type: ai-tool` to enable tool lifecycle permissions via catalog RBAC. + +### Decision 2: Entity providers as independently deployable backend services + +Entity providers are separate packages registered as Backstage backend services, each independently deployable as an RHDH dynamic plugin: + +- `kagenti-entity-provider` — `KagentiAgentEntityProvider` (5m), `KagentiToolEntityProvider` (5m) +- `llamastack-entity-provider` — `LlamaStackModelEntityProvider` (60s), `LlamaStackAgentEntityProvider` (5m) +- Core plugin: `McpEntityProvider` (5m), `VectorStoreEntityProvider` (10m) — cross-cutting + +**Standalone mode:** Install entity providers without boost to get catalog discoverability for teams already using Llama Stack or Kagenti. + +**Composed mode:** Boost provider modules compose these same packages internally — one install gives you AI capabilities + catalog entities. + +Packages live at `rhdh-plugins/workspace/boost/plugins/llamastack-entity-provider` and `kagenti-entity-provider`. + +### Decision 3: Gradual cache elimination + +Phase 1: EntityProviders emit entities alongside existing caches (dual-write). Phase 2: Frontend/backend consumers switch to catalog API queries. Phase 3: Remove in-memory caches. This avoids a big-bang migration. + +### Decision 4: toolscope extraction as standalone npm package + +The `services/toolscope/` subsystem (29 files) has zero Backstage dependencies. Extracted as `@augment/toolscope` with injectable `CacheAdapter` interface — default in-memory adapter for standalone use, Backstage adapter wrapping `coreServices.cache`. + +### Decision 5: 4-stage lifecycle with ownership + +Agents follow the 4-stage lifecycle from the start: Draft → Pending → Published → Archived. No legacy stage mappings or normalization layers — boost has no prior model to be compatible with. The `createdBy` field is set at registration and drives visibility filtering, action gating, and self-approval prevention. Cascading delete detects agent source and cleans up across corresponding stores. + +### Decision 6: Skills marketplace integration (consumer only) + +Augment integrates with an external skills marketplace provided by a separate workspace. Augment proxies browse/filter requests to the external catalog and owns only the deployment side: K8s manifest generation with OCI init containers, namespace scoping, and deployment progress tracking. Deployed skills carry `framework: 'docsclaw'` and `chatEndpoint` for direct routing. Deployed skills appear in the gallery with a skill badge. Skills catalog entities will eventually be emitted by the catalog module alongside other agent entities. + +## Risks + +- **Catalog polling latency vs. cache TTL:** Catalog entities update on provider schedules, not on-demand. Mitigated by keeping short poll intervals for models (60s) and offering manual refresh. +- **Upstream kind availability:** `AIContext` may not be ready. Mitigated by starting with existing kinds and designing for migration. +- **Upstream augment data import:** If boost ever needs to import agent data from augment, a one-time migration script would map 5-stage values to 4-stage. This is not a runtime concern. diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/proposal.md b/workspaces/boost/openspec/changes/agent-creation-discovery/proposal.md new file mode 100644 index 0000000000..fc7bde2327 --- /dev/null +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/proposal.md @@ -0,0 +1,32 @@ +# Proposal: Agent Creation & Discovery + +## Why + +An agentic AI platform is only as valuable as its agents. Augment supports four creation paths (no-code, template, DevSpaces, import), a gallery for discovery, and MCP tool connectivity. These form the supply side of the agent ecosystem. + +The current implementation manages agents, MCP servers, and models entirely within plugin-internal caches and databases. These domain objects are natural candidates for Backstage catalog entities, which would provide discoverability, ownership, lifecycle management, and catalog-level RBAC — capabilities the current approach cannot offer. + +## What Changes + +### Current Capabilities (retroactive documentation) + +- Browse and select agents via gallery (Kagenti) or router delegation (Llama Stack) +- Four agent creation paths: no-code builder, Software Template, DevSpaces, import +- MCP tool server registration with 4-level auth chain +- Agent lifecycle: draft → registered → deployed (published=true) +- Unified `ChatAgent` model merging agents from all providers + +### Architectural Improvements (from tech debt analysis) + +- Create catalog `EntityProvider` for AI agents (maps to upstream `AIContext` initiative) +- Create catalog `EntityProvider` for MCP servers (maps to upstream `API Discriminated Union v1alpha2`) +- Create catalog `EntityProvider` for AI models (currently duplicated in caches #3 and #4) +- Create catalog `EntityProvider` for vector stores +- Extract `toolscope/` as standalone package (zero Backstage dependencies) + +## Impact + +- New: `plugin-augment-backend-module-catalog-agents` (EntityProvider for agents) +- New: `plugin-augment-backend-module-catalog-mcp` (EntityProvider for MCP servers) +- `plugins/augment-backend/src/providers/` — remove agent card and model caches in favor of catalog +- `plugins/augment-backend/src/services/toolscope/` — extract as standalone package diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md new file mode 100644 index 0000000000..2c986b11a2 --- /dev/null +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md @@ -0,0 +1,79 @@ +# Agent Creation Paths + +Four creation methods converge on a unified `ChatAgent` model. All paths produce agents visible in the gallery and available in chat. + +## EXISTING Requirements + +### Requirement: No-Code Agent Builder + +Create agents visually without writing code. + +#### Scenario: Llama Stack no-code agent creation + +- **WHEN** the admin navigates to Admin Panel → Agents → "Create Agent" +- **THEN** an agent editor form shows: name, instructions, model, temperature, max tokens +- **AND** tool access is configured via MCP server/tool selection +- **AND** knowledge base is scoped via vector store ID selection +- **AND** handoffs are configured by selecting target agents +- **AND** on save, the agent is immediately available in chat + +#### Scenario: Kagenti no-code agent creation + +- **WHEN** the admin opens the `CreateAgentWizard` +- **THEN** a 3-step wizard guides: basics, deployment, runtime (plus optional build step) +- **AND** optionally, `AgentCreateIntentDialog` supports quick creation from natural language intent +- **AND** if a container build is needed, Shipwright is triggered +- **AND** the agent appears in the gallery on completion + +### Requirement: Agent from Software Template + +Bootstrap agent projects using Backstage Software Templates. + +#### Scenario: Scaffolder creates agent project + +- **WHEN** the user selects an agent template (LangGraph, CrewAI, Python A2A, etc.) +- **THEN** the scaffolder wizard collects: name, description, namespace, repo, framework options +- **AND** it generates: source code, Dockerfile, CI/CD pipeline, Kagenti manifest, MCP tool definitions +- **AND** CI/CD builds the container and registers the agent on merge + +### Requirement: Agent from DevSpaces + +Write agent code in a cloud development environment. + +#### Scenario: DevSpaces agent development + +- **WHEN** the admin launches a DevSpaces workspace from the Kagenti admin +- **THEN** a cloud IDE opens with agent SDK/ADK pre-installed +- **AND** the developer can test in a sandbox environment +- **AND** a Shipwright container build can be triggered from the admin panel +- **AND** the build pipeline panel shows status, logs, and history in real time +- **AND** on success, the agent is deployed as a K8s workload and discovered via A2A + +### Requirement: Import Existing Agent + +Bring existing agents (container images or source repos) into the platform. + +#### Scenario: Import container image + +- **WHEN** the user provides a container image reference +- **THEN** deployment configuration is collected: namespace, resource limits, env vars, MCP connections +- **AND** Kagenti deploys it as a K8s workload and discovers it via A2A +- **AND** the agent appears in the gallery with auto-detected capabilities + +#### Scenario: Import source repository + +- **WHEN** the user provides a source repo URL +- **THEN** build settings are configured and a Shipwright build is triggered +- **AND** on success, the agent is deployed and registered + +### Requirement: Governance Registration + +All agent creation paths register the agent for lifecycle governance. + +#### Scenario: Agent registered for governance on creation + +- **WHEN** an agent is created via any path (no-code, template, DevSpaces, import, or skills deployment) +- **THEN** the agent is automatically registered for governance (`governanceRegistered: true`) +- **AND** the agent enters the `Draft` lifecycle stage +- **AND** the `createdBy` field is set to the authenticated user's identity +- **AND** lifecycle actions (promote, withdraw, delete) are available per the agent's governance state diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md new file mode 100644 index 0000000000..c0da65b0f8 --- /dev/null +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md @@ -0,0 +1,38 @@ +# Agent Gallery and Discovery + +Browse, search, filter, and select agents from a curated gallery. The gallery merges agents from all providers into a unified view. + +## EXISTING Requirements + +### Requirement: Agent Catalog Dialog (Kagenti) + +A full-featured agent browsing experience for the Kagenti provider. + +#### Scenario: Browse all agents + +- **WHEN** the user clicks "Browse all agents" from the welcome screen +- **THEN** the `AgentCatalogDialog` opens showing all published agents +- **AND** agents can be searched by keyword, filtered by framework, and sorted by name/status/newest +- **AND** tabs separate: All, Recent, Pinned + +#### Scenario: Agent preview panel + +- **WHEN** the user selects an agent in the catalog +- **THEN** a preview panel shows: conversation starters, about section, skills, capabilities (streaming/A2A), and technical details (framework, workspace, version, endpoint) +- **AND** "Start Conversation" selects the agent and enables chat input + +#### Scenario: First visit auto-open + +- **WHEN** a user visits Augment with Kagenti provider and no agent is selected +- **THEN** the agent catalog dialog auto-opens + +### Requirement: Unified Agent List + +Agents from all providers are merged into a single discoverable list. + +#### Scenario: buildUnifiedAgentList merges providers + +- **WHEN** the agent gallery data is fetched via `GET /agents?published=true` +- **THEN** `useAgentGalleryData()` merges agents from all providers with a 155ms timeout +- **AND** guard merge + dedup ensures no duplicates +- **AND** featured agents are configured via `ChatExperiencePanel` diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md new file mode 100644 index 0000000000..aa13d3c915 --- /dev/null +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md @@ -0,0 +1,114 @@ +# Catalog Entities for AI Domain Objects + +AI agents, models, MCP servers, and vector stores are modeled as Backstage catalog entities. This replaces in-memory caches with catalog-managed lifecycle, providing discoverability, ownership, search, and RBAC integration. + +NOTE: These recommendations align with in-flight upstream Backstage initiatives: + +- `AIContext`: Agent Cards will map to this kind when available +- `API Discriminated Union v1alpha2`: MCP Servers and AI Model Servers will map to the expanded `API` kind when available + +The specifications below use existing Backstage kinds (`Resource`, `Component`) as the primary implementation path, with migration to upstream kinds when they land. Custom `CatalogProcessor` validators support both during transition. + +**Entity type strategy:** +| Domain Object | Immediate Kind | `spec.type` | Future Kind (upstream) | +|---|---|---|---| +| AI Agents | `Component` | `ai-agent` | `AIContext` | +| AI Models | `Resource` | `ai-model` | `API` (v1alpha2 discriminated union) | +| MCP Servers | `Resource` | `mcp-server` | `API` (v1alpha2 discriminated union) | +| Vector Stores | `Resource` | `vector-store` | (no upstream equivalent planned) | +| Tools | `Resource` | `ai-tool` | (no upstream equivalent planned) | + +Entity providers are **independently deployable Backstage backend services**, each packaged as its own RHDH dynamic plugin (`llamastack-entity-provider`, `kagenti-entity-provider`). They are registered as backend services per the [Backstage backend system architecture](https://backstage.io/docs/backend-system/architecture/services/). + +**Two deployment modes:** + +1. **Standalone:** Install `llamastack-entity-provider` or `kagenti-entity-provider` as independent RHDH dynamic plugins — gets AI domain objects in the catalog without the rest of boost. Packages live at `rhdh-plugins/workspace/boost/plugins/`. +2. **Composed:** When `boost-backend` is installed with provider modules, the same entity provider packages are composed internally — installing a provider module gives you both AI capabilities and catalog entities. + +Cross-cutting entities (MCP servers, vector stores) that aren't provider-specific live in the core plugin. + +## ADDED Requirements + +### Requirement: AI Agent Catalog Entities + +Agents are represented as Backstage catalog entities with lifecycle, ownership, and relations. + +#### Scenario: Kagenti module emits agent entities + +- **WHEN** the `KagentiAgentEntityProvider` (inside the Kagenti provider module) runs on its scheduled interval +- **THEN** it polls the Kagenti API for all agents across configured namespaces +- **AND** it emits catalog entities with `kind: Component, spec.type: ai-agent` (or `kind: AIContext` when upstream is available) +- **AND** agent capabilities, LLM demands, and MCP demands map to `spec.dependsOn` relations +- **AND** the entity replaces the in-memory `KagentiAgentCardCache` (cache #2) + +#### Scenario: Llama Stack module emits agent entities + +- **WHEN** the `LlamaStackAgentEntityProvider` (inside the Llama Stack provider module) runs on its scheduled interval +- **THEN** it reads configured agents from YAML/admin config +- **AND** it emits catalog entities for each configured agent with their tool sets and handoff targets + +#### Scenario: Agent lifecycle reflected in catalog + +- **WHEN** an agent transitions through lifecycle stages (Draft → Pending → Published → Archived) +- **THEN** the catalog entity's `metadata.annotations` reflect the current 4-stage lifecycle stage +- **AND** catalog entity lifecycle state maps: Draft → `experimental`, Published → `production`, Archived → `deprecated` +- **AND** `createdBy` ownership maps to catalog entity `spec.owner` for RBAC integration + +### Requirement: AI Model Catalog Entities + +AI models are represented as catalog entities, eliminating duplicate caches. + +#### Scenario: Provider modules emit model entities + +- **WHEN** the `LlamaStackModelEntityProvider` (inside the Llama Stack module) runs on its scheduled interval +- **THEN** it polls `/v1/models` from the Llama Stack endpoint +- **AND** it emits entities with `kind: Resource, spec.type: ai-model` +- **AND** this eliminates duplicate caches #3 (`ResponsesApiProvider._modelsCache`) and #4 (`KagentiProvider._modelsCache`) + +### Requirement: MCP Server Catalog Entities + +MCP servers are represented as catalog entities. + +#### Scenario: Core plugin emits MCP server entities + +- **WHEN** the `McpEntityProvider` (in the core plugin, cross-cutting) runs on its scheduled interval +- **THEN** it reads MCP server configurations from admin config and database +- **AND** it emits entities with `kind: Resource, spec.type: mcp-server` (or expanded `API` kind when upstream is available) +- **AND** auto-discovered tools are reflected as entity annotations +- **AND** this eliminates the unbounded tool schema cache (#7) + +### Requirement: Vector Store Catalog Entities + +RAG vector stores are represented as catalog entities. + +#### Scenario: Core plugin emits vector store entities + +- **WHEN** the `VectorStoreEntityProvider` (in the core plugin, cross-cutting) runs on its scheduled interval +- **THEN** it reads vector store configurations from admin config +- **AND** it emits entities with `kind: Resource, spec.type: vector-store` +- **AND** per-agent scoping is reflected via `spec.dependsOn` relations to agent entities + +### Requirement: Entity Providers as Independent Backend Services + +Entity providers are independently deployable Backstage backend services. + +#### Scenario: Standalone entity provider deployment (without boost) + +- **WHEN** `llamastack-entity-provider` or `kagenti-entity-provider` is installed as a standalone RHDH dynamic plugin +- **THEN** it registers as a Backstage backend service +- **AND** it registers its entity providers via `catalogProcessingExtensionPoint` +- **AND** it configures scheduled task runners for periodic polling (e.g., every 5 minutes for agents, every 60 seconds for models) +- **AND** AI domain objects appear in the Backstage catalog without the rest of boost installed + +#### Scenario: Entity provider composed into boost provider module + +- **WHEN** a boost provider module (e.g., `plugin-boost-backend-module-kagenti`) is installed +- **THEN** it composes the `kagenti-entity-provider` package internally +- **AND** it registers both AI capabilities (via `augmentProviderExtensionPoint`) and catalog entities (via `catalogProcessingExtensionPoint`) +- **AND** installing the provider module gives you both AI capabilities and catalog entities in one step + +#### Scenario: Cross-cutting entity providers in core plugin + +- **WHEN** the core `boost-backend` plugin starts +- **THEN** it registers `McpEntityProvider` and `VectorStoreEntityProvider` via `catalogProcessingExtensionPoint` +- **AND** these cross-cutting entities are available regardless of which provider modules are installed diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/mcp-tools/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/mcp-tools/spec.md new file mode 100644 index 0000000000..f16c4a9252 --- /dev/null +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/mcp-tools/spec.md @@ -0,0 +1,48 @@ +# MCP Tool Configuration + +Connect agents to live systems by registering MCP servers, configuring authentication, and setting tool approval policies. + +## EXISTING Requirements + +### Requirement: MCP Server Registration + +Administrators register MCP servers and auto-discover available tools. + +#### Scenario: Register MCP server + +- **WHEN** the admin adds an MCP server in the admin panel +- **THEN** they provide: URL, transport (Streamable HTTP / SSE), and display name +- **AND** authentication is configured via one of: OAuth client credentials, K8s ServiceAccount token, static headers, or infrastructure mTLS (Kagenti) +- **AND** a connection test auto-discovers available tools + +### Requirement: MCP Auth Chain (4 Levels) + +A hierarchical authentication resolution for MCP tool connections. + +#### Scenario: Auth chain resolution order + +- **WHEN** an MCP tool call requires authentication +- **THEN** `McpAuthService` resolves credentials in order: auth references (per-tool) → per-server OAuth → ServiceAccount tokens → global fallback +- **AND** resolved tokens are cached with TTL derived from token expiry +- **AND** token deduplication prevents concurrent refresh storms + +### Requirement: Tool Approval Policies + +Per-server and per-tool approval requirements are configurable. + +#### Scenario: Configure per-tool approval + +- **WHEN** the admin configures an MCP server's tools +- **THEN** each tool can have `requireApproval: true` or `false` +- **AND** tools can be scoped to specific agents via per-agent allowed tool subsets + +### Requirement: Kagenti Tool Management + +Kagenti provides dedicated tool lifecycle management. + +#### Scenario: Create tool via wizard + +- **WHEN** the admin uses the `CreateToolWizard` (3 steps: basics, runtime, deploy) +- **THEN** a new tool is configured and deployed +- **AND** `ToolInvokeDialog` allows direct testing of the tool +- **AND** backend proxy mode supports air-gapped environments diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/tasks.md b/workspaces/boost/openspec/changes/agent-creation-discovery/tasks.md new file mode 100644 index 0000000000..7a085c77ae --- /dev/null +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/tasks.md @@ -0,0 +1,82 @@ +# Tasks: Agent Creation & Discovery + +## 1. Entity Provider Packages — Independently Deployable Backend Services (P2) + +### 1a. kagenti-entity-provider package + +- [ ] 1a.1 Create `kagenti-entity-provider` package at `rhdh-plugins/workspace/boost/plugins/kagenti-entity-provider` +- [ ] 1a.2 Register as Backstage backend service per backend system architecture +- [ ] 1a.3 Implement `KagentiAgentEntityProvider` polling Kagenti API for agents (kind: Component, spec.type: ai-agent) +- [ ] 1a.4 Implement `KagentiToolEntityProvider` reading tool configs from Kagenti (kind: Resource, spec.type: ai-tool) +- [ ] 1a.5 Package as independently loadable RHDH dynamic plugin (usable without boost) +- [ ] 1a.6 Verify standalone deployment: entity provider loads and emits catalog entities without boost-backend installed + +### 1b. llamastack-entity-provider package + +- [ ] 1b.1 Create `llamastack-entity-provider` package at `rhdh-plugins/workspace/boost/plugins/llamastack-entity-provider` +- [ ] 1b.2 Register as Backstage backend service per backend system architecture +- [ ] 1b.3 Implement `LlamaStackModelEntityProvider` polling `/v1/models` (kind: Resource, spec.type: ai-model) +- [ ] 1b.4 Implement `LlamaStackAgentEntityProvider` reading configured agents from YAML/admin config (kind: Component, spec.type: ai-agent) +- [ ] 1b.5 Package as independently loadable RHDH dynamic plugin (usable without boost) +- [ ] 1b.6 Verify standalone deployment: entity provider loads and emits catalog entities without boost-backend installed + +### 1c. Composition into boost provider modules + +- [ ] 1c.1 `plugin-boost-backend-module-kagenti` composes `kagenti-entity-provider` internally +- [ ] 1c.2 `plugin-boost-backend-module-llamastack` composes `llamastack-entity-provider` internally +- [ ] 1c.3 Verify composed deployment: provider module install gives AI capabilities + catalog entities + +### 1d. Core plugin entity providers (cross-cutting) + +- [ ] 1d.1 Implement `McpEntityProvider` reading MCP server configs from admin DB (kind: Resource, spec.type: mcp-server) +- [ ] 1d.2 Implement `VectorStoreEntityProvider` reading vector store configs (kind: Resource, spec.type: vector-store) +- [ ] 1d.3 Register both via `catalogProcessingExtensionPoint` in core plugin + +### 1e. Shared entity concerns + +- [ ] 1e.1 Map agent `createdBy` → catalog entity `spec.owner` for RBAC integration +- [ ] 1e.2 Map 4-stage lifecycle (Draft/Pending/Published/Archived) → catalog lifecycle state (experimental/production/deprecated) in entity annotations +- [ ] 1e.3 Create `CatalogProcessor` validators for ai-agent, ai-model, mcp-server, vector-store, ai-tool types +- [ ] 1e.4 Configure scheduled task runners per provider (60s models, 5m agents/MCP/tools, 10m vector stores) + +## 2. Catalog Migration (P2) + +- [ ] 2.1 Add catalog API queries alongside existing cache reads (dual-read phase) +- [ ] 2.2 Update `useAgentGalleryData` to optionally read from catalog API +- [ ] 2.3 Update model list endpoints to read from catalog +- [ ] 2.4 Remove `KagentiAgentCardCache` (cache #2) after catalog migration +- [ ] 2.5 Remove `ResponsesApiProvider._modelsCache` (cache #3) and `KagentiProvider._modelsCache` (cache #4) after catalog migration +- [ ] 2.6 Remove `BackendToolExecutor` tool schema cache (cache #7) after catalog migration + +## 3. Toolscope Extraction (P2) + +- [ ] 3.1 Create `@augment/toolscope` package from `services/toolscope/` (29 files) +- [ ] 3.2 Define `CacheAdapter` interface replacing raw `Map<>` in embedding and session caches +- [ ] 3.3 Create default in-memory `CacheAdapter` for standalone use +- [ ] 3.4 Create Backstage `CacheAdapter` wrapping `coreServices.cache` +- [ ] 3.5 Update `augment-backend` to import from `@augment/toolscope` + +## 4. Lifecycle Model (P1) + +- [ ] 4.1 Implement 4-stage lifecycle (Draft → Pending → Published → Archived) as the only model — no legacy mappings +- [ ] 4.2 Document cascading delete behavior: source detection (kagenti/orchestration/workflow) → multi-store cleanup + +## 5. Skills Marketplace Integration (P1) + +- [ ] 5.1 Implement proxy routes to external skills catalog backend (`GET /skills`, `/skills/runtimes`, `/skills/domains`) +- [ ] 5.2 Implement skills browse UI with runtime and domain filters (consuming proxied data) +- [ ] 5.3 Implement K8s manifest generation with OCI init containers for local skill deployment +- [ ] 5.4 Add deployment progress polling and status display +- [ ] 5.5 Add skill badge to gallery for DocsClaw framework agents +- [ ] 5.6 Route chat to skill agents via `chatEndpoint` field + +## 6. Verify + +- [ ] 6.1 Verify catalog entities appear for agents, models, MCP servers, vector stores, and tools +- [ ] 6.2 Verify catalog-based agent gallery matches cache-based gallery +- [ ] 6.3 Verify agent `spec.owner` matches `createdBy` for RBAC +- [ ] 6.4 Verify lifecycle stage mapping: Draft→experimental, Published→production, Archived→deprecated +- [ ] 6.5 Verify toolscope package works standalone (without Backstage) +- [ ] 6.6 Verify toolscope package works with Backstage cacheService adapter +- [ ] 6.7 Verify skills deployment creates correct K8s manifests +- [ ] 6.8 Verify catalog module works as RHDH dynamic plugin diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/.openspec.yaml b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/.openspec.yaml new file mode 100644 index 0000000000..28882f7998 --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-19 diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/design.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/design.md new file mode 100644 index 0000000000..0f3f04b678 --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/design.md @@ -0,0 +1,42 @@ +# Design: AI Chat & Interaction Experience + +## Context + +The chat experience is fully functional but the frontend is monolithic. `AugmentPage` is the single routable extension, eagerly loading all 204 admin panel files and all provider-specific components. Sub-route refs already exist in `routes.ts` — the composability plumbing is partially there. + +## Goals + +- Decompose into composable extensions using existing sub-route refs +- Add lazy loading in `ChatView.tsx` and `AdminLayout.tsx` +- Add config-driven feature flags via `app-config.yaml` +- Register with Backstage `featureFlagsApiRef` + +## Non-Goals + +- Changing the streaming protocol or event processing +- Modifying HITL approval flow behavior +- Changing conversation persistence schema +- Migrating session caches (covered in platform-operations-deployment change) + +## Decisions + +### Decision 1: Composable extensions wrap lazy-loaded components + +Each new routable extension uses `React.lazy()` in its `component` factory. This means code-splitting happens at the extension boundary — deployers who mount only `AugmentChatPage` never download admin panel code. + +### Decision 2: Feature flags use both Backstage API and app-config + +Two mechanisms work together: + +- `app-config.yaml` `augment.features.*` keys provide deployer-controlled defaults +- Backstage `featureFlagsApiRef` allows runtime user-level overrides via Settings UI +- The `useFeatureFlags` hook checks app-config first, then `featureFlagsApiRef` for overrides + +### Decision 3: Existing AugmentPage preserved as composition root + +The monolithic `AugmentPage` remains available and unchanged. New extensions are additive. Zero breaking changes for existing deployers. + +## Risks + +- **Extension boundary state sharing:** Chat and admin extensions share `AugmentContext`. Mitigated by lifting shared state to a context provider registered at the plugin level, not the page level. +- **Lazy loading SSR incompatibility:** Not a concern — RHDH is SPA-only. diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/proposal.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/proposal.md new file mode 100644 index 0000000000..d093e74163 --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/proposal.md @@ -0,0 +1,33 @@ +# Proposal: AI Chat & Interaction Experience + +## Why + +Augment's core value is the developer-agent conversation interface. Without a compelling chat experience, the platform has no user-facing value regardless of backend configuration. The chat surface must deliver streaming responses, knowledge-grounded answers with citations, human-in-the-loop approval for sensitive actions, persistent conversation history, and developer debugging tools. + +The current implementation delivers all product capabilities but the frontend is monolithic — all 204 admin panel files and all provider-specific components are eagerly loaded for every user. The chat view needs composable extensions, lazy loading, and capability-driven rendering. + +## What Changes + +### Current Capabilities (retroactive documentation) + +- Streaming chat with real-time phase indicators and rich markdown rendering +- Knowledge-grounded answers (RAG) with source citations and expandable source cards +- Human-in-the-loop approval for tool calls with parameter editing +- Interactive cards (forms, auth flows) within conversations +- Conversation history with search, resume, feedback, and export +- Developer tools: execution trace, session inspector, message inspector +- Provider-adaptive chat experience (Llama Stack vs Kagenti paths) + +### Architectural Improvements (from tech debt analysis) + +- Lazy loading in `ChatView.tsx` for provider-specific components (204 admin panel files currently eagerly loaded) +- Split `AugmentPage` into composable routable extensions (chat, admin, agent studio) +- Capability-driven rendering replacing provider ID string checks +- Frontend feature flags via `app-config.yaml` and Backstage `featureFlagsApiRef` + +## Impact + +- `plugins/augment/src/plugin.ts` — new composable extensions +- `plugins/augment/src/components/ChatView.tsx` — lazy loading +- `plugins/augment/src/components/AugmentPage/AdminLayout.tsx` — lazy loading, capability checks +- `plugins/augment/src/config.d.ts` — feature flags schema diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/conversation-history/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/conversation-history/spec.md new file mode 100644 index 0000000000..85dfd3a55e --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/conversation-history/spec.md @@ -0,0 +1,71 @@ +# Conversation History + +Persistent, searchable conversation history with feedback, export, and developer inspection tools. + +## EXISTING Requirements + +### Requirement: Session Management and Search + +Past conversations are accessible, searchable, and resumable. + +#### Scenario: Browse conversation history + +- **WHEN** the user opens the right pane +- **THEN** grouped sessions are displayed with search +- **AND** sessions are scoped to the active provider's `providerId` + +#### Scenario: Resume past conversation + +- **WHEN** the user selects a past session +- **THEN** a confirmation dialog appears if a stream is currently active +- **AND** the full conversation loads with all messages, tool calls, and metadata +- **AND** the user can continue the conversation or review past exchanges + +#### Scenario: Search by keyword + +- **WHEN** the user types a search term in the history panel +- **THEN** sessions matching the keyword in message content are filtered and displayed + +### Requirement: Session Interactions + +Users can take actions on sessions and individual messages. + +#### Scenario: Provide feedback on a message + +- **WHEN** the user clicks thumbs up or thumbs down on an agent response +- **THEN** the feedback is stored via `augment_feedback` table with optional reasons +- **AND** the feedback is associated with the specific message ID + +#### Scenario: Edit and regenerate + +- **WHEN** the user edits a past question +- **THEN** the edited message is re-sent to the agent +- **AND** a new response is generated from the edited prompt + +#### Scenario: Export conversation + +- **WHEN** the user clicks export on a session +- **THEN** the full conversation is exported in a structured format + +#### Scenario: Admin cross-user view + +- **WHEN** an admin toggles "Show all users" in the history panel +- **THEN** sessions from all users are visible (not just the current user's) +- **AND** this is gated by `augment.admin` permission + +### Requirement: Developer Inspection Tools + +Professional developers can inspect agent execution for transparency and debugging. + +#### Scenario: Enable dev mode + +- **WHEN** the user toggles dev mode via the chat header +- **THEN** the execution trace panel shows step-by-step trace (agent turns, tool calls, reasoning steps as spans) +- **AND** the message inspector shows raw payload for individual messages +- **AND** the session state inspector shows full session JSON + +#### Scenario: Tool call drill-down in dev mode + +- **WHEN** the user expands a tool call in the execution trace +- **THEN** full input arguments and output are visible +- **AND** timing data (phase chips) shows duration of each phase diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md new file mode 100644 index 0000000000..58a8412d33 --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md @@ -0,0 +1,96 @@ +# Frontend Composability + +The frontend must be decomposed from a monolithic `AugmentPage` into composable extensions with lazy loading, feature flags, and capability-driven rendering. + +## ADDED Requirements + +### Requirement: Composable Routable Extensions + +Deployers can mount chat, admin, and agent studio independently. + +#### Scenario: Independent chat extension + +- **WHEN** a deployer wants only the chat interface without admin panels +- **THEN** they mount `AugmentChatPage` as a standalone routable extension +- **AND** it is provided via `augmentPlugin.provide(createRoutableExtension({ name: 'AugmentChatPage', mountPoint: chatRouteRef }))` +- **AND** it can be configured independently in `dynamic-plugins.yaml` with its own `dynamicRoutes` entry + +#### Scenario: Independent admin extension + +- **WHEN** a deployer wants to mount the admin panel at a separate route +- **THEN** they mount `AugmentAdminPage` as a standalone routable extension +- **AND** it uses the existing `settingsAdminRouteRef` mount point + +#### Scenario: Monolithic default preserved + +- **WHEN** no specific extensions are configured +- **THEN** the existing `AugmentPage` continues to work as the all-in-one default +- **AND** each extension is independently mountable + +### Requirement: Lazy Loading in Primary Paths + +Provider-specific and admin components are loaded only when needed. + +#### Scenario: ChatView lazy loads provider-specific components + +- **WHEN** `ChatView.tsx` renders +- **THEN** Kagenti-specific components (`AgentCreateIntentDialog`, `CreateAgentWizard`, `ToolCreateIntentDialog`, `CreateToolWizard`, `AgentLifecycleDetail`) are loaded via `React.lazy()` +- **AND** they are NOT statically imported at the top of the file +- **AND** they load only when the active provider is Kagenti AND the user triggers the relevant action + +#### Scenario: AdminLayout lazy loads panel groups + +- **WHEN** `AdminLayout.tsx` renders +- **THEN** the 204 admin panel component files are loaded via `React.lazy()` per panel group +- **AND** only the currently active panel group is loaded + +### Requirement: Config-Driven Feature Flags + +Deployers control feature visibility via `app-config.yaml`. + +#### Scenario: Feature flags in app-config + +- **WHEN** an administrator configures feature flags in `app-config.yaml` +- **THEN** the following features can be individually enabled or disabled: + ```yaml + augment: + features: + agentCreation: true + devSpaces: false + workflowBuilder: true + sandbox: false + observability: true + adminPanel: true + ``` +- **AND** a `useFeatureFlags` hook reads from `configApiRef` +- **AND** disabled features are not rendered (not just hidden) + +#### Scenario: Backstage feature flags registration + +- **WHEN** the augment plugin is loaded +- **THEN** it registers feature flags with Backstage's `featureFlagsApiRef` +- **AND** flags can be toggled in the Backstage settings UI without code changes or restarts + +### Requirement: UX/UXD Design Alignment + +All frontend components and UI flows align with RHDH usability and visual design standards. + +#### Scenario: Implementation from UX/UXD mockups + +- **WHEN** a frontend feature introduces or modifies user-visible UI +- **THEN** implementation follows approved mockups, wireframes, or design specs provided by the UX/UXD team (Figma, Sketch, or equivalent) +- **AND** no user-facing UI ships without a corresponding approved design artifact +- **AND** custom components that extend beyond PatternFly defaults require explicit UX/UXD review + +#### Scenario: Design review gate on frontend PRs + +- **WHEN** a frontend PR introduces or modifies user-visible UI (chat, gallery, admin panels, governance controls) +- **THEN** the PR requires UX/UXD sign-off before merge +- **AND** deviations from approved mockups are documented and justified + +#### Scenario: PatternFly and accessibility compliance + +- **WHEN** frontend components are implemented +- **THEN** they use PatternFly design system components and patterns consistent with RHDH +- **AND** all UI meets WCAG 2.1 AA accessibility standards +- **AND** keyboard navigation and screen reader support are validated diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/hitl-approval/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/hitl-approval/spec.md new file mode 100644 index 0000000000..e4d472ce69 --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/hitl-approval/spec.md @@ -0,0 +1,60 @@ +# Human-in-the-Loop Approval + +Review proposed agent actions (tool calls) before execution, with the ability to edit parameters, approve, or reject. No destructive action executes without explicit developer consent. + +## EXISTING Requirements + +### Requirement: Tool Call Approval Dialog + +Agents pause before executing sensitive tool calls and request user approval. + +#### Scenario: Tool call requiring approval + +- **WHEN** an agent proposes a tool call where `requireApproval: true` is configured +- **THEN** a `ToolApprovalDialog` displays: tool name, target system, and exact arguments +- **AND** the inference loop is paused on the backend via `BackendApprovalStore` +- **AND** the user can review, edit parameters via JSON editor, then approve or reject + +#### Scenario: User approves tool call + +- **WHEN** the user clicks approve in the approval dialog +- **THEN** `BackendApprovalHandler` resumes the paused inference loop +- **AND** the tool executes with the approved (potentially edited) parameters +- **AND** the result flows back into the conversation + +#### Scenario: User rejects tool call + +- **WHEN** the user clicks reject in the approval dialog +- **THEN** the agent is notified of the rejection +- **AND** it adjusts its approach without executing the tool + +#### Scenario: Auto-approve for read-only tools + +- **WHEN** a tool call is configured with `requireApproval: false` +- **THEN** it executes automatically without showing the approval dialog + +### Requirement: Interactive Cards + +Agents can request structured input or authentication within conversations. + +#### Scenario: Form card for structured input + +- **WHEN** an agent requires structured input from the user +- **THEN** it emits a form card with typed fields rendered inline in the conversation +- **AND** the user fills and submits the form, resuming the agent flow + +#### Scenario: Auth card for external authentication + +- **WHEN** an agent requires external authentication +- **THEN** it emits an auth card with an OAuth sign-in flow +- **AND** on successful authentication, the agent continues with the obtained credentials + +### Requirement: Approval Audit Trail + +Every approval decision is persisted for auditability. + +#### Scenario: Approval decisions stored in session + +- **WHEN** a user approves or rejects a tool call +- **THEN** the decision (approve/reject), timestamp, parameters, and user identity are stored in the session history +- **AND** they are visible in the execution trace panel (dev mode) diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/rag-knowledge/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/rag-knowledge/spec.md new file mode 100644 index 0000000000..08c53b852c --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/rag-knowledge/spec.md @@ -0,0 +1,34 @@ +# Knowledge-Grounded Answers (RAG) + +Answers grounded in the organization's own documentation, with source citations enabling developers to trace every claim to a source. + +## EXISTING Requirements + +### Requirement: RAG-Grounded Responses with Citations + +The agent searches the knowledge base and provides cited answers. + +#### Scenario: Question about internal documentation + +- **WHEN** a user asks about internal documentation, runbooks, or policies +- **THEN** the agent determines retrieval is relevant and searches the knowledge base +- **AND** the UI shows "Searching knowledge base..." in real time via stream phase indicator +- **AND** the response includes a RAG sources section: document name, chunk text, and relevance score + +#### Scenario: User expands source citations + +- **WHEN** a RAG-grounded response is displayed +- **THEN** the user can expand source cards to view the original chunk text +- **AND** each card shows which vector store the source came from (when multiple stores are configured) + +#### Scenario: No relevant results found + +- **WHEN** the knowledge base search returns no results above the relevance threshold +- **THEN** the agent indicates it could not find relevant information +- **AND** it answers from general knowledge, noting the limitation + +#### Scenario: Multiple knowledge bases searched + +- **WHEN** multiple vector stores are configured and scoped to the active agent +- **THEN** the search spans all configured vector stores +- **AND** results show which store each source came from diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/streaming-chat/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/streaming-chat/spec.md new file mode 100644 index 0000000000..abec003fc2 --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/streaming-chat/spec.md @@ -0,0 +1,56 @@ +# Streaming Chat + +Real-time streamed conversation with specialist AI agents, including phase indicators, rich rendering, and provider-adaptive behavior. + +## EXISTING Requirements + +### Requirement: Real-Time Streaming with Phase Indicators + +The chat interface streams responses incrementally with visible progress phases. + +#### Scenario: User sends a message and receives streamed response + +- **WHEN** a user submits a message via the chat input +- **THEN** the system sends it to the active AI provider and begins streaming +- **AND** real-time phase indicators show progress: thinking, reasoning, searching, calling tools, generating +- **AND** the response renders incrementally: markdown, code blocks with syntax highlighting, reasoning summary, source citations, and token usage + +#### Scenario: Llama Stack path with router agent handoff + +- **WHEN** a message is sent on the Llama Stack provider path +- **THEN** it routes to the configured default agent +- **AND** a router agent may hand off to a specialist mid-conversation +- **AND** the user sees a handoff divider: "Handed off from [Agent A] to [Agent B]" + +#### Scenario: Kagenti path with mandatory agent selection + +- **WHEN** a message is sent on the Kagenti provider path +- **THEN** the user must have selected an agent from the gallery before sending +- **AND** the chat header shows agent name, streaming/A2A mode, namespace, and health status + +### Requirement: Resilience During Chat + +The chat interface degrades gracefully on errors. + +#### Scenario: Provider goes offline during chat + +- **WHEN** `useStatus` detects the AI provider is unreachable +- **THEN** a `ProviderOfflineBanner` is displayed +- **AND** chat resumes automatically when the provider recovers + +#### Scenario: Agent error during streaming + +- **WHEN** an agent returns an error during a streaming response +- **THEN** an `ErrorCard` is displayed inline within the message +- **AND** the page does not crash (protected by `AugmentErrorBoundary`) +- **AND** the conversation remains navigable + +### Requirement: Conversation Auto-Save + +Conversations are persisted automatically. + +#### Scenario: Successful response triggers auto-save + +- **WHEN** a streaming response completes successfully +- **THEN** the conversation (session and messages) is auto-saved via `ChatSessionService` +- **AND** the session appears in the conversation history panel diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/tasks.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/tasks.md new file mode 100644 index 0000000000..c380a3abcb --- /dev/null +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/tasks.md @@ -0,0 +1,30 @@ +# Tasks: AI Chat & Interaction Experience + +## 1. Composable Extensions (P1) + +- [ ] 1.1 Create `BoostChatPage` routable extension in `plugin.ts` using `chatRouteRef` and `React.lazy(() => import('./components/ChatContainer'))` +- [ ] 1.2 Create `BoostAdminPage` routable extension using `settingsAdminRouteRef` +- [ ] 1.3 Create `BoostAgentStudioPage` routable extension using `agentCreateRouteRef` +- [ ] 1.4 Export new extensions from `src/index.ts` +- [ ] 1.5 Document frontend wiring config for each extension in `dynamic-plugins.yaml` examples + +## 2. Lazy Loading (P1) + +- [ ] 2.1 Replace static imports of Kagenti components in `ChatView.tsx` (lines 31-41) with `React.lazy()` +- [ ] 2.2 Add `React.lazy()` to `AdminLayout.tsx` for each panel group +- [ ] 2.3 Add `` boundaries with loading indicators at each lazy boundary + +## 3. Feature Flags (P1) + +- [ ] 3.1 Add `augment.features` section to frontend `config.d.ts` schema +- [ ] 3.2 Register feature flags with Backstage `featureFlagsApiRef` in `createPlugin` call +- [ ] 3.3 Create `useFeatureFlags` hook that reads from `configApiRef` with `featureFlagsApiRef` overrides +- [ ] 3.4 Gate `agentCreation`, `devSpaces`, `workflowBuilder`, `sandbox`, `observability`, `adminPanel` behind feature flags +- [ ] 3.5 Remove hardcoded `KagentiFeatureFlags` server-side check for sandbox (replace with config flag) + +## 4. Verify + +- [ ] 4.1 Verify `BoostChatPage` renders independently without admin panel code loaded +- [ ] 4.2 Verify feature flags disable features in both app-config and Backstage Settings UI +- [ ] 4.3 Verify each composable extension loads only its own code — no eager cross-extension imports +- [ ] 4.4 Verify initial bundle size meets target (composable extensions, not monolithic) diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/.openspec.yaml b/workspaces/boost/openspec/changes/platform-operations-deployment/.openspec.yaml new file mode 100644 index 0000000000..28882f7998 --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-19 diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/design.md b/workspaces/boost/openspec/changes/platform-operations-deployment/design.md new file mode 100644 index 0000000000..ea647da1ac --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/design.md @@ -0,0 +1,55 @@ +# Design: Platform Operations & Deployment + +## Context + +Boost implements the runtime configuration engine (DB-backed overlay, 25+ keys) with proper architecture from the start, informed by augment's experience. Augment built this as a product feature but accumulated debt: 671 lines of hand-written validators, no documentation of config field scopes, raw `Map<>` caches instead of Backstage `cacheService`, and a 1,500+ line config schema growing without resolution. Boost uses Zod schema-driven validation and `cacheService` from day one. + +## Goals + +- All operational caches use Backstage `cacheService` from day one +- Configuration validation uses Zod schemas as single source of truth from day one +- Every config field documented with scope: `yaml-only`, `db-overridable`, or `db-only` +- No duplicate cache wrappers or hand-written validators + +## Non-Goals + +- Removing the DB-backed dynamic config system (it's a product feature) +- Migrating provider-specific caches (covered in platform-architecture change) +- Migrating catalog entity candidates (covered in agent-creation-discovery change) + +## Decisions + +### Decision 1: Zod schemas derived from config.d.ts + +Replace `configValidation.ts` with Zod schemas that are the single source of truth. The TypeScript `config.d.ts` interface is generated from the Zod schemas (not the other way around). This ensures DB-stored values are validated by the same rules as YAML values. + +### Decision 2: Cache migration order follows traffic and risk + +1. `RuntimeConfigResolver` (cache #1) — highest traffic, 30s TTL, cleanest migration +2. `ConversationRegistry` (cache #8) — add TTL (24h), multi-instance benefit +3. `DocumentSyncService` (cache #9) — multi-instance sync consistency +4. `KagentiProvider` session maps (cache #10) — multi-instance safety +5. `ClientManager` (cache #11) — low risk, singleton pattern +6. `ConfigResolutionService` (cache #14) — eliminate entirely (delegate to #1) +7. `conversationAgents` (cache #15) — new, session-scoped +8. `rateLimiter store` (cache #16) — new, per-window +9. `BackendApprovalStore.pending` (cache #17) — new, request-scoped HITL approvals + +Caches #12 and #13 (toolscope) are migrated via the injectable `CacheAdapter` in the toolscope extraction (covered in agent-creation-discovery change). + +**Note:** Config schema has grown to 1,500+ lines (was 1,393 at original audit). Hand-written validators are 671 lines. Each new feature (agent approval, skills marketplace, token exchange, DevSpaces credentials) adds config keys without Zod migration, increasing eventual cleanup cost. + +### Decision 3: Config field metadata annotation + +Each field in the admin config system is annotated with a `configScope` property: + +- `yaml-only`: only settable in `app-config.yaml` (e.g., database connection, security mode) +- `db-overridable`: settable in YAML with admin panel override (e.g., model name, system prompt) +- `db-only`: only settable via admin panel (e.g., prompt groups, branding) + +This metadata drives both the admin UI (which fields to show) and validation (which writes to accept). + +## Risks + +- **Redis dependency in production:** `cacheService` defaults to in-memory but uses Redis when configured. Deployments without Redis lose multi-instance cache sharing. Mitigated: in-memory mode is functionally identical to current behavior. +- **Schema migration for existing DB values:** Switching to schema-driven validation may reject currently-stored values. Mitigated by running a one-time migration that validates and reports (but doesn't block) existing values. diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/proposal.md b/workspaces/boost/openspec/changes/platform-operations-deployment/proposal.md new file mode 100644 index 0000000000..9e9e2f192f --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/proposal.md @@ -0,0 +1,34 @@ +# Proposal: Platform Operations & Deployment + +## Why + +An AI platform requiring code changes or restarts for configuration changes is unusable in production. Administrators need to deploy cleanly, manage agents and orchestration, configure RAG pipelines, tune 25+ runtime parameters, and white-label the experience — all without touching source code. + +The current runtime configuration engine uses a DB-backed dynamic overlay that is unique across all RHDH plugins and bypasses Backstage's config validation pipeline. The 14 home-grown caches used for operational state (config resolution, session management, content hashes) should migrate to Backstage's `cacheService` for multi-instance safety and Redis backing in production. + +## What Changes + +### Current Capabilities (retroactive documentation) + +- RHDH dynamic plugin (OCI) and Backstage static plugin (npm) deployment +- Agent and orchestration management via admin panel +- RAG knowledge pipeline: document ingestion, vector stores, RAG playground +- Runtime configuration engine: YAML baseline + DB overrides, 25+ keys, 30s cache TTL +- White-label branding: name, logo, colors, welcome screen, featured agents +- Admin onboarding experience + +### Architectural Improvements (from tech debt analysis) + +- Migrate `RuntimeConfigResolver` cache (cache #1) to Backstage `cacheService` +- Migrate `ConversationRegistry` (cache #8), `DocumentSyncService` content hashes (cache #9), and session maps (cache #10) to `cacheService` +- Migrate `ClientManager` (cache #11), `EmbeddingCache` (cache #12), `SessionCache` (cache #13), `ConfigResolutionService` (cache #14) to `cacheService` +- Replace hand-written config validators (`configValidation.ts`, 668 lines) with schema-driven validation +- Add config-driven feature flags for frontend +- Document YAML-only vs. DB-overridable config fields + +## Impact + +- `plugins/augment-backend/src/services/RuntimeConfigResolver.ts` — cacheService migration +- `plugins/augment-backend/src/services/configValidation.ts` — replace with schema-driven validation +- `plugins/augment-backend/src/providers/` — remaining cache migrations +- `plugins/augment/src/config.d.ts` — feature flags schema addition diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md new file mode 100644 index 0000000000..2a28d081a6 --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md @@ -0,0 +1,82 @@ +# Operational Caching via Backstage cacheService + +All operational caches use Backstage `cacheService` from day one — no raw `Map<>` caches. This provides Redis-backed caching in production, consistent TTL semantics, and multi-instance safety. The cache inventory below is derived from augment's 17-cache analysis to ensure boost covers all the same operational caching needs with proper architecture. + +NOTE: Provider-specific caches (#2-#7) are covered in the platform-architecture change. Catalog entity candidate caches are covered in the agent-creation-discovery change. This spec covers the remaining operational caches (#1, #8-#14) plus 3 new caches identified in the May 26 analysis (#15-#17). + +**Full cache inventory (17 caches, 2 migrated, 15 remaining):** + +| # | Cache | Location | Status | Owner | +| --- | ---------------------------------- | ------------------------------ | --------------- | ---------------- | +| 1 | RuntimeConfigResolver | services/ | **This spec** | Platform ops | +| 2 | KagentiAgentCardCache | providers/kagenti/ | **Migrated ✓** | Platform arch | +| 3 | KagentiProvider.\_modelsCache | providers/kagenti/ | **Migrated ✓** | Platform arch | +| 4 | ResponsesApiProvider.\_modelsCache | providers/llamastack/ | Platform arch | Platform arch | +| 5 | McpAuthService tokens | providers/llamastack/auth/ | Platform arch | Platform arch | +| 6 | KeycloakTokenManager | providers/kagenti/client/ | Platform arch | Platform arch | +| 7 | BackendToolExecutor | providers/responses-api/tools/ | Platform arch | Platform arch | +| 8 | ConversationRegistry | providers/responses-api/ | **This spec** | Platform ops | +| 9 | DocumentSyncService | providers/responses-api/ | **This spec** | Platform ops | +| 10 | KagentiProvider session maps | providers/kagenti/ | **This spec** | Platform ops | +| 11 | ClientManager | providers/llamastack/ | **This spec** | Platform ops | +| 12 | EmbeddingCache (toolscope) | services/toolscope/ | Agent discovery | Via CacheAdapter | +| 13 | SessionCache (toolscope) | services/toolscope/ | Agent discovery | Via CacheAdapter | +| 14 | ConfigResolutionService | providers/llamastack/config/ | **This spec** | Platform ops | +| 15 | conversationAgents | OpenAIAgentsOrchestrator.ts | **This spec** | Platform ops | +| 16 | rateLimiter store | middleware/rateLimiter.ts | **This spec** | Platform ops | +| 17 | BackendApprovalStore.pending | responses-api/tools/ | **This spec** | Platform ops | + +## ADDED Requirements + +### Requirement: RuntimeConfigResolver Caching + +The highest-traffic cache uses Backstage cacheService. + +#### Scenario: Config cache uses cacheService + +- **WHEN** `RuntimeConfigResolver` caches the merged effective config +- **THEN** it uses `coreServices.cache` with `cache.set('effective-config', value, { ttl: '30s' })` +- **AND** immediate invalidation on write is preserved via `cache.delete('effective-config')` +- **AND** in production with Redis, this cache is shared across multiple backend instances + +### Requirement: Conversation and Session Caching + +Session correlation and conversation maps use cacheService. + +#### Scenario: ConversationRegistry uses cacheService + +- **WHEN** `ConversationRegistry` maps response IDs to conversation IDs (currently cache #8, no TTL, max 10,000) +- **THEN** it uses `coreServices.cache` with a reasonable TTL (e.g., 24h for conversation mapping) +- **AND** max-size eviction is handled by the cache backend (no manual tracking) + +#### Scenario: Kagenti session maps use cacheService + +- **WHEN** `KagentiProvider` correlates sessions (currently cache #10, no TTL, max 10,000) +- **THEN** it uses `coreServices.cache` with a reasonable TTL +- **AND** multi-instance safety is achieved via Redis backing + +### Requirement: Document Sync Hash Caching + +Content hashes for change detection use cacheService. + +#### Scenario: DocumentSyncService uses cacheService + +- **WHEN** `DocumentSyncService` tracks content hashes for change detection (currently cache #9, no TTL, max 10,000) +- **THEN** it uses `coreServices.cache` with no expiry (or very long TTL) +- **AND** hashes are shared across instances for consistent sync behavior + +### Requirement: Client and Config Service Caching + +Singleton client instances and config wrappers use cacheService. + +#### Scenario: ClientManager uses cacheService + +- **WHEN** `ClientManager` caches HTTP client instances (currently cache #11, identity-based, max 1) +- **THEN** it uses `coreServices.cache` for client instance caching +- **AND** identity-based keying is preserved + +#### Scenario: ConfigResolutionService delegates to RuntimeConfigResolver cache + +- **WHEN** `ConfigResolutionService` wraps RuntimeConfigResolver (currently cache #14) +- **THEN** it delegates entirely to the migrated RuntimeConfigResolver cache +- **AND** the duplicate wrapper cache is eliminated diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/deployment/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/deployment/spec.md new file mode 100644 index 0000000000..ea3a60c3de --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/deployment/spec.md @@ -0,0 +1,33 @@ +# Plugin Deployment + +Install and configure Augment in an RHDH or vanilla Backstage instance via two deployment paths. + +## EXISTING Requirements + +### Requirement: RHDH Dynamic Plugin Deployment + +Deploy Augment as a dynamic plugin with zero code changes. + +#### Scenario: Dynamic plugin installation + +- **WHEN** the administrator configures `dynamic-plugins.override.yaml` with Augment OCI plugin references +- **THEN** RHDH loads frontend, backend, and common packages dynamically via Scalprum +- **AND** no code changes or application rebuilds are required +- **AND** Augment appears as a sidebar entry in RHDH + +#### Scenario: Dynamic plugin configuration + +- **WHEN** the administrator sets up `app-config.yaml` with Augment configuration +- **THEN** provider settings, security mode, and base URLs are configured +- **AND** the plugin validates configuration at startup against the declared schema + +### Requirement: Backstage Static Plugin Deployment + +Deploy Augment as a traditional Backstage plugin with npm packages. + +#### Scenario: Static plugin installation + +- **WHEN** the developer installs `@augment/plugin-augment`, `@augment/plugin-augment-backend`, and `@augment/plugin-augment-common` +- **THEN** frontend route, sidebar entry, icon, and backend plugin are registered manually +- **AND** `app-config.yaml` is configured +- **AND** the application is rebuilt and deployed diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/rag-pipelines/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/rag-pipelines/spec.md new file mode 100644 index 0000000000..d8c9ca75f0 --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/rag-pipelines/spec.md @@ -0,0 +1,56 @@ +# RAG Knowledge Pipelines + +Ingest customer documentation into vector stores so agents can ground their answers in real data. + +## EXISTING Requirements + +### Requirement: Document Ingestion Pipeline + +Multi-source document fetching with change detection and chunking. + +#### Scenario: GitHub repository ingestion + +- **WHEN** the admin adds a GitHub repository as a document source +- **THEN** the pipeline fetches content (supporting public/private repos, path filters, glob patterns) +- **AND** content is chunked and pushed to the configured vector store + +#### Scenario: URL and file upload ingestion + +- **WHEN** the admin adds a URL or uploads files via `IngestDropZone` +- **THEN** web pages are fetched and chunked, or uploaded files are processed +- **AND** all content is pushed to the vector store + +#### Scenario: Change detection on subsequent syncs + +- **WHEN** a sync schedule triggers (e.g., hourly) after initial ingestion +- **THEN** `DocumentSyncService` uses content hashes to detect changes +- **AND** only changed files are re-ingested +- **AND** deleted files are removed from the store + +### Requirement: Vector Store Management + +Create, configure, and scope vector stores to specific agents. + +#### Scenario: Create vector store with search mode + +- **WHEN** the admin creates a vector store via `KBCreateStore` +- **THEN** they configure search mode: semantic, keyword, or hybrid +- **AND** multiple stores can be created for different domains + +#### Scenario: Per-agent vector store scoping + +- **WHEN** the admin configures an agent +- **THEN** specific `vectorStoreIds` can be assigned +- **AND** the agent only searches scoped vector stores during RAG queries + +### Requirement: RAG Playground + +Test retrieval quality before deploying to production. + +#### Scenario: RAG quality testing + +- **WHEN** the admin opens the RAG playground (`KBRagTest`) +- **THEN** they can submit test queries via `RagQueryForm` +- **AND** `RagResultsTable` shows retrieved chunks with `ChunkCard`, `ScoreBar`, and relevance scores +- **AND** thresholds are adjustable to tune precision vs. recall +- **AND** `GeneratedAnswerCard` shows the answer that would be generated from the retrieved context diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md new file mode 100644 index 0000000000..385c80d8c7 --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md @@ -0,0 +1,136 @@ +# Runtime Configuration Engine + +Change Augment's behavior at runtime — model, system prompt, tools, caps, and more — without restarting. + +## EXISTING Requirements + +### Requirement: Two-Layer Configuration Resolution + +YAML baseline + database overrides with automatic fallback. + +#### Scenario: Config resolution precedence + +- **WHEN** a runtime config value is requested +- **THEN** `RuntimeConfigResolver` checks `AdminConfigService` (DB) first +- **AND** if a DB override exists, it takes precedence over the YAML baseline +- **AND** if no DB override exists, the YAML baseline value is used +- **AND** resolved values are cached with 30-second TTL + +#### Scenario: Config write invalidation + +- **WHEN** an admin writes a config value via the admin panel +- **THEN** `AdminConfigService` persists it to the `augment_admin_config` table +- **AND** the `RuntimeConfigResolver` cache is immediately invalidated +- **AND** the new value takes effect within seconds (not waiting for TTL expiry) + +#### Scenario: DB override removed restores YAML baseline + +- **WHEN** a DB override is removed via the admin panel +- **THEN** the YAML baseline value is restored as the effective value + +### Requirement: Configurable Categories + +25+ runtime-configurable keys across multiple categories. + +#### Scenario: Model connection configuration + +- **WHEN** the admin opens the Model Connection panel +- **THEN** base URL, model name, and connection test are configurable +- **AND** changes take effect without restart + +#### Scenario: System prompt configuration + +- **WHEN** the admin edits the system prompt +- **THEN** they can edit directly or use LLM-assisted prompt generation via `GeneratePromptForm` +- **AND** the updated prompt applies to subsequent conversations + +#### Scenario: Agent-level configuration + +- **WHEN** the admin configures a specific agent +- **THEN** per-agent model, temperature, max tokens, tool choice, MCP server subsets, and vector store IDs are configurable + +### Requirement: Admin Onboarding + +First-time administrators receive guided setup. + +#### Scenario: Admin onboarding card on first visit + +- **WHEN** an admin visits the admin panel for the first time +- **THEN** `AdminOnboardingCard` provides guided setup steps +- **AND** each step links to the relevant configuration panel + +## MODIFIED Requirements + +### Requirement: Schema-Driven Config Validation + +Hand-written validators are replaced with schema-derived validation. + +#### Scenario: Validation from single source of truth + +- **WHEN** a config value is written via the admin panel +- **THEN** it is validated using a schema derived from the same source as `config.d.ts` (Zod or JSON Schema) +- **AND** the 668-line `configValidation.ts` hand-written validators are eliminated +- **AND** DB-stored values cannot bypass the same constraints that YAML values must satisfy + +#### Scenario: YAML-only vs DB-overridable documentation + +- **WHEN** a deployer reviews the config schema +- **THEN** each field is documented as YAML-only, DB-overridable, or DB-only +- **AND** the admin UI only shows DB-overridable fields + +### Requirement: New Config Categories + +New features require additional runtime configuration fields. + +#### Scenario: Agent approval configuration + +- **WHEN** the admin configures agent approval settings +- **THEN** the following fields are available: + | Field | Scope | Description | + |---|---|---| + | `augment.agentApproval.mode` | db-overridable | Built-in or SonataFlow-managed approval | + | `augment.agentApproval.sonataflow.endpoint` | yaml-only | SonataFlow workflow endpoint | + +#### Scenario: Skills marketplace configuration + +- **WHEN** the admin configures skills marketplace +- **THEN** the following fields are available: + | Field | Scope | Description | + |---|---|---| + | `augment.skillsMarketplace.endpoint` | yaml-only | Skills catalog backend URL | + | `augment.skillsMarketplace.enabled` | db-overridable | Enable/disable skills marketplace | + +#### Scenario: Token exchange configuration + +- **WHEN** the admin configures per-user Kagenti auth +- **THEN** the following fields are available: + | Field | Scope | Description | + |---|---|---| + | `augment.kagenti.auth.tokenExchange.enabled` | yaml-only | Enable RFC 8693 token exchange | + | `augment.kagenti.auth.tokenExchange.audience` | yaml-only | Target audience for exchanged token | + | `augment.kagenti.auth.tokenExchange.userTokenHeader` | yaml-only | Header containing user OIDC token | + +#### Scenario: Credential encryption + +- **WHEN** sensitive credentials (DevSpaces tokens) are stored +- **THEN** they are encrypted at rest in the `augment_admin_config` table +- **AND** the admin UI masks credential values + +### Requirement: Config Schema Versioning + +DB-stored config values survive schema changes across upgrades. + +#### Scenario: Schema evolution on startup + +- **WHEN** boost starts and the Zod schema has changed since the last run +- **THEN** a startup migration validates all existing DB values against the current schema +- **AND** values that pass validation are kept as-is +- **AND** values that fail validation are logged with details (field, stored value, validation error) +- **AND** failed values are removed from the DB override, restoring the YAML baseline for those fields +- **AND** the admin is notified of removed overrides via the admin onboarding/status panel + +#### Scenario: Schema version tracking + +- **WHEN** boost writes a config value to the DB +- **THEN** the schema version is stored alongside the value +- **AND** on startup, values from older schema versions are re-validated against the current schema diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/white-label/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/white-label/spec.md new file mode 100644 index 0000000000..78ec5a3bb4 --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/white-label/spec.md @@ -0,0 +1,38 @@ +# White-Label Branding + +Customize the Augment experience to match the organization's brand — all at runtime, no deployment required. + +## EXISTING Requirements + +### Requirement: Appearance Customization + +Application name, logo, and color theme are configurable at runtime. + +#### Scenario: Brand customization via admin panel + +- **WHEN** the admin opens `BrandingPanel` → `AppearanceSection` +- **THEN** application name, logo, and color theme (from presets or custom) are configurable +- **AND** changes apply immediately — users see updated branding without page refresh + +### Requirement: Prompt Group Management + +Welcome screen prompt groups are configurable with rich editing. + +#### Scenario: Edit prompt groups + +- **WHEN** the admin opens `PromptsPanel` +- **THEN** `GroupEditor` and `CardEditor` allow creating and editing prompt groups +- **AND** each group has icons (via `IconPicker`), colors (via `ColorPicker`), and suggested prompts +- **AND** groups can be reordered +- **AND** `LivePreview` shows real-time rendering of changes + +### Requirement: Chat Experience Configuration (Kagenti) + +Featured agents and conversation starters are configurable. + +#### Scenario: Configure featured agents and starters + +- **WHEN** the admin opens `ChatExperiencePanel` +- **THEN** featured agents for the welcome screen strip are configurable +- **AND** per-agent conversation starters are configurable +- **AND** changes apply at runtime diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/tasks.md b/workspaces/boost/openspec/changes/platform-operations-deployment/tasks.md new file mode 100644 index 0000000000..c4ba78ccd0 --- /dev/null +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/tasks.md @@ -0,0 +1,40 @@ +# Tasks: Platform Operations & Deployment + +## 1. Operational Caches — cacheService from Day One (P1) + +- [ ] 1.1 All backend services depend on `coreServices.cache` — no raw `Map<>` caches anywhere +- [ ] 1.2 `RuntimeConfigResolver`: `cache.set('effective-config', value, { ttl: '30s' })` with immediate invalidation via `cache.delete()` +- [ ] 1.3 `ConversationRegistry`: 24h TTL via cacheService +- [ ] 1.4 `DocumentSyncService` content hashes: cacheService with long TTL +- [ ] 1.5 Provider session maps: cacheService with session-appropriate TTL +- [ ] 1.6 `ClientManager`: identity-keyed cacheService +- [ ] 1.7 Config resolution: single cache layer (no duplicate wrapper) +- [ ] 1.8 Conversation-agent maps: session-scoped cacheService +- [ ] 1.9 Rate limiter state: per-window cacheService +- [ ] 1.10 HITL approval state: request-scoped cacheService + +## 2. Schema-Driven Config Validation — Zod from Day One (P1) + +- [ ] 2.1 Define Zod schemas for all admin-configurable fields as single source of truth +- [ ] 2.2 Generate `config.d.ts` types from Zod schemas +- [ ] 2.3 Validate all config writes (YAML and DB) via Zod `.parse()` — no hand-written validators +- [ ] 2.4 Annotate each field with `configScope`: `yaml-only`, `db-overridable`, or `db-only` +- [ ] 2.5 Add Zod schemas for new config fields: agentApproval, skillsMarketplace, tokenExchange, DevSpaces credentials +- [ ] 2.6 Update admin UI to only show DB-overridable and DB-only fields +- [ ] 2.7 Create one-time migration script that validates existing DB values against new schemas +- [ ] 2.8 Implement credential encryption for sensitive DB-stored values (DevSpaces tokens) +- [ ] 2.9 Implement schema version tracking: store schema version alongside DB values, re-validate on startup +- [ ] 2.10 Implement startup migration: validate existing DB values against current Zod schema, remove invalid overrides with logging + +## 3. Config Field Documentation (P2) + +- [ ] 3.1 Document all 25+ configurable keys with their scope (YAML-only vs DB-overridable) +- [ ] 3.2 Add schema documentation comments to Zod schema definitions + +## 4. Verify + +- [ ] 4.1 Verify RuntimeConfigResolver cache works with both in-memory and Redis backends +- [ ] 4.2 Verify config write → immediate invalidation → new value served in under 1 second +- [ ] 4.3 Verify Zod validation rejects the same invalid values that hand-written validators did +- [ ] 4.4 Verify existing DB values pass Zod validation (migration script) +- [ ] 4.5 Verify multi-instance cache sharing works with Redis in production config diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/.openspec.yaml b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/.openspec.yaml new file mode 100644 index 0000000000..28882f7998 --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-19 diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/design.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/design.md new file mode 100644 index 0000000000..7ce73d16f8 --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/design.md @@ -0,0 +1,94 @@ +# Design: Pluggable AI Platform Architecture + +## Context + +Boost implements the provider abstraction as modular RHDH dynamic plugins from the start, informed by augment's experience. Augment had a clean provider abstraction design (`AgenticProvider` interface, extension point registration, hot-swap lifecycle) but locked everything inside one monolithic plugin with 17 raw `Map<>` caches, 18+ provider ID string checks, and 559 lines of Kagenti-specific types in the common package. Boost avoids all of these patterns by building modular, capability-gated, and cacheService-backed from day one. + +## Goals + +- Cross-plugin AI provider consumption via Backstage `serviceRef` from day one +- Each provider as an independent RHDH dynamic plugin from day one +- All caches use Backstage `cacheService` from day one +- No cross-provider coupling — providers are isolated modules +- Capability-based feature gating in frontend — no provider ID string checks + +## Non-Goals + +- Changing the `AgenticProvider` interface contract +- Modifying chat interaction behavior or message rendering +- Rewriting the ADK orchestration library +- Creating catalog entities for models/agents (covered in agent-creation-discovery change) +- Per-user token exchange (covered in security-safety-governance change) + +## Decisions + +### Decision 1: serviceRef lives in augment-common + +The `augmentAiProviderServiceRef` is exported from `@augment/plugin-augment-common` alongside the `AgenticProvider` interface types. This allows both backend consumers and frontend type consumers to reference the interface from a single package without depending on the full backend. + +```typescript +// plugins/augment-common/src/services.ts +import { createServiceRef } from '@backstage/backend-plugin-api'; +import type { AgenticProvider } from './types'; + +export const augmentAiProviderServiceRef = createServiceRef({ + id: 'augment.ai-provider', + scope: 'plugin', +}); +``` + +The core `augment-backend` plugin registers the default factory via `createServiceFactory` that resolves to the `ProviderManager`'s active provider. + +### Decision 2: Providers as backend modules, not separate plugins + +Each provider is a `createBackendModule` (not `createBackendPlugin`), because providers extend the augment plugin — they don't stand alone. Module IDs: `llamastack`, `kagenti`. + +This follows the Backstage pattern established by `plugin-catalog-backend-module-*` and `plugin-kubernetes-backend-module-*`. + +### Decision 3: cacheService replaces ALL provider-internal Map<> caches + +17 caches identified across the codebase; only 2 migrated to date. All providers must use `cacheService` consistently — no asymmetry between Kagenti (cacheService) and Llama Stack (raw Map). Provider modules depend on `coreServices.cache` and use `cache.withOptions()` for namespace isolation: + +| Current Cache | Location | Current State | Migration Target | +| ---------------------------------- | -------------------------------- | ------------------------ | ------------------------------------------------------------------- | +| RuntimeConfigResolver | `services/` | raw Map, 30s TTL | `cache.withOptions({ defaultTtl: '30s' })` + immediate invalidation | +| KagentiAgentCardCache | `providers/kagenti/` | **migrated ✓** | — | +| KagentiProvider.\_modelsCache | `providers/kagenti/` | **migrated ✓** | — | +| ResponsesApiProvider.\_modelsCache | `providers/llamastack/` | raw object | `cache.withOptions({ defaultTtl: '60s' })` — eliminate asymmetry | +| McpAuthService tokens | `providers/llamastack/auth/` | raw Map | `cache.set(key, token, { ttl: expiresIn })` | +| KeycloakTokenManager | `providers/kagenti/client/` | raw Map | `cache.set(key, token, { ttl: expiresIn })` | +| BackendToolExecutor | `providers/responses-api/tools/` | raw Map, unbounded | `cache.withOptions({ defaultTtl: '5m' })` | +| ConversationRegistry | `providers/responses-api/` | raw Map, no TTL, 10k max | `cache.withOptions({ defaultTtl: '24h' })` | +| DocumentSyncService | `providers/responses-api/` | raw Map, no TTL, 10k max | cache with no expiry (content hash tracking) | +| KagentiProvider session maps | `providers/kagenti/` | raw Map, no TTL, 10k max | `cache.withOptions()` with session TTL | +| ClientManager | `providers/llamastack/` | raw Map | identity-keyed cache | +| EmbeddingCache (toolscope) | `services/toolscope/` | raw Map, unbounded | Via injectable `CacheAdapter` | +| SessionCache (toolscope) | `services/toolscope/` | raw Map, 1h TTL, 1k max | Via injectable `CacheAdapter` | +| ConfigResolutionService | `providers/llamastack/config/` | wrapper | Delegates to migrated RuntimeConfigResolver | +| conversationAgents | `OpenAIAgentsOrchestrator.ts` | new raw Map | session-scoped cache | +| rateLimiter store | `middleware/rateLimiter.ts` | new raw Map | per-window cache | +| BackendApprovalStore.pending | `responses-api/tools/` | new raw Map | request-scoped cache | + +Backstage's cache layer handles max-size eviction and Redis backing in production. + +### Decision 4: Capability checks via ProviderCapabilities + +Frontend replaces all `providerId === 'kagenti'` checks with capability queries. The `ProviderCapabilities` interface already exists and is partially used. The migration: + +```typescript +// Before (coupled to provider identity) +const isFullProvider = liveStatus?.providerId === 'kagenti'; + +// After (coupled to capabilities) +const hasAgentCatalog = capabilities?.agentCatalog === true; +const hasNamespaceScoping = capabilities?.namespaceScoping === true; +``` + +### Decision 5: Kagenti-specific types extracted from augment-common + +Currently 559 lines (60+ interfaces) of Kagenti-only types are exported from `augment-common`, violating the type package boundary. These must be moved to the Kagenti provider module, with only the shared `AgenticProvider` interface and conversation types remaining in `augment-common`. + +## Risks + +- **Cache key collisions:** Mitigated by using `cache.withOptions()` which namespace-scopes keys per plugin/module. +- **Provider module interdependency:** Provider modules must not import from each other. Shared utilities live in `augment-common` or standalone packages. Boost enforces this from the start. diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/proposal.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/proposal.md new file mode 100644 index 0000000000..d2834d4df7 --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/proposal.md @@ -0,0 +1,35 @@ +# Proposal: Pluggable AI Platform Architecture + +## Why + +Augment must be the experience layer above any AI platform, not a client of one. Enterprise customers run different AI backends — and they change their minds. The architecture must support pluggable providers, runtime hot-swap, normalized streaming, and multi-agent orchestration without vendor lock-in. + +The current implementation achieves the product goals but has critical architectural gaps that limit reusability and composability: no Backstage `serviceRef` for cross-plugin AI provider consumption, providers embedded inside one monolithic backend plugin rather than packaged as separate Backstage modules, and shared types scattered across provider-specific directories. + +## What Changes + +### Current Capabilities (retroactive documentation) + +- Provider abstraction via `AgenticProvider` interface with required (`chat`, `chatStream`) and optional capabilities +- `ProviderDescriptor` declares ID, name, and capability matrix +- Backstage extension point (`augmentProviderExtensionPoint`) for provider registration +- Runtime hot-swap via `ProviderManager.switchProvider()` with rollback on failure +- Normalized streaming protocol (`NormalizedStreamEvent`) for frontend uniformity +- Two built-in providers: `ResponsesApiProvider` (Llama Stack) and `KagentiProvider` (Kagenti A2A) +- Frontend capability-based feature gating adapting UI per provider + +### Architectural Improvements (from tech debt analysis) + +- Create `augmentAiProviderServiceRef` so other plugins can consume the active AI provider +- Move `AgenticProvider` interface and conversation types to `augment-common` +- Package `ResponsesApiProvider` and `KagentiProvider` as separate Backstage backend modules +- Replace provider ID checks (`providerId === 'kagenti'`) with capability-based checks +- Extract `responses-api/` toolkit and `toolscope/` as standalone packages + +## Impact + +- `plugins/augment-common/` — new types and serviceRef +- `plugins/augment-backend/src/providers/` — provider extraction +- `plugins/augment-backend/src/plugin.ts` — serviceRef registration +- New packages: `plugin-augment-backend-module-llamastack`, `plugin-augment-backend-module-kagenti` +- `plugins/augment/src/` — replace provider ID checks with capability checks diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/multi-agent-orchestration/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/multi-agent-orchestration/spec.md new file mode 100644 index 0000000000..c6d829b27c --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/multi-agent-orchestration/spec.md @@ -0,0 +1,56 @@ +# Multi-Agent Orchestration + +Config-driven multi-agent orchestration without writing code. Llama Stack agents are defined in YAML and assembled into handoff chains. Kagenti agents are framework-neutral K8s workloads discovered via A2A protocol. + +## EXISTING Requirements + +### Requirement: Llama Stack Config-Driven Agents + +Agents are defined declaratively and assembled into orchestration chains. + +#### Scenario: Agent defined in YAML configuration + +- **WHEN** an agent is defined in YAML or admin config with name, instructions, tools, model, temperature, and handoffs +- **THEN** `ResponsesApiCoordinator` assembles it into a `POST /v1/responses` call against the Llama Stack endpoint +- **AND** per-agent config includes: model, temperature, max tokens, tool choice, MCP server subsets, and vector store IDs + +#### Scenario: Router agent delegates to specialists + +- **WHEN** a router agent is configured as the default entry point with handoff targets +- **THEN** `ResponsesApiCoordinator` generates `transfer_to_{agent}` functions for handoff routing +- **AND** the router delegates to specialist agents mid-conversation while maintaining shared conversation context +- **AND** the user sees a handoff divider in the chat UI + +#### Scenario: Agents-as-tools pattern + +- **WHEN** an agent is configured with `call_{agent}` tool references +- **THEN** the manager agent can invoke specialist agents as tools +- **AND** the manager retains control of the conversation after the specialist returns + +### Requirement: Kagenti Framework-Neutral Agent Operations + +Agents built in any framework are accessible via RHDH through the A2A protocol. + +#### Scenario: Kagenti provider discovers agents via A2A + +- **WHEN** agents are deployed as K8s workloads in a Kagenti-managed namespace +- **THEN** `KagentiProvider` discovers them via the A2A protocol +- **AND** `KagentiApiClient` uses Keycloak OAuth2, retry logic, and namespace-scoped API calls +- **AND** agents appear in the gallery with auto-detected capabilities + +#### Scenario: Namespace-scoped multi-tenancy + +- **WHEN** multiple namespaces are configured in the Kagenti backend +- **THEN** agents are scoped to their namespace with backend-enforced allowlists +- **AND** the namespace picker in the admin UI filters the agent catalog accordingly + +### Requirement: ADK Orchestration Library + +The `@augment-adk/augment-adk` library handles agent continuity, turn counting, handoff logic, and tool execution. + +#### Scenario: ADK manages agent turn lifecycle + +- **WHEN** a chat interaction spans multiple agent turns +- **THEN** the ADK library tracks turn count against configured limits +- **AND** it manages handoff transitions between agents +- **AND** it coordinates tool execution within agent turns diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/normalized-streaming/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/normalized-streaming/spec.md new file mode 100644 index 0000000000..d602254682 --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/normalized-streaming/spec.md @@ -0,0 +1,38 @@ +# Normalized Streaming Protocol + +One event contract between all backend providers and the frontend. Each provider maps its native events to `NormalizedStreamEvent` so the frontend works identically regardless of active backend. + +## EXISTING Requirements + +### Requirement: NormalizedStreamEvent Union Type + +A single union type in the common package covers all streaming event categories. + +#### Scenario: Event categories cover full agent interaction lifecycle + +- **WHEN** a provider emits streaming events during a chat interaction +- **THEN** each native event is mapped to one of the `NormalizedStreamEvent` discriminated union members +- **AND** the union covers: text deltas, reasoning, tool calls, RAG results, handoffs, approvals, forms, auth, artifacts, citations, completion, and errors + +#### Scenario: Llama Stack stream normalization + +- **WHEN** the `ResponsesApiProvider` receives SSE events from Llama Stack +- **THEN** `normalizeLlamaStackEvent()` maps each event to the corresponding `NormalizedStreamEvent` +- **AND** multi-agent handoff events produce `stream.handoff` normalized events with source and target agent identifiers + +#### Scenario: Kagenti stream normalization + +- **WHEN** the `KagentiProvider` receives A2A `TaskStatusUpdateEvent` or `TaskArtifactUpdateEvent` +- **THEN** `KagentiStreamNormalizer` maps them to `NormalizedStreamEvent` +- **AND** A2A task state transitions map to appropriate stream lifecycle events (start, progress, completion) + +### Requirement: Frontend Stream Processing + +The frontend processes normalized events identically regardless of provider. + +#### Scenario: StreamingMessage reducer handles all event types + +- **WHEN** an SSE event arrives at the frontend via `sseStreaming.ts` +- **THEN** `StreamingMessage.reducer` processes it based on the `NormalizedStreamEvent` discriminator +- **AND** `useStreamingStateBatching` batches rapid events for performant rendering +- **AND** `VirtualizedMessageList` renders the accumulated state diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-abstraction/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-abstraction/spec.md new file mode 100644 index 0000000000..a53167af58 --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-abstraction/spec.md @@ -0,0 +1,73 @@ +# Provider Abstraction + +Augment abstracts AI platform backends behind a pluggable provider interface, enabling any AI platform to be integrated without forking the plugin. + +## EXISTING Requirements + +### Requirement: AgenticProvider Interface + +The `AgenticProvider` interface defines the contract between Augment and any AI platform backend. Chat and streaming are required capabilities; RAG, safety, evaluation, and conversation management are optional capability objects. + +#### Scenario: Provider implements required capabilities + +- **WHEN** a provider is registered with `augmentProviderExtensionPoint` +- **THEN** it must implement `chat()` and `chatStream()` methods +- **AND** it must provide a `ProviderDescriptor` declaring its ID, name, and supported capabilities + +#### Scenario: Provider declares optional capabilities + +- **WHEN** a provider supports RAG, safety, evaluation, or conversation management +- **THEN** it exposes those as optional capability objects on the `AgenticProvider` interface +- **AND** the frontend gates features based on the declared capability matrix + +### Requirement: Extension Point Registration + +Providers register via a Backstage extension point, requiring zero Augment source code modification. + +#### Scenario: External provider module registers via extension point + +- **WHEN** a Backstage backend module depends on `augmentProviderExtensionPoint` +- **THEN** it calls `addProvider()` to register its `AgenticProviderFactory` +- **AND** the provider appears in the admin panel's provider switcher on next startup + +#### Scenario: Placeholder provider registration + +- **WHEN** a provider factory is registered with `implemented: false` +- **THEN** it appears in the admin panel as a future placeholder +- **AND** attempting to switch to it returns a descriptive error + +## ADDED Requirements + +### Requirement: AI Provider Service Ref for Cross-Plugin Consumption + +Other Backstage plugins must be able to consume the active AI provider via Backstage's dependency injection, not just register providers. + +#### Scenario: External plugin consumes active AI provider + +- **WHEN** a Backstage plugin declares a dependency on `augmentAiProviderServiceRef` +- **THEN** it receives the currently active `AgenticProvider` instance +- **AND** it can call `chat()`, `chatStream()`, and any declared optional capabilities +- **AND** if the active provider is hot-swapped, the consuming plugin receives the new provider on next request + +#### Scenario: Service ref declared in augment-common + +- **WHEN** the `augmentAiProviderServiceRef` is created via `createServiceRef` from `@backstage/backend-plugin-api` +- **THEN** it is exported from the `augment-common` package (not `augment-backend`) +- **AND** its type parameter is the `AgenticProvider` interface +- **AND** its ID follows the pattern `augment.ai-provider` + +### Requirement: Shared Types in Common Package + +Provider interfaces and conversation types must live in the common package so both frontend and backend can consume them without circular dependencies. + +#### Scenario: AgenticProvider types moved to common + +- **WHEN** the `AgenticProvider` interface, `ProviderDescriptor`, `ProviderCapabilities`, and `NormalizedStreamEvent` types are needed +- **THEN** they are imported from `@augment/plugin-augment-common` +- **AND** provider-specific types (e.g., `LlamaStackConfig`, `KagentiConfig`) remain in their respective provider modules — not in the common package + +#### Scenario: Conversation types consolidated + +- **WHEN** conversation types (`ConversationSummary`, `ConversationDetails`, `InputItem`) are needed +- **THEN** they are imported from `@augment/plugin-augment-common` +- **AND** they are no longer defined inside `providers/llamastack/conversationTypes.ts` diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-hot-swap/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-hot-swap/spec.md new file mode 100644 index 0000000000..1391807d88 --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-hot-swap/spec.md @@ -0,0 +1,56 @@ +# Provider Hot-Swap + +Switch AI platform providers at runtime without downtime or data loss. The system starts the new provider, validates it, swaps the active pointer, and shuts down the old — with automatic rollback on failure. + +## EXISTING Requirements + +### Requirement: Backend Hot-Swap Lifecycle + +`ProviderManager.switchProvider()` implements a safe swap sequence. + +#### Scenario: Successful provider switch + +- **WHEN** the administrator selects a different provider in the admin panel +- **THEN** `ProviderManager` starts the new provider and fully initializes it +- **AND** on successful initialization, it atomically swaps the active provider pointer +- **AND** it shuts down the old provider after the swap completes + +#### Scenario: Failed provider switch with rollback + +- **WHEN** the new provider fails to initialize during a switch attempt +- **THEN** the system rolls back to the previous provider automatically +- **AND** an error notification is shown to the administrator +- **AND** the previous provider continues serving requests without interruption + +### Requirement: Frontend Provider Change Adaptation + +The frontend detects provider changes and performs a full state reset. + +#### Scenario: Chat state reset on provider change + +- **WHEN** the frontend detects a `providerId` change +- **THEN** it cancels any active stream +- **AND** resets the conversation and clears messages +- **AND** resets agent selection and clears input +- **AND** triggers `onNewChat()` + +#### Scenario: UI adapts per provider capabilities + +- **WHEN** the active provider changes +- **THEN** the welcome screen adapts (gallery strip for Kagenti, prompt groups for Llama Stack) +- **AND** agent selection behavior adapts (mandatory for Kagenti, free-form for Llama Stack) +- **AND** the admin sidebar adapts (KagentiSidebar with 8 panels vs CommandCenterHeader with 3 panels) +- **AND** conversation history re-scopes to the new `providerId` + +## MODIFIED Requirements + +### Requirement: Capability-Driven Rendering Replaces Provider ID Checks + +Frontend layout decisions must use the `ProviderCapabilities` interface, not provider identity strings. + +#### Scenario: Layout adapts via capabilities not provider ID + +- **WHEN** the frontend determines which UI elements to show +- **THEN** it queries the active provider's `ProviderCapabilities` object +- **AND** it does NOT check `providerId === 'kagenti'` or any other provider identity string +- **AND** the pattern already used in `ModelToolsPanel` (filtering tabs by capability) is extended to `AdminLayout`, `ChatView`, and `ChatHeader` diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md new file mode 100644 index 0000000000..43ae19fab4 --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md @@ -0,0 +1,81 @@ +# Provider Packaging as Backstage Modules + +Each AI platform provider must be packaged as an independent Backstage backend module, following RHDH dynamic plugin conventions. This enables deployers to install only the providers they need and allows providers to evolve independently. + +## ADDED Requirements + +### Requirement: ResponsesApiProvider as Backstage Backend Module + +The Llama Stack provider is packaged as an independent Backstage backend module that registers via the extension point. + +#### Scenario: Module registration + +- **WHEN** the `plugin-augment-backend-module-llamastack` package is installed +- **THEN** it creates a `createBackendModule` with `pluginId: 'augment'` and `moduleId: 'llamastack'` +- **AND** it registers `ResponsesApiProviderFactory` via `augmentProviderExtensionPoint` (AI capabilities — composable, accessed by the core backend) +- **AND** it composes `llamastack-entity-provider` internally, registering its entity providers via `catalogProcessingExtensionPoint` +- **AND** `llamastack-entity-provider` is also independently deployable as its own RHDH dynamic plugin (without boost) +- **AND** it depends on `coreServices.config` for Llama Stack connection settings +- **AND** it depends on `coreServices.logger` and `coreServices.cache` for operational services + +#### Scenario: Dynamic plugin packaging + +- **WHEN** the module is exported for RHDH dynamic plugin deployment +- **THEN** it is packaged as an OCI image via `@red-hat-developer-hub/cli plugin export` +- **AND** it is configured in `dynamic-plugins.yaml` as: + ```yaml + - package: oci://registry/augment-backend-module-llamastack:tag!augment-backend-module-llamastack-dynamic + disabled: false + ``` +- **AND** it can be installed or removed independently of the core augment backend + +#### Scenario: Module uses Backstage cacheService + +- **WHEN** the Llama Stack module needs to cache model lists or auth tokens +- **THEN** it depends on `coreServices.cache` and uses `cache.set(key, value, { ttl: '60s' })` +- **AND** it does NOT create raw `Map<>` caches with manual TTL tracking +- **AND** cached data is Redis-backed in production for multi-instance safety + +### Requirement: KagentiProvider as Backstage Backend Module + +The Kagenti provider is packaged as an independent Backstage backend module. + +#### Scenario: Module registration + +- **WHEN** the `plugin-augment-backend-module-kagenti` package is installed +- **THEN** it creates a `createBackendModule` with `pluginId: 'augment'` and `moduleId: 'kagenti'` +- **AND** it registers `KagentiProviderFactory` via `augmentProviderExtensionPoint` (AI capabilities — composable, accessed by the core backend) +- **AND** it composes `kagenti-entity-provider` internally, registering its entity providers via `catalogProcessingExtensionPoint` +- **AND** `kagenti-entity-provider` is also independently deployable as its own RHDH dynamic plugin (without boost) +- **AND** it depends on `coreServices.config` for Kagenti/Keycloak connection settings +- **AND** it depends on `coreServices.cache` for agent card caching and token management + +#### Scenario: Agent card cache uses Backstage cacheService + +- **WHEN** the Kagenti module caches agent cards (currently `KagentiAgentCardCache` with 5m TTL, max 500 entries) +- **THEN** it uses `coreServices.cache` with `cache.withOptions({ defaultTtl: { minutes: 5 } })` +- **AND** cache invalidation occurs on agent create/update/delete operations +- **AND** the unbounded growth risk of the current `Map<>` implementation is eliminated + +#### Scenario: Keycloak token cache uses Backstage cacheService + +- **WHEN** the Kagenti module caches Keycloak access tokens (currently `KeycloakTokenManager`) +- **THEN** it uses `coreServices.cache` with TTL derived from token expiry +- **AND** the token cache is Redis-backed in production for multi-instance safety + +### Requirement: Standalone Toolkit Packages + +Provider-internal subsystems with zero Backstage coupling are extracted as standalone packages. + +#### Scenario: toolscope extracted as standalone package + +- **WHEN** the `services/toolscope/` subsystem (29 files, zero Backstage dependencies) is needed +- **THEN** it is available as `@augment/toolscope` (or `@augment-adk/toolscope`) +- **AND** the embedding cache (currently unbounded `Map<>`) is replaced with an injectable cache interface +- **AND** the session cache (currently raw `Map<>` with 1h TTL, max 1000) uses the injected cache + +#### Scenario: responses-api toolkit partially extracted + +- **WHEN** shared Responses API utilities (prompt generation, tool execution patterns) are needed by multiple providers +- **THEN** they are available in a shared `providers/responses-api/` package +- **AND** provider-specific code does NOT import across provider boundaries (e.g., Kagenti importing from `responses-api/chat/promptGeneration` is eliminated) diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/tasks.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/tasks.md new file mode 100644 index 0000000000..c998a7285d --- /dev/null +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/tasks.md @@ -0,0 +1,69 @@ +# Tasks: Pluggable AI Platform Architecture + +## 1. Types and Service Ref (P0) + +- [ ] 1.1 Move `AgenticProvider`, `ProviderDescriptor`, `ProviderCapabilities` interfaces to `augment-common` +- [ ] 1.2 Move `NormalizedStreamEvent` union type to `augment-common` +- [ ] 1.3 Move `ConversationSummary`, `ConversationDetails`, `InputItem` from `providers/llamastack/conversationTypes.ts` to `augment-common` +- [ ] 1.4 Create `augmentAiProviderServiceRef` in `augment-common` via `createServiceRef` +- [ ] 1.5 Register default service factory in `augment-backend/plugin.ts` resolving to `ProviderManager.getActiveProvider()` +- [ ] 1.6 Verify no provider-specific types leak into common package + +## 2. Provider Module Extraction (P0) + +- [ ] 2.1 Create `plugin-augment-backend-module-llamastack` package with `createBackendModule({ pluginId: 'augment', moduleId: 'llamastack' })` +- [ ] 2.2 Move `ResponsesApiProvider`, `ResponsesApiProviderFactory`, and Llama Stack client code to the module +- [ ] 2.3 Create `plugin-augment-backend-module-kagenti` package with `createBackendModule({ pluginId: 'augment', moduleId: 'kagenti' })` +- [ ] 2.4 Move `KagentiProvider`, `KagentiProviderFactory`, and Kagenti client code to the module +- [ ] 2.5 Eliminate cross-provider import: remove `KagentiProvider.ts` import of `responses-api/chat/promptGeneration` +- [ ] 2.6 Verify each provider module starts and registers independently via extension point + +## 3. Cache Migration — Provider Caches (P1) + +- [ ] 3.1 Add `coreServices.cache` dependency to provider modules +- [x] 3.2 KagentiProvider.\_modelsCache — already migrated to cacheService ✓ +- [x] 3.3 KagentiAgentCardCache — already migrated to cacheService ✓ +- [ ] 3.4 Replace `ResponsesApiProvider._modelsCache` (raw object) with `cache.withOptions({ defaultTtl: '60s' })` — eliminates model cache asymmetry +- [ ] 3.5 Replace `KeycloakTokenManager` (Map<>) with `cache.set(key, token, { ttl: expiresIn })` +- [ ] 3.6 Replace `McpAuthService` token caches (Map<>, dynamic TTL) with cacheService +- [ ] 3.7 Replace `BackendToolExecutor` schema cache (Map<>, unbounded) with `cache.withOptions({ defaultTtl: '5m' })` +- [ ] 3.8 Replace `ConversationRegistry` (Map<>, no TTL, 10k max) with `cache.withOptions({ defaultTtl: '24h' })` +- [ ] 3.9 Replace `KagentiProvider` session maps (Map<>, no TTL) with cacheService +- [ ] 3.10 Replace `ClientManager` (Map<>) with identity-keyed cacheService +- [ ] 3.11 Replace `DocumentSyncService` hash tracking (Map<>, no TTL) with cacheService (no expiry) + +## 3b. Cache Migration — Core Caches (P0) + +- [ ] 3b.1 Replace `RuntimeConfigResolver` cache (raw Map, 30s TTL) with `coreServices.cache` + immediate invalidation via `cache.delete()` +- [ ] 3b.2 Verify `ConfigResolutionService` delegates correctly to migrated RuntimeConfigResolver + +## 3c. Kagenti Type Extraction (P1) + +- [ ] 3c.1 Move 559 lines of Kagenti-only types (60+ interfaces) from `augment-common` to the Kagenti provider module +- [ ] 3c.2 Keep only `AgenticProvider`, `ProviderDescriptor`, `ProviderCapabilities`, conversation types, and `NormalizedStreamEvent` in `augment-common` +- [ ] 3c.3 Verify common package contains only shared interfaces — no provider-specific types + +## 4. Frontend Capability Checks (P1) + +- [ ] 4.1 Replace `providerId === 'kagenti'` in `AdminLayout.tsx` with `ProviderCapabilities` query +- [ ] 4.2 Replace provider ID checks in `ChatView.tsx` with capability checks +- [ ] 4.3 Replace provider ID checks in `ChatHeader.tsx` with capability checks +- [ ] 4.4 Extend `ProviderCapabilities` interface with missing capability flags (agentCatalog, namespaceScoping, devSpaces, buildPipelines) + +## 5. Standalone Package Extraction (P2) + +- [ ] 5.1 Extract `services/toolscope/` as `@augment/toolscope` with injectable cache interface +- [ ] 5.2 Extract shared `providers/responses-api/` utilities as `@augment/responses-api-toolkit` + +## 6. Dynamic Plugin Packaging (P2) + +- [ ] 6.1 Configure `plugin-augment-backend-module-llamastack` for RHDH dynamic plugin export (OCI) +- [ ] 6.2 Configure `plugin-augment-backend-module-kagenti` for RHDH dynamic plugin export (OCI) +- [ ] 6.3 Create `dynamic-plugins.yaml` examples for modular deployment + +## 7. Verify + +- [ ] 7.1 Verify serviceRef consumption works from an external test plugin +- [ ] 7.2 Verify hot-swap works with modular provider packages +- [ ] 7.3 Verify cache behavior in both in-memory and Redis-backed modes +- [ ] 7.4 Verify no provider ID string checks remain in frontend diff --git a/workspaces/boost/openspec/changes/security-safety-governance/.openspec.yaml b/workspaces/boost/openspec/changes/security-safety-governance/.openspec.yaml new file mode 100644 index 0000000000..28882f7998 --- /dev/null +++ b/workspaces/boost/openspec/changes/security-safety-governance/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-19 diff --git a/workspaces/boost/openspec/changes/security-safety-governance/design.md b/workspaces/boost/openspec/changes/security-safety-governance/design.md new file mode 100644 index 0000000000..091ff5e3a7 --- /dev/null +++ b/workspaces/boost/openspec/changes/security-safety-governance/design.md @@ -0,0 +1,59 @@ +# Design: Security, Safety & Governance + +## Context + +Boost builds the security and governance layer from scratch, informed by augment's experience. Augment's governance system grew into a parallel authorization layer (2,132 lines of custom code vs. 73 lines of Backstage permissions — 29x ratio) where 12 authorization decisions bypassed `permissions.authorize()`. Boost avoids this entirely: all authorization decisions use Backstage fine-grained permissions from day one. + +Augment also authenticated to Kagenti using a shared service-account token for all users, making per-user audit trails impossible. Boost implements RFC 8693 token exchange for per-user identity delegation from the start. + +## Goals + +- Implement 16 fine-grained Backstage permissions as the sole authorization mechanism +- Add conditional permission rules for ownership (IS_OWNER), separation of duties (IS_NOT_CREATOR), and lifecycle stage gating (HAS_LIFECYCLE_STAGE) +- Implement RFC 8693 token exchange for per-user Kagenti identity +- Rename `none` security mode with deprecation path +- Add CSRF protection and credential encryption +- Export all permissions from `augment-common` + +## Non-Goals + +- Removing the 3-mode security system (it's a deliberate product feature) +- Changing safety shield behavior or the SSRF guard +- Modifying the MCP auth chain logic +- Removing the SonataFlow approval workflow integration + +## Decisions + +### Decision 1: 16 permissions with resource-based conditions and admin fallback + +Agent and tool lifecycle actions get resource-based permissions with conditional rules. The `authorizeLifecycleAction` middleware replaces scattered per-route guards. On fine-grained DENY, the system falls back to checking `augment.admin` — enabling gradual adoption without breaking existing 2-permission deployments. + +### Decision 2: Three conditional permission rules + +- `IS_OWNER`: `resource.createdBy === currentUser` — gates promote, withdraw, delete, unpublish +- `IS_NOT_CREATOR`: `resource.createdBy !== currentUser` — enforces self-approval prevention +- `HAS_LIFECYCLE_STAGE`: `resource.lifecycleStage in allowedStages` — enforces valid transitions + +These rules are evaluated against loaded resources via `createConditionalDecision` and integrated with `PermissionPolicy`. + +### Decision 3: Self-approval prevention stays layered + +The `IS_NOT_CREATOR` permission rule is the primary enforcement mechanism. The existing route-level guard remains as defense-in-depth (belt and suspenders). Both layers are active in `security.mode === 'full'`. + +### Decision 4: Per-user token exchange is backend-only with graceful fallback + +`TokenExchangeManager` reads the user's OIDC token from a configurable request header (injected by auth proxy), exchanges it via RFC 8693, caches per-user, and deduplicates concurrent exchanges. All failures fall back silently to the shared service-account token — no request is ever blocked by token exchange issues. This is deliberately conservative: token exchange enhances audit trails and per-user authorization but must never degrade availability. + +### Decision 5: Separation of authorization concerns + +Three non-overlapping authorization layers: + +- **Backstage** governs: UI visibility, agent lifecycle governance, ownership, approval workflows, admin operations +- **Kagenti** governs: agent specs, tools, runtime operations — via per-user exchanged token when enabled +- **Kubernetes** governs: pod/deployment operations, namespace scoping, SPIRE mTLS + +## Risks + +- **RBAC policy complexity:** 16 permissions with conditions is more complex than 2. Mitigated by sensible defaults — `augment.access` as top-level gate and `augment.admin` available for coarse control. +- **Token exchange reliability:** Keycloak availability becomes a dependency. Mitigated by graceful fallback to service-account token on any failure. +- **SonataFlow trust boundary:** Callbacks bypass self-approval prevention via header. Callback identity verification should be implemented to close this gap. diff --git a/workspaces/boost/openspec/changes/security-safety-governance/proposal.md b/workspaces/boost/openspec/changes/security-safety-governance/proposal.md new file mode 100644 index 0000000000..8a32d5858b --- /dev/null +++ b/workspaces/boost/openspec/changes/security-safety-governance/proposal.md @@ -0,0 +1,33 @@ +# Proposal: Security, Safety & Governance + +## Why + +Enterprise AI platforms must treat security, safety, and governance as foundational capabilities. Augment implements a three-tier security mode system, RBAC, content safety shields, SSRF protection, and zero data retention. However, the permission model is too coarse (2 permissions vs. peer plugins' 7+), the security modes are non-standard, and there are no resource-based permissions for owned resources. + +## What Changes + +### Current Capabilities (retroactive documentation) + +- Three security modes: `none`, `plugin-only`, `full` +- RBAC via Keycloak OIDC + Backstage permissions (`augment.access`, `augment.admin`) +- Frontend `SecurityGate` with meaningful access-denied page +- Content safety shields (input/output) with fail-open/fail-closed +- SSRF protection via `SsrfGuard` on all backend HTTP paths +- Zero Data Retention mode with encrypted reasoning tokens +- MCP 4-level auth chain +- Kagenti SPIRE integration for infrastructure mTLS +- Provider offline detection and error boundaries + +### Architectural Improvements (from tech debt analysis) + +- Expand from 2 to 7-9 fine-grained permissions (matching Lightspeed granularity) +- Add resource-based permissions for owned resources (sessions, documents, agents) +- Rename `none` security mode to `development-only-no-auth` with production warning +- Replace `adminUsers` fallback with standard Backstage RBAC-only pattern + +## Impact + +- `plugins/augment-common/src/permissions.ts` — expanded permission definitions +- `plugins/augment-backend/src/middleware/security.ts` — fine-grained enforcement +- `plugins/augment/src/components/SecurityGate.tsx` — granular permission checks +- `plugins/augment-backend/src/routes/` — per-route permission requirements diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md new file mode 100644 index 0000000000..8a4c8102e9 --- /dev/null +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md @@ -0,0 +1,153 @@ +# Access Control and Security Posture + +Multi-level security configuration controlling who accesses Augment, who has admin privileges, and how tool connections are authenticated. + +## EXISTING Requirements + +### Requirement: Three Security Modes + +The plugin supports progressive security enforcement from development through production. + +#### Scenario: Security mode `none` (development only) + +- **WHEN** `augment.security.mode` is set to `none` +- **THEN** the frontend shows no SecurityGate — all users pass as guest +- **AND** the backend skips RBAC and treats everyone as admin +- **AND** provider auth uses static token/TLS if configured + +#### Scenario: Security mode `plugin-only` (recommended production) + +- **WHEN** `augment.security.mode` is set to `plugin-only` +- **THEN** `SecurityGate` wraps `AugmentPage` with `RequirePermission` +- **AND** the backend enforces `augment.access` via `requirePluginAccess` middleware +- **AND** admin access uses an explicit `adminUsers` allowlist +- **AND** real user principal is extracted from the request + +#### Scenario: Security mode `full` (full production with token propagation) + +- **WHEN** `augment.security.mode` is set to `full` +- **THEN** the backend enforces both `augment.access` and `augment.admin` via Backstage RBAC +- **AND** MCP OAuth chain is configured for token propagation to tool servers +- **AND** Kagenti uses Keycloak OAuth2 + SPIRE mTLS + +### Requirement: Frontend Security Enforcement + +Unauthorized users see meaningful access-denied pages, not broken UIs. + +#### Scenario: SecurityGate blocks unauthorized access + +- **WHEN** a user without `augment.access` permission navigates to Augment +- **THEN** `SecurityGate` renders a meaningful access-denied page +- **AND** the page explains what permission is needed and how to request access + +### Requirement: MCP Auth Chain + +Tool connections authenticate through a 4-level hierarchical resolution. + +#### Scenario: Auth chain resolves credentials + +- **WHEN** an MCP tool call requires authentication +- **THEN** `McpAuthService` resolves in order: auth references (per-tool) → per-server OAuth (client credentials) → ServiceAccount tokens → global fallback +- **AND** caching with deduplication prevents concurrent refresh storms + +### Requirement: SSRF Protection + +All backend HTTP paths are protected against SSRF attacks. + +#### Scenario: SsrfGuard blocks internal network access + +- **WHEN** a backend HTTP call targets an internal/private network address +- **THEN** `SsrfGuard` performs DNS re-check and blocks the request +- **AND** this applies to all HTTP paths: ingestion, MCP, and provider calls + +### Requirement: Zero Data Retention Mode + +Inference responses are not stored on the server when ZDR is enabled. + +#### Scenario: ZDR mode active + +- **WHEN** zero data retention is configured +- **THEN** inference responses are not persisted on the server +- **AND** conversation continuity uses encrypted reasoning tokens instead of stored messages + +## ADDED Requirements + +### Requirement: Per-User Kagenti Identity via Token Exchange + +User identity is delegated to Kagenti via RFC 8693 OAuth2 Token Exchange so agent operations are authorized per-user. + +#### Scenario: Token exchange enabled + +- **WHEN** `augment.kagenti.auth.tokenExchange.enabled` is `true` +- **AND** a user's OIDC token is available via the configured header (default: `X-Forwarded-Access-Token`) +- **THEN** `TokenExchangeManager` exchanges the user's token for a Kagenti-scoped token via RFC 8693 +- **AND** the exchanged token is cached per-user with TTL from token expiry +- **AND** concurrent exchanges for the same user are deduplicated +- **AND** the per-user token is used for all Kagenti API calls on behalf of that user + +#### Scenario: Token exchange graceful fallback + +- **WHEN** token exchange fails (missing header, Keycloak error, exchange failure, disabled config) +- **THEN** the system silently falls back to the shared service-account token +- **AND** no request is blocked due to token exchange failure +- **AND** the fallback is logged for debugging + +#### Scenario: Token exchange configuration + +- **WHEN** token exchange is configured +- **THEN** the following config is used: + | Key | Default | Description | + |---|---|---| + | `augment.kagenti.auth.tokenExchange.enabled` | `false` | Enable per-user token exchange | + | `augment.kagenti.auth.tokenExchange.audience` | — | Target audience for exchanged token | + | `augment.kagenti.auth.tokenExchange.userTokenHeader` | `X-Forwarded-Access-Token` | Header containing user's OIDC token | + +#### Scenario: LlamaStack provider unaffected + +- **WHEN** token exchange is configured +- **THEN** `ResponsesApiProvider` is not modified — `setUserContext` is optional and not implemented +- **AND** token exchange is Kagenti-specific + +### Requirement: CSRF Protection + +All mutating requests include CSRF protection headers. + +#### Scenario: X-Backstage-Request header enforcement + +- **WHEN** a mutating fetch operation is made from the frontend +- **THEN** the `X-Backstage-Request` header is included +- **AND** this applies to all fetch operations including workflow dashboard operations + +### Requirement: Credential Storage + +Sensitive credentials are stored encrypted in the admin config database. + +#### Scenario: DevSpaces token encryption + +- **WHEN** a DevSpaces token is stored in admin configuration +- **THEN** the token is encrypted at rest in the `augment_admin_config` table +- **AND** plaintext storage of credentials is not permitted + +## MODIFIED Requirements + +### Requirement: Security Mode Naming + +The `none` mode name must clearly indicate its development-only nature. + +#### Scenario: Renamed security mode with production warning + +- **WHEN** `augment.security.mode` is set to `development-only-no-auth` (renamed from `none`) +- **THEN** behavior is identical to the current `none` mode +- **AND** if detected in a non-development environment, a prominent warning is logged at startup +- **AND** boost uses `development-only-no-auth` as the only name for this mode (no legacy aliases) + +### Requirement: Identity Resolution + +User identity resolution uses real OIDC credentials in all security modes. + +#### Scenario: getUserRef reads real credentials + +- **WHEN** `getUserRef()` resolves the current user's identity +- **THEN** it reads real OIDC credentials from `httpAuth.credentials` even in `security.mode === 'development-only-no-auth'` +- **AND** falls back to `user:default/guest` only if OIDC credentials are not available +- **AND** this ensures ownership fields (`createdBy`) reflect real users even in development diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md new file mode 100644 index 0000000000..fa14fffb6c --- /dev/null +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md @@ -0,0 +1,135 @@ +# Fine-Grained Permissions + +Expand from 2 coarse permissions to 16 fine-grained permissions across 3 resource types with conditional rules, replacing custom route-level governance with proper Backstage RBAC. This eliminates the parallel authorization system (2,132 lines of custom governance code vs. 73 lines of Backstage permissions) by migrating all 12+ authorization decisions into `permissions.authorize()`. + +## ADDED Requirements + +### Requirement: Agent Lifecycle Permissions (Resource-Based) + +RBAC policies govern agent lifecycle transitions with ownership and separation-of-duties rules. + +#### Scenario: Agent permission definitions + +- **WHEN** the augment plugin registers permissions via `permissionsRegistry.addPermissions()` +- **THEN** the following agent permissions are registered: + | Permission | Resource Type | Conditional Rules | Gates | + |---|---|---|---| + | `augment.agent.list` | — | — | View agent list (visibility filtering) | + | `augment.agent.register` | — | — | Register an agent for governance | + | `augment.agent.promote` | `augment-agent` | `IS_OWNER`, `HAS_LIFECYCLE_STAGE` | Submit draft for review (draft→pending) | + | `augment.agent.approve` | `augment-agent` | `IS_NOT_CREATOR`, `HAS_LIFECYCLE_STAGE` | Approve pending (pending→published) | + | `augment.agent.demote` | `augment-agent` | — | Reject, request-unpublish, approve-unpublish | + | `augment.agent.publish` | `augment-agent` | — | Publish an approved agent | + | `augment.agent.unpublish` | `augment-agent` | `IS_OWNER` | Request unpublishing | + | `augment.agent.withdraw` | `augment-agent` | `IS_OWNER` | Withdraw pending submission | + | `augment.agent.delete` | `augment-agent` | `IS_OWNER`, `HAS_LIFECYCLE_STAGE` | Delete agent | + | `augment.agent.configure` | — | — | Edit agent configuration | + +#### Scenario: Self-approval prevention via IS_NOT_CREATOR rule + +- **WHEN** a user attempts to approve an agent (pending→published) +- **THEN** the `IS_NOT_CREATOR` conditional rule checks `resource.createdBy !== currentUser` +- **AND** if the user is the agent's creator, the permission is DENIED +- **AND** a defense-in-depth route guard additionally enforces this in `security.mode === 'full'` + +#### Scenario: Ownership-scoped promotion + +- **WHEN** a non-admin user attempts to promote their own draft agent +- **THEN** `IS_OWNER` checks `resource.createdBy === currentUser` +- **AND** `HAS_LIFECYCLE_STAGE` checks `resource.lifecycleStage === 'draft'` +- **AND** both rules must pass for the promotion to proceed + +### Requirement: Tool Lifecycle Permissions (Resource-Based) + +RBAC policies govern tool lifecycle transitions. + +#### Scenario: Tool permission definitions + +- **WHEN** the augment plugin registers permissions +- **THEN** the following tool permissions are registered: + | Permission | Resource Type | Conditional Rules | Gates | + |---|---|---|---| + | `augment.tool.promote` | `augment-tool` | `IS_OWNER` | Promote tool lifecycle | + | `augment.tool.approve` | `augment-tool` | `IS_NOT_CREATOR` | Approve tool promotion | + | `augment.tool.demote` | `augment-tool` | — | Demote tool lifecycle stage | + | `augment.tool.publish` | `augment-tool` | — | Publish a tool | + | `augment.tool.unpublish` | `augment-tool` | — | Unpublish a tool | + +### Requirement: Infrastructure Permissions + +#### Scenario: Kagenti admin permission + +- **WHEN** a user accesses Kagenti infrastructure operations +- **THEN** `augment.kagenti.admin` permission is checked +- **AND** this covers namespace management, build pipelines, sandbox, and platform links + +### Requirement: Conditional Permission Rules + +Three conditional rules evaluate loaded resources during permission checks. + +#### Scenario: IS_OWNER rule + +- **WHEN** a permission check includes the `IS_OWNER` condition +- **THEN** the system loads the agent/tool resource and checks `resource.createdBy === userRef` +- **AND** `userRef` is resolved from `httpAuth.credentials` (real OIDC identity) + +#### Scenario: IS_NOT_CREATOR rule + +- **WHEN** a permission check includes the `IS_NOT_CREATOR` condition +- **THEN** the system checks `resource.createdBy !== userRef` +- **AND** this enforces separation of duties (no self-approval) + +#### Scenario: HAS_LIFECYCLE_STAGE rule + +- **WHEN** a permission check includes the `HAS_LIFECYCLE_STAGE` condition +- **THEN** the system checks `resource.lifecycleStage` against the allowed stages for the action +- **AND** invalid lifecycle transitions are blocked at the permission layer + +### Requirement: Backward Compatibility with Fallback + +Existing 2-permission deployments continue to work without policy changes. + +#### Scenario: Fine-grained permissions as primary authorization + +- **WHEN** a lifecycle or admin action is invoked +- **THEN** the specific fine-grained permission is checked via `permissions.authorize()` +- **AND** `augment.access` serves as a top-level gate (if denied, all sub-permissions are denied) +- **AND** `augment.admin` is available for deployments that prefer coarse-grained admin control + +### Requirement: Route-Level Authorization Middleware + +A shared middleware replaces scattered route-level guards. + +#### Scenario: authorizeLifecycleAction middleware + +- **WHEN** a lifecycle route is invoked (promote, approve, demote, delete, etc.) +- **THEN** `authorizeLifecycleAction(permission, resourceLoader)` middleware: + 1. Loads the resource (agent or tool) + 2. Calls `permissions.authorize()` with the fine-grained permission and resource + 3. On DENY, falls back to `augment.admin` + 4. On both DENY, returns 403 +- **AND** this replaces the per-route `checkIsAdmin` + `getUserRef` + ownership patterns + +### Requirement: Permission Registration Best Practices + +#### Scenario: Permissions exported from common package + +- **WHEN** permission constants are needed by frontend or backend +- **THEN** they are exported from `@augment/plugin-augment-common` +- **AND** basic permissions use `createPermission` from `@backstage/plugin-permission-common` +- **AND** resource permissions use `createResourcePermission` with resource types `augment-agent` and `augment-tool` + +### Requirement: Functional Area Permissions (non-lifecycle) + +#### Scenario: Functional permission definitions + +- **WHEN** the augment plugin registers permissions +- **THEN** the following functional permissions are also registered: + | Permission | Action | Gates | + |---|---|---| + | `augment.chat.read` | read | View chat interface, read messages | + | `augment.chat.create` | create | Send messages, start sessions | + | `augment.documents.manage` | update | Upload documents, sync RAG sources | + | `augment.mcp.manage` | update | Configure MCP servers | + | `augment.config.manage` | update | Modify admin configuration | +- **AND** these supplement the lifecycle permissions for comprehensive coverage diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/resilience/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/resilience/spec.md new file mode 100644 index 0000000000..9ecaf20cd3 --- /dev/null +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/resilience/spec.md @@ -0,0 +1,36 @@ +# Resilience Patterns + +Graceful degradation when things go wrong — provider offline detection, error boundaries, and transient notifications. + +## EXISTING Requirements + +### Requirement: Provider Offline Detection + +The system detects when the AI provider is unreachable and communicates this clearly. + +#### Scenario: Provider goes offline + +- **WHEN** `useStatus` detects the AI provider is down +- **THEN** `ProviderOfflineBanner` is displayed +- **AND** chat resumes automatically when the provider recovers + +### Requirement: Error Boundaries + +Per-message and page-level error isolation prevents cascading failures. + +#### Scenario: Agent error contained + +- **WHEN** an agent or streaming error occurs +- **THEN** `ErrorCard` is displayed inline on the affected message +- **AND** `AugmentErrorBoundary` prevents the entire page from crashing +- **AND** other messages and navigation remain functional + +### Requirement: Transient Notifications + +Non-blocking feedback for operational events. + +#### Scenario: Toast notifications + +- **WHEN** a transient event occurs (config saved, connection tested, etc.) +- **THEN** a snackbar toast is shown via `useToast` +- **AND** it auto-dismisses after a timeout diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/safety-shields/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/safety-shields/spec.md new file mode 100644 index 0000000000..eb344c34cc --- /dev/null +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/safety-shields/spec.md @@ -0,0 +1,42 @@ +# Safety Shields and Guardrails + +Content safety filtering on agent inputs and outputs to prevent harmful, injected, or destructive content. + +## EXISTING Requirements + +### Requirement: Input Shields + +Safety filters applied to user messages before sending to the model. + +#### Scenario: Input shield detects prompt injection + +- **WHEN** a user message is submitted to the agent +- **THEN** enabled input shields (prompt injection detection, harmful content filtering) are applied +- **AND** if a violation is detected and the shield is configured as fail-closed, the message is blocked and the user sees a safety message +- **AND** if configured as fail-open, the content passes through but the violation is logged + +### Requirement: Output Shields + +Safety filters applied to agent responses before displaying. + +#### Scenario: Output shield detects harmful content + +- **WHEN** an agent generates a response +- **THEN** enabled output shields (harmful content filtering, destructive command detection) are applied +- **AND** violation handling follows the same fail-open/fail-closed behavior as input shields + +### Requirement: Shield Administration + +Administrators configure shields and review violations. + +#### Scenario: Admin configures shield behavior + +- **WHEN** the admin opens the `SafetyEvalPanel` +- **THEN** `SafetyShieldsSection` shows available shields with enable/disable toggles +- **AND** each shield can be configured as fail-open or fail-closed +- **AND** `SafetyPatternsSection` allows custom safety patterns + +#### Scenario: Violation logging + +- **WHEN** any shield detects a violation +- **THEN** the violation details are logged for review regardless of fail-open/fail-closed setting diff --git a/workspaces/boost/openspec/changes/security-safety-governance/tasks.md b/workspaces/boost/openspec/changes/security-safety-governance/tasks.md new file mode 100644 index 0000000000..fadfcaface --- /dev/null +++ b/workspaces/boost/openspec/changes/security-safety-governance/tasks.md @@ -0,0 +1,76 @@ +# Tasks: Security, Safety & Governance + +## 1. Permission Definitions (P0, additive) + +- [ ] 1.1 Define 16 permissions in `augment-common/src/permissions.ts`: 10 agent, 5 tool, 1 kagenti-infra +- [ ] 1.2 Define resource types `augment-agent` and `augment-tool` using `createResourcePermission` +- [ ] 1.3 Define conditional rules: `IS_OWNER`, `IS_NOT_CREATOR`, `HAS_LIFECYCLE_STAGE` +- [ ] 1.4 Define 5 functional permissions: `chat.read`, `chat.create`, `documents.manage`, `mcp.manage`, `config.manage` +- [ ] 1.5 Register all permissions via `permissionsRegistry.addPermissions()` in backend `plugin.ts` + +## 2. Authorization Middleware (P0, new files) + +- [ ] 2.1 Create `authorizeLifecycleAction(permission, resourceLoader)` middleware in `middleware/security.ts` +- [ ] 2.2 Implement fine-grained permission check via `permissions.authorize()` → DENY → 403 pattern +- [ ] 2.3 Create resource loader functions for agents and tools (load from store, extract `createdBy` and `lifecycleStage`) + +## 3. Route Refactoring — Agent Routes (P1) + +- [ ] 3.1 Replace `GET /agents` visibility filtering with `augment.agent.list` + ownership condition +- [ ] 3.2 Replace `PUT /agents/:id/register` admin guard with `augment.agent.register` +- [ ] 3.3 Replace `PUT /agents/:id/promote` ownership+stage guards with `augment.agent.promote` (IS_OWNER + HAS_LIFECYCLE_STAGE) +- [ ] 3.4 Replace `PUT /agents/:id/promote` (pending→published) approval guard with `augment.agent.approve` (IS_NOT_CREATOR) +- [ ] 3.5 Replace `PUT /agents/:id/request-unpublish` with `augment.agent.unpublish` (IS_OWNER) +- [ ] 3.6 Replace `PUT /agents/:id/withdraw` with `augment.agent.withdraw` (IS_OWNER) +- [ ] 3.7 Replace `DELETE /agents/:id` stage+ownership guards with `augment.agent.delete` (IS_OWNER + HAS_LIFECYCLE_STAGE) + +## 4. Route Refactoring — Tool Routes (P1) + +- [ ] 4.1 Replace `PUT /tools/:id/promote` ownership guard with `augment.tool.promote` (IS_OWNER) +- [ ] 4.2 Replace `PUT /tools/:id/demote` admin guard with `augment.tool.demote` +- [ ] 4.3 Replace `PUT /tools/:id/publish` admin guard with `augment.tool.publish` +- [ ] 4.4 Replace `PUT /tools/:id/unpublish` admin guard with `augment.tool.unpublish` + +## 5. Route Refactoring — Kagenti Infra Routes (P1) + +- [ ] 5.1 Replace Kagenti admin route guards with `augment.kagenti.admin` + +## 6. Frontend Permission Gating (P1) + +- [ ] 6.1 Wrap admin panel sections with `` using fine-grained permissions +- [ ] 6.2 Batch permission checks via `usePermissions` (plural) for performance +- [ ] 6.3 Gate knowledge base panel with `augment.documents.manage` +- [ ] 6.4 Gate MCP panel with `augment.mcp.manage` +- [ ] 6.5 Gate config panel with `augment.config.manage` + +## 7. Token Exchange (P1, new file + config) + +- [ ] 7.1 Create `TokenExchangeManager` implementing RFC 8693 exchange +- [ ] 7.2 Add per-user token caching with TTL from token expiry +- [ ] 7.3 Add concurrent exchange deduplication +- [ ] 7.4 Add graceful fallback to service-account token on all failures +- [ ] 7.5 Add config schema: `augment.kagenti.auth.tokenExchange.{enabled, audience, userTokenHeader}` +- [ ] 7.6 Integrate into `KagentiApiClient.requestCore()` — inject per-user token when available +- [ ] 7.7 Extract user OIDC token from configurable request header in route handlers + +## 8. CSRF and Credential Security (P2) + +- [ ] 8.1 Add `X-Backstage-Request` header to all frontend mutating fetch operations +- [ ] 8.2 Encrypt DevSpaces tokens in admin config DB (not plaintext) + +## 9. Security Mode Rename (P3) + +- [ ] 9.1 Rename `none` to `development-only-no-auth` in config schema +- [ ] 9.2 Use `development-only-no-auth` as the only mode name (no legacy aliases) +- [ ] 9.3 Add production environment detection heuristic with startup warning + +## 10. Verify + +- [ ] 10.1 Verify fine-grained permission check → admin fallback → 403 pattern works +- [ ] 10.2 Verify IS_OWNER blocks non-owner promote/delete/withdraw +- [ ] 10.3 Verify IS_NOT_CREATOR blocks self-approval +- [ ] 10.4 Verify `augment.admin` works as coarse-grained alternative to fine-grained permissions +- [ ] 10.5 Verify token exchange fallback: disabled config → service-account token +- [ ] 10.6 Verify token exchange fallback: Keycloak error → service-account token +- [ ] 10.7 Verify token exchange fallback: missing header → service-account token +- [ ] 10.8 Verify `none` alias works with deprecation warning diff --git a/workspaces/boost/specifications/boost-context.md b/workspaces/boost/specifications/boost-context.md new file mode 100644 index 0000000000..03d23bc90f --- /dev/null +++ b/workspaces/boost/specifications/boost-context.md @@ -0,0 +1,155 @@ +# Boost: Project Context and Upstream Monitoring + +**Date:** 2026-06-02 + +--- + +## What Is Boost + +Boost is a new workspace delivering a clean-slate implementation of the agentic developer portal for Red Hat Developer Hub. It provides the same product capabilities as the Augment plugin — AI chat, agent creation and discovery, pluggable AI platform backends, governance, and platform operations — but built from scratch with intentional architecture, avoiding the accumulated tech debt of the reference prototype. + +## Relationship to Augment + +The Augment plugin (in `redhat-developer/rhdh-plugins`, workspace `augment`) is the **reference prototype**. It was the first implementation of the agentic developer portal and served as the basis for customer engagements (notably the Citi "Cloud Concierge" engagement). Boost's requirements, architecture decisions, and design principles are drawn from augment's experience — both what worked and what didn't. + +**Augment is the source of requirements.** The PRDs and OpenSpec changes in this directory were originally written as retroactive documentation of augment's capabilities. They have been reframed as forward-looking requirements for boost, informed by augment's implementation experience and three rounds of tech debt analysis (May 13, May 26, May 30 2026). + +**Boost is not a fork of augment.** It is a new codebase. There is no migration path from augment to boost — boost starts clean and implements the same (and evolving) product requirements with the right architecture from day one. + +## Product Requirements + +- [Use Case Index](prd/use-case-index.md) — all 25 use cases at a glance +- [AI Chat & Interaction Experience](prd/ai-chat-interaction-experience.md) — streaming chat, RAG, HITL approval, conversation history, debug tools (UC-1 through UC-6) +- [Agent Creation & Discovery](prd/agent-creation-discovery.md) — agent gallery, 4 creation paths, MCP tools, skills marketplace integration, catalog entities (UC-4, UC-7 through UC-13) +- [Pluggable AI Platform Architecture](prd/pluggable-ai-platform-architecture.md) — provider abstraction, streaming protocol, hot-swap, multi-agent orchestration, providers as RHDH dynamic plugins (UC-14, UC-16) +- [Platform Operations & Deployment](prd/platform-operations-deployment.md) — deployment, runtime config, RAG pipelines, white-labeling, workspace package structure (UC-15, UC-17, UC-18, UC-21, UC-22) +- [Security, Safety & Governance](prd/security-safety-governance.md) — 16 fine-grained permissions, lifecycle governance, token exchange, safety shields, resilience (UC-19, UC-20, UC-23 through UC-25) + +## Workspace Structure + +All packages live at `rhdh-plugins/workspace/boost/plugins/`: + +``` +workspace/boost/plugins/ +├── boost-frontend — Chat UI, agent gallery, admin panels, composable extensions +├── boost-common — Shared types, permissions, augmentAiProviderServiceRef +├── boost-backend — Core routes, services, middleware, ProviderManager, cross-cutting entity providers +├── boost-backend-module-llamastack — Llama Stack agentic provider (composes llamastack-entity-provider) +├── boost-backend-module-kagenti — Kagenti agentic provider (composes kagenti-entity-provider) +├── llamastack-entity-provider — Backstage backend service: Llama Stack catalog entities (independently deployable) +└── kagenti-entity-provider — Backstage backend service: Kagenti catalog entities (independently deployable) +``` + +The core three packages (`boost-frontend`, `boost-common`, `boost-backend`) mirror augment's structure. Provider modules and entity providers are additive — deployers install only what they need. Entity providers are independently deployable as RHDH dynamic plugins for catalog-only use cases. + +## Design Principles (Learned from Augment) + +These principles are derived from augment's tech debt analysis. Each represents a pattern that augment got wrong or accumulated as debt, and that boost will implement correctly from the start. + +### 1. Backstage cacheService from Day One + +All operational caches use Backstage `cacheService` with appropriate TTL, namespace isolation, and Redis backing in production. No raw `Map<>` caches with manual TTL tracking. + +_Augment lesson: 17 home-grown caches identified, only 2 migrated after months of development. Asymmetric caching (Kagenti on cacheService, Llama Stack on raw Map) created inconsistent multi-instance behavior._ + +### 2. Fine-Grained Backstage Permissions from Day One + +All authorization decisions use `permissions.authorize()` with specific permissions and conditional rules. No parallel authorization systems in route handlers. + +_Augment lesson: 2,132 lines of custom governance code implementing 12 authorization decisions outside Backstage permissions, vs. 73 lines of actual Backstage permission integration (29x ratio). Shadow authorization invisible to RBAC configuration._ + +### 3. Providers as Independent RHDH Dynamic Plugins + +Each AI platform provider is a separate `createBackendModule` packaged as an RHDH dynamic plugin. Provider types live in the common package. Cross-plugin consumption via `augmentAiProviderServiceRef`. + +_Augment lesson: Monolithic plugin with providers locked inside. No serviceRef for cross-plugin consumption. 559 lines of Kagenti-specific types polluting the common package. 13+ provider ID string checks coupling frontend to specific providers._ + +### 4. Capability-Based Feature Gating, Not Provider Identity Checks + +Frontend features are gated by `ProviderCapabilities` interface checks, never by `providerId === 'string'` comparisons. Provider-specific routes are confined to provider module directories. + +_Augment lesson: 18+ provider ID string checks and 12 `as KagentiProvider` type casts broke the provider abstraction at scale._ + +### 5. Catalog Entities for AI Domain Objects + +Agents, tools, models, MCP servers, and vector stores are Backstage catalog entities from the start — not plugin-internal caches. Entity providers poll external APIs and emit standard catalog entities with ownership, lifecycle, and RBAC integration. + +_Augment lesson: Four separate in-memory caches storing what should be catalog entities. Duplicate model caches across providers. No discoverability, ownership, or catalog-level RBAC for AI domain objects._ + +### 6. Schema-Driven Configuration Validation + +Runtime configuration uses Zod schemas as single source of truth. TypeScript types are derived from schemas. DB-stored overrides are validated by the same rules as YAML values. Each field is annotated with its scope: `yaml-only`, `db-overridable`, or `db-only`. + +_Augment lesson: 671 lines of hand-written validators duplicating what schemas should enforce. 1,500+ line config schema growing without resolution. DB values could bypass YAML validation._ + +### 7. Composable Frontend Extensions with Lazy Loading + +The frontend is decomposed into composable routable extensions (`ChatPage`, `AdminPage`, `AgentStudioPage`) with `React.lazy()` at extension boundaries. Feature flags control visibility per deployment. + +_Augment lesson: Single monolithic `AugmentPage` extension eagerly loading 200+ admin panel files. 13 components over 500 lines with zero lazy loading at primary entry points. No config-driven feature flags._ + +### 8. UX/UXD-Driven UI Development + +All user-facing UI is built from UX/UXD-provided mockups and wireframes. Frontend PRs modifying visible UI require design review. PatternFly design system alignment and WCAG 2.1 AA accessibility are baseline requirements. + +_Augment lesson: No UX/UXD integration in development workflow. UI components built code-first without design artifacts._ + +### 9. Clean 4-Stage Lifecycle Model + +Agent lifecycle uses the 4-stage model (Draft → Pending → Published → Archived) from the start, with no legacy stage mappings or normalization layers. + +_Augment lesson: Pivoted from 5-stage to 4-stage model mid-development, requiring `LEGACY_STAGE_MAP` and `normalizeLifecycleStage` compatibility layers._ + +### 10. Per-User Identity Delegation + +Kagenti authentication uses RFC 8693 token exchange for per-user authorization from the start (when enabled). No shared service-account-only authentication presenting all users as the same identity. + +_Augment lesson: All Kagenti requests used a shared service-account token. `X-Backstage-User` header was informational only. Per-user audit trail impossible at the provider level._ + +### 11. Testing from Day One + +Every feature ships with tests. Lifecycle routes, provider integrations, governance decisions, and streaming pipelines all have test coverage. Integration tests use real database and cache backends, not mocks. + +_Augment lesson: Zero tests for lifecycle routes, WorkflowBuilder (3,000+ lines), DevSpacesService, KagentiApiClient (922 lines). Mocked tests passed while production migrations failed._ + +### 12. Observability Built In + +Metrics, structured logging, and trace context propagation are implemented alongside features, not bolted on after. Provider health, cache hit rates, permission decision latency, lifecycle transition counts, and streaming pipeline throughput are observable from the start. + +_Augment lesson: No metrics, no dashboards, no alerting, no SLO tracking. Provider offline detection existed but no systematic observability framework for operations teams._ + +--- + +## Upstream Monitoring: Tracking Augment Changes + +Augment continues to evolve in `rhdh-plugins`. Boost must periodically check for changes that represent real requirement shifts (vs. augment-specific implementation choices) and decide whether to adopt them. + +### What to Monitor + +1. **New use cases or capabilities** — features that augment adds which aren't in boost's PRDs +2. **API contract changes** — changes to the `AgenticProvider` interface, `NormalizedStreamEvent` union, or REST API surface +3. **Provider protocol changes** — changes to A2A protocol integration, Llama Stack Responses API usage, or Kagenti API client patterns +4. **Governance model changes** — new lifecycle actions, new approval workflow patterns, new permission requirements +5. **External integration changes** — new MCP auth patterns, new catalog entity types, new SonataFlow integration patterns +6. **UX/UXD design changes** — new UI patterns, component redesigns, or interaction model changes that reflect product direction + +### What to Ignore + +1. **Tech debt fixes** — augment migrating its own caches, extracting its own packages, fixing its own provider abstraction violations. Boost starts clean; these are augment catching up. +2. **Backward compatibility scaffolding** — legacy stage maps, deprecated aliases, fallback patterns. Boost has no legacy deployments. +3. **Monolithic-to-modular transitions** — augment breaking apart its monolith. Boost starts modular. + +### Adoption Decision Process + +For each significant augment change: + +1. **Classify:** Is this a requirement change (new capability, changed behavior) or an implementation fix (tech debt, refactoring)? +2. **Evaluate:** If requirement change — does it apply to boost's product scope? Is it customer-driven or augment-specific? +3. **Decide:** Adopt (take the requirement as-is), Adapt (take the requirement but implement differently), or Ignore (augment-specific, not applicable to boost) +4. **Update:** If adopted/adapted, update the relevant PRD and OpenSpec change + +### Monitoring Cadence + +- **Weekly:** Quick scan of augment workspace commits and PRs for new capabilities or API changes +- **Bi-weekly:** Deeper review of merged PRs with architecture implications +- **On major PRs:** Any PR touching provider interfaces, governance model, or permission system warrants immediate review against boost specs diff --git a/workspaces/boost/specifications/prd/agent-creation-discovery.md b/workspaces/boost/specifications/prd/agent-creation-discovery.md new file mode 100644 index 0000000000..6aae3801c6 --- /dev/null +++ b/workspaces/boost/specifications/prd/agent-creation-discovery.md @@ -0,0 +1,337 @@ +# PRD: Agent Creation & Discovery + +**Product:** Boost — Agentic Developer Portal for Red Hat Developer Hub +**Status:** Requirements for new implementation (informed by Augment reference prototype) +**Date:** 2026-05-19 +**Updated:** 2026-06-02 — reframed for boost; 4-stage lifecycle, skills marketplace integration, catalog entities from day one, ownership semantics +**Priority:** P0 (creation paths, lifecycle governance) / P1 (discovery, tools, skills marketplace integration) +**Provenance:** Requirements derived from Augment plugin analysis. See `specifications/boost-context.md` for project context. + +--- + +## Why + +An agentic AI platform is only as valuable as the agents running on it. Augment must support the full agent lifecycle — from initial creation through discovery by end users — across two fundamentally different personas: citizen developers who create agents visually and professional developers who build agents with code. + +This PRD defines the four creation paths, the discovery and browsing experience, and MCP tool connectivity that powers agent capabilities. Together, these form the "supply side" of the agent ecosystem. + +## What This Product Does + +The platform provides four distinct paths to create an AI agent, a curated gallery for discovering existing agents, and a tool integration system for connecting agents to live infrastructure. All paths converge on a unified agent model that is visible to end users through the same gallery and chat interface. + +## Who It's For + +### Citizen Developer + +Creates agents visually through the no-code builder wizard. Discovers pre-built agents in the gallery. Does not write code. + +### Professional Developer + +Creates agents through Software Templates, cloud IDEs (DevSpaces), or by importing existing container images/repos. Configures MCP tool integrations. Can also extend the platform with new provider implementations. + +### Administrator + +Manages agents, orchestration rules, and tool policies across the platform. + +## Boundaries + +### In Scope + +- Agent browsing and selection (gallery, search, filter, pin) +- Four agent creation paths: no-code builder, Software Template, DevSpaces, import +- Skills marketplace integration: proxy to external skills catalog, deploy selected skills locally +- MCP tool server registration, authentication, and approval policies +- Agent lifecycle: 4-stage governance (Draft → Pending → Published → Archived) +- Ownership-based visibility and action gating +- Cascading delete across backend stores +- Backstage catalog representation: agents, tools, models, and MCP servers as catalog entities +- Kagenti-specific admin experience (sidebar, dashboard, build pipelines, sandbox) + +### Out of Scope + +- Chat interaction with agents (see AI Chat & Interaction PRD) +- Provider architecture and hot-swap (see Platform Architecture PRD) +- Lifecycle governance approval workflows and permissions (see Security & Governance PRD) +- Runtime configuration and branding (see Platform Operations PRD) + +### UX/UXD Integration + +All agent creation, gallery, and admin UI flows must align with RHDH usability and visual design standards: + +- **Mockups as source of truth:** Agent gallery, creation wizards, skills marketplace integration, lifecycle governance UI, and admin panels are built from UX/UXD-provided mockups and wireframes. No user-facing UI ships without an approved design artifact. +- **PatternFly alignment:** All components use PatternFly design system patterns consistent with RHDH. Custom wizard steps, gallery cards, preview panels, and approval queue UIs require UX/UXD review. +- **Design review gates:** Frontend PRs introducing or modifying agent-facing UI require UX/UXD sign-off before merge. + +--- + +## Capabilities + +### 1. Browse and Select an Agent (UC-4) + +**Goal:** Discover available agents, evaluate their capabilities, and select one to start a conversation. + +**How it works (Kagenti):** + +- Welcome screen shows a featured agents strip curated by the administrator +- "Browse all agents" opens the full agent catalog dialog +- Search, filter by framework, sort by name/status/newest; tabs: All, Recent, Pinned +- Preview panel shows: starters, about, skills, capabilities (streaming/A2A), technical details (framework, workspace, version, endpoint) +- "Start Conversation" selects the agent and enables the chat input + +**Llama Stack path:** Agents are configured by the administrator; the router agent handles delegation automatically. No gallery needed. + +**First visit:** Auto-open catalog when no agent is selected (Kagenti). + +**Epics/Stories:** Epic 3 (Feature 3.2), Epic 1 (Stories 1.5.2-1.5.3) + +### 2. Discover Agents in the Gallery (UC-9) + +**Goal:** Browse a curated collection of pre-built agents with rich metadata. (Citizen Developer focused, Kagenti only.) + +**How it works:** + +- Welcome screen shows featured agents curated by administrator +- Agent cards display: name, description, avatar, capabilities, framework, status +- Click-through to preview panel with detailed information and "Start Conversation" +- Search by keyword, filter by framework, pin favorites + +**Epics/Stories:** Epic 3 (Feature 3.2), Epic 4 (Story 4.5.1), Epic 9 (Story 9.4.3) + +### 3. Create an Agent — Umbrella (UC-7) + +**Goal:** Create a new AI agent that serves users through the Augment chat interface. + +Four creation methods converge to a unified `ChatAgent` model: + +| Method | Persona | How | Provider | +| ------------------ | ---------------------- | ------------------------------ | ---------------------- | +| No-code builder | Citizen Developer | Visual wizard in admin UI | Llama Stack or Kagenti | +| Software Template | Professional Developer | Backstage scaffolder | Kagenti | +| Write from scratch | Professional Developer | Code in DevSpaces | Kagenti | +| Import existing | Professional Developer | Container image or source repo | Kagenti | + +All methods produce an agent visible in the gallery and available in chat. + +**Epics/Stories:** Epic 2 (Story 2.1.1), Epic 3 (Features 3.3, 3.4) + +### 4. No-Code Agent Builder (UC-8) + +**Goal:** Create an AI agent visually — defining its purpose, tools, knowledge base, and handoff rules — without writing code. + +**Llama Stack flow:** + +1. Admin panel → Agents → "Create Agent" +2. Agent editor: name, instructions, model, temperature, max tokens +3. Configure tool access (MCP servers/tools) +4. Scope knowledge base (vector store IDs) +5. Configure handoffs (target agents) +6. Save — agent is immediately available + +**Kagenti flow:** + +1. CreateAgentWizard: 3 steps (basics, deployment, runtime) + optional build +2. Optional: `AgentCreateIntentDialog` for quick creation from natural language intent +3. Build step triggers Shipwright container build if needed +4. Agent appears in gallery + +**Epics/Stories:** Epic 2 (Stories 2.1.1, 2.1.5), Epic 3 (Feature 3.3), Epic 9 (Story 9.3.1) + +### 5. Agent from Software Template (UC-10) + +**Goal:** Bootstrap a new agent project using a Backstage Software Template with boilerplate, CI/CD, and Kagenti registration. + +**How it works:** + +1. Navigate to Backstage Software Templates catalog +2. Select agent template (LangGraph, CrewAI, Python A2A, etc.) +3. Scaffolder wizard collects: name, description, namespace, repo, framework options +4. Generates: source code, Dockerfile, CI/CD pipeline, Kagenti manifest, MCP tool definitions +5. Project created in source repo with initial commit +6. CI/CD builds container and registers agent on merge +7. Developer opens generated project to customize logic + +**Epics/Stories:** Epic 3 (Feature 3.3, Stories 3.7.3, 3.7.6) + +### 6. Agent from DevSpaces (UC-11) + +**Goal:** Write agent code from scratch in a cloud development environment, build as a container, deploy to Kagenti. + +**How it works:** + +1. Kagenti admin → DevSpaces → configure workspace +2. Cloud IDE launches with agent SDK/ADK pre-installed +3. Developer writes agent in chosen framework +4. Test in sandbox environment +5. Trigger Shipwright container build from admin panel +6. Build pipeline panel shows status, logs, history in real time +7. On success: deployed as K8s workload, discovered via A2A protocol +8. Agent appears in gallery + +**Epics/Stories:** Epic 3 (Stories 3.7.6, 3.7.3, 3.8.1-3.8.2, 3.1.1) + +### 7. Import an Existing Agent (UC-12) + +**Goal:** Bring an already-built agent (container image or source repo) and make it available through Augment. + +**Container image flow:** + +1. Provide container image reference (e.g., quay.io/team/my-agent:latest) +2. Configure deployment: namespace, resource limits, env vars, MCP connections +3. Kagenti deploys as K8s workload, discovers via A2A +4. Agent appears in gallery with auto-detected capabilities + +**Source code flow:** + +1. Provide source repo URL +2. Configure build settings → Shipwright build triggered +3. On success: deployed and registered + +**Additional options:** Auth Bridge/SPIRE security toggles, namespace scoping, image tag updates for versioning. + +**Epics/Stories:** Epic 3 (Stories 3.1.1, 3.3.1-3.3.3, 3.5.1, 3.6.1-3.6.2) + +### 8. Configure MCP Tools (UC-13) + +**Goal:** Connect agents to live systems by registering MCP servers, configuring authentication, and setting tool approval policies. + +**How it works:** + +1. Admin panel → MCP Servers (Llama Stack) or Tools (Kagenti) +2. Add server: URL, transport (Streamable HTTP / SSE), display name +3. Configure authentication: OAuth client credentials, K8s ServiceAccount token, static headers, or infrastructure-level mTLS (Kagenti) +4. Test connection — system auto-discovers available tools +5. Configure per-server/per-tool `requireApproval` policies +6. Scope tools to specific agents (per-agent tool subsets) +7. Save — tools immediately available to configured agents + +**Kagenti-specific:** CreateToolWizard (3 steps: basics, runtime, deploy), ToolInvokeDialog for direct testing, backend proxy mode for air-gapped environments. + +**Epics/Stories:** Epic 7 (Features 7.1-7.3), Epic 3 (Feature 3.4) + +### 9. Skills Marketplace Integration + +**Goal:** Integrate with an external skills marketplace (provided by a separate workspace) to browse, select, and deploy pre-built skills-based agents into the Augment environment. + +**Note:** Augment does not own or implement the skills marketplace itself. The marketplace is provided by another workspace/team. Augment is a consumer that proxies requests to the external skills catalog and handles the deployment of selected skills into the local Kagenti environment. + +**How it works:** + +1. Admin navigates to the Skills section in the admin panel +2. Augment proxies browse/filter requests to the external skills catalog backend +3. Admin selects a skill → Augment generates the K8s deployment manifest with init container for OCI skill extraction +4. Deploy skill agent to local namespace → deployment progress polling shows status +5. Deployed skill agents appear in the Augment gallery with a `DocsClaw` framework label and skill badge + +**Integration architecture:** + +- `GET /skills` proxies to the external skills catalog backend (endpoint configured via `augment.skillsMarketplace.endpoint`) +- `GET /skills/runtimes` and `GET /skills/domains` proxy filter metadata from the external catalog +- Augment handles deployment only: K8s manifest generation, OCI init containers, namespace scoping +- Deployed skills agents carry a `chatEndpoint` field for direct chat routing within Augment + +### 10. Backstage Catalog Representation + +**Goal:** Model AI domain objects (agents, tools, models, MCP servers, vector stores) as Backstage catalog entities for discoverability, ownership, search, and RBAC integration. + +**Entity types and providers:** + +| Domain Object | Entity Kind | `spec.type` | Entity Provider | Lives In | Polling Interval | +| ------------------ | ----------- | -------------- | ------------------------------- | --------------------------- | ---------------- | +| Kagenti Agents | `Component` | `ai-agent` | `KagentiAgentEntityProvider` | Kagenti provider module | 5 min | +| Kagenti Tools | `Resource` | `ai-tool` | `KagentiToolEntityProvider` | Kagenti provider module | 5 min | +| Llama Stack Models | `Resource` | `ai-model` | `LlamaStackModelEntityProvider` | Llama Stack provider module | 60s | +| Llama Stack Agents | `Component` | `ai-agent` | `LlamaStackAgentEntityProvider` | Llama Stack provider module | 5 min | +| MCP Servers | `Resource` | `mcp-server` | `McpEntityProvider` | Core plugin (cross-cutting) | 5 min | +| Vector Stores | `Resource` | `vector-store` | `VectorStoreEntityProvider` | Core plugin (cross-cutting) | 10 min | + +**Architecture:** Entity providers are **independently deployable Backstage backend services**, each packaged as its own RHDH dynamic plugin: + +- `llamastack-entity-provider` — emits Llama Stack models and agents as catalog entities. Loadable standalone (without the rest of boost) for RHDH deployments that use Llama Stack but don't need the full agentic portal. +- `kagenti-entity-provider` — emits Kagenti agents and tools as catalog entities. Loadable standalone for RHDH deployments that use Kagenti but don't need the full portal. + +These packages live at `rhdh-plugins/workspace/boost/plugins/` and are registered as Backstage backend services per the [Backstage backend system architecture](https://backstage.io/docs/backend-system/architecture/services/). When the full `boost-backend` plugin is installed, it composes these same entity provider packages internally alongside the agentic provider modules. Cross-cutting entities (MCP servers, vector stores) that aren't provider-specific live in the core plugin. + +**Entity kind strategy:** + +- Agents use `kind: Component` with `spec.type: ai-agent` as the immediate path. When upstream Backstage `AIContext` kind is available, agents will migrate to the purpose-built kind. +- Models, MCP servers, vector stores, and tools use `kind: Resource` with discriminated `spec.type` values. +- Agent capabilities (tools, knowledge bases, downstream agents) map to `spec.dependsOn` relations. + +--- + +## Architecture Context + +**Agent creation paths converge:** +All four creation paths (no-code, template, DevSpaces, import) plus skills marketplace produce a `ChatAgent` — a unified agent model with `id`, `name`, `providerType`, `lifecycleStage`, `createdBy`, and `ChatAgentConfig`. Agents progress through a 4-stage lifecycle: `Draft` → `Pending` → `Published` → `Archived`. + +Boost uses the 4-stage model from the start — no legacy stage mappings or normalization layers needed. + +**Agent lifecycle and ownership:** + +- `createdBy` field set at registration, used for visibility filtering, action gating, and self-approval prevention +- Non-admins see: published agents + own draft/pending agents + unowned legacy agents +- Governance registration required before lifecycle promotion (`governanceRegistered` flag) +- Cascading delete: `DELETE /agents/:id` detects source (kagenti/orchestration/workflow) and cleans up across all corresponding stores + +**Agent discovery pipeline:** + +- `buildUnifiedAgentList()` merges agents from all providers +- `GET /agents?published=true` → `useAgentGalleryData()` (155ms timeout, guard merge + dedup) → `AgentCatalogDialog` +- Featured agents configured via `ChatExperiencePanel` +- Future: gallery reads from Backstage catalog entities instead of in-memory caches + +**Backstage catalog integration:** + +- Entity providers are independently deployable backend services: `llamastack-entity-provider` and `kagenti-entity-provider` +- Each is loadable as a standalone RHDH dynamic plugin (without the rest of boost) or composed into the full `boost-backend` +- Kagenti entity provider emits agents and tools; Llama Stack entity provider emits models and agents +- Cross-cutting entities (MCP servers, vector stores) are emitted by the core plugin +- Eliminates duplicate in-memory caches and enables Backstage-native search, ownership, and RBAC + +**Skills marketplace integration:** + +- Augment proxies browse/filter requests to an external skills catalog backend (separate workspace) +- Augment owns deployment only: K8s manifest generation with OCI init containers +- Deployed skill agents carry `framework: 'docsclaw'` and `chatEndpoint` field + +**Kagenti admin surface:** +Home Dashboard, Agents, Tools, Build Pipelines, Sandbox, Platform Links, Dashboard Links, Admin Settings. UI uses "Save to My Agents" (green button) instead of "Publish". Review Queue filters by normalized lifecycle stage. + +**MCP architecture:** + +- 4-level auth chain: auth references → per-server OAuth → ServiceAccount tokens → global fallback +- `McpAuthService` with caching and deduplication +- Backend execution mode (`BackendToolExecutor`) for air-gapped environments +- Tool scoping: per-agent allowed tool subsets via configuration + +See architecture diagrams: `arch-diagrams/06-backend-detail-provider-framework.png`, `arch-diagrams/06-backend-detail-provider-framework-may26.png`, `arch-diagrams/08-backend-detail-kagenti.png`, `arch-diagrams/08-backend-detail-kagenti-may26.png` + +See flow diagrams: `use-case-flow-diagrams/UC-4.png`, `UC-4-may26.png`, `UC-7.png`, `UC-7-may26.png` through `UC-13.png`, `UC-23-may26.png`, `UC-24-may26.png`, `UC-25-may26.png` + +--- + +## Traceability + +| Capability | Use Case | Priority | Stories | +| ------------------------------ | -------- | -------- | -------------------------------------- | +| Browse & Select Agent | UC-4 | P1 | 3.2.1-3.2.5, 1.5.2-1.5.3 | +| Create Agent (umbrella) | UC-7 | P0 | 2.1.1, 3.3.1-3.3.3, 3.4.1-3.4.3 | +| No-Code Builder | UC-8 | P0 | 2.1.1, 2.1.5, 3.3.1-3.3.3, 9.3.1 | +| Gallery Discovery | UC-9 | P1 | 3.2.1-3.2.5, 4.5.1, 9.4.3 | +| Agent from Template | UC-10 | P1 | 3.3.1-3.3.3, 3.7.3, 3.7.6 | +| Agent from DevSpaces | UC-11 | P1 | 3.7.6, 3.7.3, 3.8.1-3.8.2, 3.1.1 | +| Import Existing Agent | UC-12 | P0 | 3.1.1, 3.3.1-3.3.3, 3.5.1, 3.6.1-3.6.2 | +| Configure MCP Tools | UC-13 | P1 | 7.1.1-7.1.2, 7.2.1, 7.3.1, 3.4.1-3.4.3 | +| Skills Marketplace Integration | (new) | P1 | (new) | +| Catalog Entities | (new) | P2 | (new) | + +--- + +## Customer Context + +Derived from the Citi engagement. Success outcomes addressed: + +- Specialist agents collaborate on complex, multi-step tasks (UC-7, UC-8, UC-10, UC-11, UC-12) +- Teams bring their own agents built in any framework (UC-10, UC-11, UC-12) +- Agents act on live systems/applications with human oversight (UC-13) +- Self-service developer onboarding reduces support volume (UC-4, UC-7) diff --git a/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md b/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md new file mode 100644 index 0000000000..79a69c44e9 --- /dev/null +++ b/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md @@ -0,0 +1,240 @@ +# PRD: AI Chat & Interaction Experience + +**Product:** Boost — Agentic Developer Portal for Red Hat Developer Hub +**Status:** Requirements for new implementation (informed by Augment reference prototype) +**Date:** 2026-05-19 +**Updated:** 2026-06-02 — reframed for boost; composable extensions with lazy loading from day one, UX/UXD-driven development +**Priority:** P0 +**Provenance:** Requirements derived from Augment plugin analysis. See `specifications/boost-context.md` for project context. + +--- + +## Why + +Augment's core value proposition is enabling developers to have intelligent, grounded conversations with specialist AI agents — directly within their developer portal. Without a compelling chat experience, the platform has no user-facing value regardless of what's configured behind it. + +This PRD defines the primary interaction surface: the streaming chat interface, knowledge-grounded answers, human-in-the-loop approval controls, conversation history management, and developer debugging tools. Together, these capabilities form the "inner loop" of the developer-agent relationship. + +## What This Product Does + +A developer opens Boost in Red Hat Developer Hub, asks a question in natural language, and receives a real-time streamed answer from a specialist AI agent. The answer may be grounded in the organization's own documentation (RAG), may involve tool calls that require human approval (HITL), and is persisted so the developer can return to it later. Professional developers can inspect the full execution trace for transparency and debugging. + +## Who It's For + +### Citizen Developer + +Business domain expert or non-traditional developer who uses AI agents through the chat interface. Asks questions, receives answers, approves or rejects sensitive actions, and reviews past conversations. + +### Professional Developer + +Engineer who additionally uses debug/inspection tools to understand agent behavior, verify reasoning chains, and troubleshoot issues. + +## Boundaries + +### In Scope + +- Streaming chat with real-time phase indicators and rich message rendering +- Knowledge-grounded answers (RAG) with source citations +- Human-in-the-loop approval for sensitive agent actions (tool calls) +- Interactive cards (forms, auth flows) within conversations +- Conversation history with search, resume, feedback, and export +- Developer tools: execution trace, session inspector, message inspector +- Provider-adaptive chat experience (Llama Stack vs Kagenti paths) + +### Out of Scope + +- Agent creation and lifecycle management (see Agent Creation & Discovery PRD) +- AI provider selection and hot-swap (see Platform Architecture PRD) +- Platform deployment and runtime configuration (see Platform Operations PRD) +- Safety shields and security posture (see Security & Governance PRD) + +### UX/UXD Integration + +All frontend components and UI flows must align with RHDH usability and visual design standards. This requires interlocking with the UX/UXD team throughout development: + +- **Mockups as source of truth:** UI implementation follows mockups, wireframes, and design specs provided by UX/UXD (Figma, Sketch, or equivalent). No frontend feature ships without a corresponding approved design artifact. +- **PatternFly alignment:** All components use PatternFly design system components and patterns consistent with the broader RHDH experience. Custom components require UX/UXD review. +- **Design review gates:** Frontend PRs that introduce or modify user-visible UI require UX/UXD sign-off before merge. This applies to chat message rendering, approval dialogs, conversation history, agent gallery, admin panels, and all interactive cards. +- **Accessibility:** All UI meets WCAG 2.1 AA standards consistent with RHDH accessibility requirements. Keyboard navigation, screen reader support, and color contrast are validated against UX/UXD accessibility guidelines. + +--- + +## Capabilities + +### 1. Streaming Chat (UC-1) + +**Goal:** Ask a question in natural language and receive a streamed, grounded answer from a specialist AI agent with reasoning visible in real time. + +**How it works:** + +- User types a question in the chat input +- The system sends the message to the active AI provider; streaming begins +- Real-time phase indicators show progress: thinking, reasoning, searching, calling tools, generating +- The response renders incrementally: markdown, code blocks with syntax highlighting, reasoning summary, source citations (if RAG), token usage +- Conversation is auto-saved on completion + +**Provider-specific behavior:** + +- **Llama Stack path:** Messages route to the configured default agent. A router agent may hand off to a specialist mid-conversation. The user sees a handoff divider: "Handed off from [Agent A] to [Agent B]." +- **Kagenti path:** User must select an agent from the gallery before sending the first message. The chat header shows agent name, streaming/A2A mode, namespace, and health status. + +**Resilience:** Provider-offline banner when the AI platform is unreachable. Error cards displayed inline on agent errors (no page crash via error boundary). + +**Success outcome:** Developer receives a grounded answer with visible reasoning. Conversation is persisted and resumable. + +**Epics/Stories:** Epic 4 (Features 4.1, 4.2, 4.5, 4.6), Epic 1 (Feature 1.5) + +### 2. Knowledge-Grounded Answers / RAG (UC-2) + +**Goal:** Ask about internal documentation, runbooks, or policies and receive an answer grounded in the organization's knowledge base, with source citations. + +**How it works:** + +- User asks a question about internal documentation +- The agent determines retrieval is relevant and searches the knowledge base; UI shows "Searching knowledge base..." in real time +- The response includes a RAG sources section: document name, chunk text, relevance score +- User can expand sources to verify the answer against original documentation + +**Edge cases:** + +- No relevant results: agent indicates it could not find relevant information and answers from general knowledge, noting the limitation +- Multiple knowledge bases: searches across all configured vector stores, showing which store each source came from + +**Success outcome:** Answers cite specific internal documents. Developers can trace every claim to a source. + +**Epics/Stories:** Epic 6 (Feature 6.1), Epic 4 (Story 4.2.4) + +### 3. Human-in-the-Loop Approval (UC-3) + +**Goal:** Review a proposed agent action (tool call) before it executes, with the ability to edit parameters, approve, or reject. + +**How it works:** + +- Agent proposes a tool call requiring approval (per configured policy) +- Approval dialog shows tool name, target system, and exact arguments +- User reviews, optionally edits parameters via JSON editor, then approves or rejects +- On approval: backend resumes the paused inference loop, tool executes, result flows back into the conversation +- On rejection: agent adjusts its approach + +**Additional interactive patterns:** + +- **Form cards:** Agent requests structured input via typed form fields +- **Auth cards:** Agent requires external authentication via OAuth sign-in flow +- **Auto-approve:** Read-only tools configured with `requireApproval: false` execute automatically + +**Audit:** Every approval decision is stored in session history. + +**Success outcome:** No destructive action executes without explicit developer consent. Approval trail is auditable. + +**Epics/Stories:** Epic 5 (Features 5.1, 5.2) + +### 4. Conversation History (UC-5) + +**Goal:** Return to past conversations, search history, provide feedback, and export sessions. + +**How it works:** + +- Right pane shows grouped sessions with search, scoped to the active provider +- User selects a past session (confirmation dialog if a stream is active) +- Full conversation loads with all messages, tool calls, and metadata +- User can continue the conversation or review past exchanges + +**Interactions:** + +- Search by keyword +- Delete sessions +- Thumbs up/down feedback with optional reasons on individual messages +- Edit and regenerate past questions +- Copy message content +- Export full conversation +- Admin: toggle "Show all users" to view cross-user sessions + +**Success outcome:** Conversations are persistent, searchable, and actionable. + +**Epics/Stories:** Epic 4 (Features 4.3, 4.4, 4.7) + +### 5. Debug & Inspect Agent Execution (UC-6) + +**Goal:** Understand what an agent did, which tools it called, and why — using developer tools for transparency and troubleshooting. + +**How it works:** + +- User enables dev mode via chat header toggle +- **Execution trace panel:** Step-by-step trace — each agent turn, tool call, and reasoning step as a span +- **Message inspector:** Raw payload for a specific message +- **Session state inspector:** Full session JSON (session ID, message count, provider, agent, metadata) + +**Additional features:** + +- Tool call drill-down: expand to see full input arguments and output +- Reasoning inspection: expand to see full chain-of-thought +- Phase chips: visible in dev mode showing timing of each phase +- Keyboard shortcuts for power user navigation + +**Success outcome:** User understands the agent's reasoning path, tool calls, and data flow. + +**Epics/Stories:** Epic 4 (Feature 4.7) + +--- + +## Architecture Context + +The chat experience spans the full plugin stack: + +**Frontend (`plugins/augment/src/`):** + +- `ChatContainer` orchestrates the chat experience (welcome vs thread mode) +- `StreamingMessage` with `StreamingProgress` for real-time rendering +- `ChatInput` for composition with agent selection +- `ToolApprovalDialog` for HITL flows +- `VirtualizedMessageList` for performant message display +- `RightPane` with `ConversationHistory` and `AgentInfoSection` +- `ExecutionTracePanel`, `SessionStateInspector`, `MessageInspectorPanel` for dev tools + +**Frontend composability (boost design principles):** +Boost builds composable from the start, avoiding augment's monolithic frontend patterns: + +- Composable routable extensions (`BoostChatPage`, `BoostAdminPage`, `BoostAgentStudioPage`) with `React.lazy()` at extension boundaries +- Config-driven feature flags (`boost.features.*`) to toggle features per deployment +- All UI surfaces (CommandCenter, Skills, Marketplace, ToolRegistry) lazy-loaded by default +- No component exceeds reasonable size without decomposition +- All UI built from UX/UXD-provided mockups with PatternFly alignment + +**Backend (`plugins/augment-backend/src/`):** + +- `chatRoutes.ts`: POST `/chat/stream`, POST `/chat/approve` +- `sessionRoutes.ts`: GET `/sessions`, GET `/sessions/:id/messages` +- `ChatSessionService`: session persistence (SQLite dev, PostgreSQL prod) +- `BackendApprovalStore` / `BackendApprovalHandler`: HITL continuation +- Streaming pipeline: `createStreamEventForwarder` → provider → `NormalizedStreamEvent` → SSE + +**Common (`plugins/augment-common/`):** + +- `NormalizedStreamEvent` union type covering all stream event categories +- Permission contracts: `augmentAccessPermission`, `augmentAdminPermission` + +See architecture diagrams: `arch-diagrams/00-frontend-architecture.png`, `arch-diagrams/00-frontend-architecture-may26.png`, `arch-diagrams/04-streaming-pipeline.png`, `arch-diagrams/04-streaming-pipeline-may26.png` + +See flow diagrams: `use-case-flow-diagrams/UC-1.png` through `UC-6.png`, `UC-9-may26.png` + +--- + +## Traceability + +| Capability | Use Case | Priority | Stories | +| -------------------- | -------- | -------- | --------------------------------------------------------------- | +| Streaming Chat | UC-1 | P0 | 4.1.1-4.1.4, 4.2.1-4.2.6, 1.5.1-1.5.7, 2.1.2-2.1.3, 8.5.1-8.5.2 | +| Knowledge Q&A (RAG) | UC-2 | P0 | 6.1.1-6.1.3, 4.2.4 | +| HITL Approval | UC-3 | P0 | 5.1.1-5.1.3, 5.2.1-5.2.3 | +| Conversation History | UC-5 | P0 | 4.3.1-4.3.3, 4.4.1-4.4.3, 4.7.4, 1.5.5 | +| Debug & Inspect | UC-6 | P2 | 4.7.1-4.7.5, 4.2.3, 4.2.5 | + +--- + +## Customer Context + +Derived from the Citi engagement ("Cloud Concierge" vision). Citi's success outcomes addressed by this PRD: + +- Developers get answers from internal knowledge without leaving the portal (UC-1, UC-2) +- Sensitive operations stay under human control (UC-3) +- Agents act on live systems/applications with human oversight (UC-3) diff --git a/workspaces/boost/specifications/prd/platform-operations-deployment.md b/workspaces/boost/specifications/prd/platform-operations-deployment.md new file mode 100644 index 0000000000..dcc94133b4 --- /dev/null +++ b/workspaces/boost/specifications/prd/platform-operations-deployment.md @@ -0,0 +1,304 @@ +# PRD: Platform Operations & Deployment + +**Product:** Boost — Agentic Developer Portal for Red Hat Developer Hub +**Status:** Requirements for new implementation (informed by Augment reference prototype) +**Date:** 2026-05-19 +**Updated:** 2026-06-02 — reframed for boost; Zod schema-driven validation from day one, cacheService throughout, modular dynamic plugin deployment +**Priority:** P0 (deployment, runtime config, agent management, RAG) / P1 (white-labeling) +**Provenance:** Requirements derived from Augment plugin analysis. See `specifications/boost-context.md` for project context. + +--- + +## Why + +An agentic AI platform that requires code changes, rebuilds, or restarts for every configuration change is unusable in production. Administrators need to deploy the plugin cleanly, manage agents and their orchestration rules, configure knowledge pipelines, tune 25+ runtime parameters, and white-label the experience — all without touching source code or restarting the deployment. + +This PRD defines the platform operations surface: deployment paths, agent and orchestration management, RAG pipeline configuration, runtime configuration engine, and branding customization. + +## What This Product Does + +Boost deploys as a set of modular dynamic plugins (RHDH) or static plugins (Backstage) with zero code changes. Core plugin and provider modules are independently installable from day one. Once deployed, administrators manage agents, configure RAG pipelines, change runtime configuration (model, prompts, tools, caps, appearance), and white-label the portal — all at runtime via the admin panel, with changes taking effect within seconds. Configuration validation uses Zod schemas as single source of truth from the start. + +## Who It's For + +### Administrator + +Deploys the platform, manages agents and orchestration rules, configures RAG knowledge pipelines, tunes runtime configuration, and customizes branding. + +## Boundaries + +### In Scope + +- Plugin deployment: RHDH dynamic plugin (OCI) and Backstage static plugin (npm) +- Agent and orchestration management (admin panel) +- RAG knowledge pipeline configuration (document ingestion, vector stores, RAG playground) +- Runtime configuration engine (YAML baseline + database overrides, 25+ keys) +- White-label branding (name, logo, colors, welcome screen, featured agents) +- Admin onboarding experience + +### Out of Scope + +- Chat interaction (see AI Chat & Interaction PRD) +- Agent creation paths (see Agent Creation & Discovery PRD) +- Provider architecture and hot-swap (see Platform Architecture PRD) +- Security posture and safety shields (see Security & Governance PRD) + +### UX/UXD Integration + +Admin panels, branding controls, RAG configuration, and onboarding flows must align with RHDH usability and visual design standards: + +- **Mockups as source of truth:** Admin panel layouts, config editors, RAG playground, branding controls, and onboarding cards are built from UX/UXD-provided mockups. No admin-facing UI ships without an approved design artifact. +- **PatternFly alignment:** All admin components use PatternFly design system patterns. Custom config editors, knowledge base panels, and branding controls require UX/UXD review. +- **Design review gates:** Frontend PRs modifying admin-facing UI require UX/UXD sign-off before merge. + +--- + +## Capabilities + +### 1. Deploy Boost (UC-15) + +**Goal:** Install and configure Boost in an RHDH or vanilla Backstage instance. + +**Workspace package structure:** + +All packages live at `rhdh-plugins/workspace/boost/plugins/`: + +| Package | Type | Description | +| --------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- | +| `boost-frontend` | Frontend plugin | Chat UI, agent gallery, admin panels, composable extensions | +| `boost-common` | Common library | Shared types (`AgenticProvider`, `NormalizedStreamEvent`, permissions), `augmentAiProviderServiceRef` | +| `boost-backend` | Backend plugin | Core routes, services, middleware, `ProviderManager`, cross-cutting entity providers (MCP, vector stores) | +| `boost-backend-module-llamastack` | Backend module | Llama Stack agentic provider (composes `llamastack-entity-provider`) | +| `boost-backend-module-kagenti` | Backend module | Kagenti agentic provider (composes `kagenti-entity-provider`) | +| `llamastack-entity-provider` | Backend service | Llama Stack model + agent catalog entities (independently deployable) | +| `kagenti-entity-provider` | Backend service | Kagenti agent + tool catalog entities (independently deployable) | + +**RHDH — Dynamic Plugin (recommended):** + +1. Obtain OCI-packaged dynamic plugin images for all needed packages +2. Configure `dynamic-plugins.override.yaml` with plugin references and configuration +3. Set up `app-config.yaml` with Boost configuration: provider settings, security mode, base URLs +4. RHDH loads plugins dynamically via Scalprum — no code changes or rebuilds +5. Boost appears as a sidebar entry in RHDH + +**Full portal deployment** installs `boost-frontend`, `boost-common`, `boost-backend`, plus one or both provider modules. Provider modules compose their entity providers internally. + +**Entity-provider-only deployment** installs `llamastack-entity-provider` or `kagenti-entity-provider` as standalone dynamic plugins — gets AI domain objects in the Backstage catalog without the rest of boost. + +**Backstage — Static Plugin:** + +1. Install npm packages: `@boost/plugin-boost-frontend`, `@boost/plugin-boost-backend`, `@boost/plugin-boost-common` +2. Optionally install provider modules: `@boost/plugin-boost-backend-module-llamastack`, `@boost/plugin-boost-backend-module-kagenti` +3. Register frontend route, sidebar entry, and icon +4. Register backend plugin and provider modules in backend startup +5. Configure `app-config.yaml` +6. Rebuild and deploy + +**Epics/Stories:** Epic 10 (Features 10.1, 10.2) + +### 2. Manage Platform Agents and Orchestration (UC-17) + +**Goal:** Create, edit, delete, and configure agents and their orchestration rules from the admin panel. + +**Llama Stack flow:** + +- Agents panel shows all configured agents with status +- Create agent: name, instructions, model, temperature, tools, knowledge base, handoff targets +- Configure router agent as default entry point delegating to specialists +- Define handoff rules: which agents can transfer to which +- Save — agents immediately available in chat + +**Kagenti flow:** + +- Kagenti admin sidebar → home dashboard with summary cards +- Agents catalog across all namespaces +- Create, edit, delete agents via agent detail view (tabs: details, resources, status, agent card) +- Manage tools via tools panel +- Monitor build pipelines, manage sandbox sessions +- Configure namespace scoping and access controls + +**Additional features:** + +- Agent template browser for bootstrapping +- Namespace picker for multi-tenant scoping +- Observability links: Jaeger, Kiali, MCP inspector, Keycloak console + +**Epics/Stories:** Epic 2 (Stories 2.1.1-2.1.6), Epic 3 (Features 3.3-3.4, 3.6-3.7), Epic 9 (Story 9.3.1) + +### 3. Configure RAG Knowledge Pipelines (UC-18) + +**Goal:** Ingest customer documentation into vector stores so agents can ground their answers in real data. + +**How it works:** + +1. Admin panel → Knowledge Base +2. Create vector store: configure search mode (semantic, keyword, or hybrid) +3. Add document sources: + - GitHub repository (public/private, path filters, glob patterns) + - URL (web page fetch and chunk) + - File upload (drag-and-drop via IngestDropZone) +4. Configure sync schedule (e.g., hourly) with full or append mode +5. Ingestion pipeline: fetch content → detect changes via content hash → chunk text → push to vector store on AI platform +6. Scope vector store to specific agents via per-agent `vectorStoreIds` +7. Test retrieval quality in RAG playground: test queries, retrieved chunks with relevance scores, adjustable thresholds + +**Change detection:** Subsequent syncs only re-ingest changed files; deleted files are removed from the store. + +**Multiple stores:** Separate vector stores for different domains (migration docs, runbooks, API docs), each scoped to the relevant agent. + +**Admin UI components:** + +- `KnowledgeBasePanel` with `KBManageStores`, `KBCreateStore`, documents table, sync trigger +- `IngestDropZone` for file upload +- `KBRagTest` with `RagQueryForm`, `RagResultsTable`, `ChunkCard`, `ScoreBar`, `GeneratedAnswerCard` + +**Backend:** `DocumentIngestionService` with multi-source fetching, content-hash change detection, chunking. + +**Epics/Stories:** Epic 6 (Features 6.1, 6.2) + +### 4. Manage Runtime Configuration (UC-21) + +**Goal:** Change Augment's behavior at runtime — model, system prompt, tools, caps, and more — without restarting. + +**Configuration engine:** + +- Two-layer resolution: YAML baseline + `AdminConfigService` database overrides +- `RuntimeConfigResolver` resolves values with database overrides taking precedence; cache backed by Backstage `cacheService` with 30s TTL and immediate invalidation on write +- 25+ configurable keys (schema has grown to 1,500+ lines) +- If database value is removed, YAML baseline is restored + +**Schema-driven validation (target architecture):** + +- Replace 668+ lines of hand-written validators in `configValidation.ts` with Zod schemas as single source of truth +- TypeScript `config.d.ts` generated from Zod schemas +- DB validators match YAML schema validation — no drift +- Each config field annotated with `configScope`: `yaml-only`, `db-overridable`, or `db-only` + +**Configurable categories:** + +- **Model Connection:** Base URL, model name, connection test +- **System Prompt:** Edit or use LLM-assisted prompt generation (`GeneratePromptForm`) +- **Tools and Capabilities:** Enable/disable tools, set allowed tool subsets +- **Agent Configuration:** Per-agent model, temperature, max tokens, tool choice +- **Agent Approval:** Governance workflow configuration, SonataFlow integration +- **Skills Marketplace Integration:** External skills catalog endpoint (provided by separate workspace), runtime filters, domain filters +- **Token and Turn Caps:** Maximum output tokens, tool calls per turn, agent turns +- **Chat Experience:** Featured agents, conversation starters (Kagenti) +- **Appearance:** Logo, colors, theme presets +- **Kagenti Auth:** Token exchange configuration (`tokenExchange.enabled`, `audience`, `userTokenHeader`) +- **DevSpaces:** Workspace configuration (credentials must be stored encrypted, not plaintext) + +**Admin onboarding:** `AdminOnboardingCard` provides guided setup steps on first admin visit. + +**Epics/Stories:** Epic 9 (Features 9.1-9.3, 9.5-9.6) + +### 5. White-Label the Portal (UC-22) + +**Goal:** Customize the Augment experience to match the organization's brand — all at runtime. + +**Customizable elements:** + +- Application name and logo +- Color theme (from presets or custom) +- Welcome screen hero content +- Prompt groups: create/edit with icons, colors, suggested prompts; reorder; live preview +- Featured agents for welcome screen strip (Kagenti) +- Conversation starters per agent (Kagenti) + +**Admin UI components:** + +- `BrandingPanel` → `AppearanceSection` (logo, colors, themes) +- `PromptsPanel` → `GroupEditor`, `CardEditor`, `IconPicker`, `ColorPicker`, `LivePreview` +- `ChatExperiencePanel` → agent gallery configuration, conversation starters + +**All changes apply at runtime.** Users see updated branding immediately. No deployment or restart required. + +**Epics/Stories:** Epic 9 (Feature 9.4) + +--- + +## Architecture Context + +**Runtime configuration engine:** + +``` +app-config.yaml (YAML baseline) + ↓ +RuntimeConfigResolver (cacheService-backed, 30s TTL) + ↓ (merges) +AdminConfigService (DB overrides, augment_admin_config table) + ↓ +Zod schema validation (single source of truth) + ↓ +Resolved config value + ↓ (immediate invalidation on write via cache.delete()) +Backend services + Frontend via admin API +``` + +**Database layer:** + +- 6 tables in Backstage database (SQLite dev, PostgreSQL prod) +- `augment_admin_config`: runtime configuration overrides +- `augment_sessions`: conversation persistence +- `augment_messages`: message history +- `augment_feedback`: user feedback on messages + +**Deployment models:** + +``` +RHDH Dynamic Plugin (full portal): + boost-frontend + boost-common + boost-backend + provider module(s) + OCI images → dynamic-plugins.override.yaml → Scalprum → sidebar entry + No code changes, no rebuilds + +RHDH Dynamic Plugin (entity providers only): + llamastack-entity-provider and/or kagenti-entity-provider + Catalog entities without the full portal + No boost-backend or boost-frontend needed + +Backstage Static Plugin: + npm packages → manual registration → rebuild → deploy + Provider modules and entity providers optionally installed alongside core +``` + +**Knowledge pipeline:** + +``` +Sources (GitHub, URL, File Upload) + → DocumentIngestionService + → Content-hash change detection + → Chunking + → Vector Store (OpenShift AI) + → Per-agent vectorStoreIds scoping + → Agent RAG queries at chat time +``` + +See architecture diagrams: `arch-diagrams/02-backend-architecture-overview.png`, `arch-diagrams/02-backend-architecture-overview-may26.png`, `arch-diagrams/05-backend-detail-routes.png`, `arch-diagrams/05-backend-detail-routes-may26.png`, `arch-diagrams/09-backend-detail-services.png`, `arch-diagrams/09-backend-detail-services-may26.png` + +See flow diagrams: `use-case-flow-diagrams/UC-15.png` through `UC-22.png`, `UC-17-may26.png`, `UC-20-may26.png` + +--- + +## Traceability + +| Capability | Use Case | Priority | Stories | +| ----------------------------- | -------- | -------- | ---------------------------------------------------------------------- | +| Deploy Plugin | UC-15 | P0 | 10.1.1, 10.2.1 | +| Manage Agents & Orchestration | UC-17 | P0 | 2.1.1-2.1.6, 3.3.1-3.3.3, 3.4.1-3.4.3, 3.6.1-3.6.2, 3.7.1-3.7.6, 9.3.1 | +| Configure RAG Pipelines | UC-18 | P0 | 6.1.1-6.1.3, 6.2.1-6.2.3 | +| Runtime Configuration | UC-21 | P0 | 9.1.1, 9.2.1-9.2.3, 9.3.1, 9.5.1, 9.6.1 | +| White-Label Portal | UC-22 | P1 | 9.4.1-9.4.3 | + +--- + +## Customer Context + +Derived from the Citi engagement. Architecture principle: "Runtime-configurable. All configuration changes take effect without restart or redeployment." + +Citi's vision was for the portal to present as their own product ("Cloud Concierge"), not as a Red Hat product. White-labeling is foundational to the engagement, not cosmetic. + +Success outcomes addressed: + +- The portal experience is fully white-labeled (UC-22) +- Self-service developer onboarding reduces support volume (UC-15) +- Agents are grounded in customer knowledge (UC-18) diff --git a/workspaces/boost/specifications/prd/pluggable-ai-platform-architecture.md b/workspaces/boost/specifications/prd/pluggable-ai-platform-architecture.md new file mode 100644 index 0000000000..6cbe3c7ed1 --- /dev/null +++ b/workspaces/boost/specifications/prd/pluggable-ai-platform-architecture.md @@ -0,0 +1,342 @@ +# PRD: Pluggable AI Platform Architecture + +**Product:** Boost — Agentic Developer Portal for Red Hat Developer Hub +**Status:** Requirements for new implementation (informed by Augment reference prototype) +**Date:** 2026-05-19 +**Updated:** 2026-06-02 — reframed for boost; providers as RHDH dynamic plugins from day one, cacheService throughout, capability-based gating, catalog entity integration +**Priority:** P0 +**Provenance:** Requirements derived from Augment plugin analysis. See `specifications/boost-context.md` for project context. + +--- + +## Why + +Enterprise customers run different AI platforms — and they change their minds. A platform that hard-codes a single AI backend becomes a liability: vendor lock-in, inability to evaluate alternatives, and deployment friction when the AI strategy evolves. Augment must be the experience layer that sits above any AI platform, not a client of one specific platform. + +This PRD defines the pluggable provider architecture that makes Augment provider-agnostic: the abstraction interface, the normalized streaming protocol, runtime hot-swap, multi-agent orchestration via Llama Stack, and the framework-neutral Kagenti integration. + +## What This Product Does + +Boost abstracts AI platform backends behind a provider interface. Each provider is packaged as an independent RHDH dynamic plugin from day one. Multiple providers (Llama Stack, Kagenti, future platforms) are registered via a Backstage extension point and can be hot-swapped at runtime without downtime. Each provider's native events are normalized into a common streaming protocol so the frontend works identically regardless of which backend is active. The UI adapts via capability-based feature gating — never provider identity checks. All operational caches use Backstage `cacheService` from the start. + +## Who It's For + +### Professional Developer (Provider Integrator) + +Implements the `AgenticProvider` interface to add a new AI platform backend. Creates a Backstage backend module that registers the provider — no modification to Augment source code required. + +### Administrator + +Hot-swaps between configured providers at runtime. Monitors capability differences between providers. + +## Boundaries + +### In Scope + +- Provider abstraction interface (`AgenticProvider`, `ProviderDescriptor`, `AgenticProviderFactory`) +- `augmentAiProviderServiceRef` for cross-plugin provider consumption +- Backstage extension point for provider registration +- Provider types and interfaces in `augment-common` (not locked inside plugin) +- Normalized streaming protocol (`NormalizedStreamEvent`) +- Runtime provider hot-swap with rollback on failure +- Capability-based frontend feature gating (replacing provider ID string checks) +- Provider-adaptive chat experience (UI adapts per provider) +- Each provider packaged as an independent RHDH dynamic plugin +- Backstage `cacheService` for all operational caches (replacing home-grown `Map<>` caches) +- Llama Stack multi-agent orchestration (config-driven agents, handoffs, agents-as-tools) +- Kagenti provider (A2A protocol, K8s agent operations) +- ADK orchestration library (`@augment-adk/augment-adk`) +- Future provider placeholders (Google ADK) + +### Out of Scope + +- Chat UI and message rendering (see AI Chat & Interaction PRD) +- Agent creation and gallery (see Agent Creation & Discovery PRD) +- Safety shields and access control (see Security & Governance PRD) +- Admin panels and runtime config (see Platform Operations PRD) + +--- + +## Capabilities + +### 1. Provider Abstraction (Epic 1, Feature 1.1) + +**Goal:** Integrate any AI platform without forking the plugin. + +**How it works:** + +- `AgenticProvider` interface: `chat()` and `chatStream()` are required capabilities; RAG, safety, evaluation, and conversation are optional capability objects +- `ProviderDescriptor` declares the provider's ID, name, and supported capabilities +- `AgenticProviderFactory` instantiates the provider from config +- Registration via `augmentProviderExtensionPoint` in a Backstage backend module +- No Augment source modification required + +**Built-in providers:** + +- `ResponsesApiProvider` (Llama Stack): full-featured — chat, RAG, safety, evaluation, conversation +- `KagentiProvider` (Kagenti): K8s-native agent operations via A2A protocol + +### 2. Normalized Streaming Protocol (Epic 1, Feature 1.2) + +**Goal:** One event contract between all backend providers and the frontend. + +**How it works:** + +- `NormalizedStreamEvent` union type in the common package covers all `stream.*` events: text deltas, reasoning, tool calls, RAG results, handoffs, approvals, forms, auth, artifacts, citations, completion, errors +- Each provider implements a stream normalizer mapping native events to `NormalizedStreamEvent` +- **Llama Stack:** `normalizeLlamaStackEvent()` +- **Kagenti:** `KagentiStreamNormalizer` mapping A2A `TaskStatusUpdateEvent`/`TaskArtifactUpdateEvent` +- Frontend `StreamingMessage.reducer` processes normalized events identically regardless of source + +### 3. Provider Hot-Swap (Epic 1, Feature 1.3) + +**Goal:** Switch AI platform providers at runtime without downtime or data loss. + +**How it works:** + +1. Admin selects a different provider in the admin panel +2. `ProviderManager.switchProvider()`: start new provider → fully initialize → swap active pointer → shutdown old +3. On initialization failure: automatic rollback to previous provider with error notification +4. Frontend detects provider change and performs full reset: cancel active stream, reset conversation, clear messages, reset agent selection, clear input, trigger `onNewChat()` +5. UI adapts via capability-based feature gating: features unsupported by the new provider are hidden + +**Frontend adaptation details:** + +- Chat state reset on `providerId` change (Story 1.5.1) +- Mandatory agent selection for Kagenti, free-form for Llama Stack (Story 1.5.2) +- Welcome screen adapts: gallery strip for Kagenti, prompt groups for Llama Stack (Story 1.5.3) +- Agent info section adapts content per provider (Story 1.5.4) +- Conversation history scoped by `providerId` (Story 1.5.5) +- Chat header adapts: full for Kagenti, minimal for Llama Stack (Story 1.5.6) +- Admin shell adapts: KagentiSidebar (8 panels) vs CommandCenterHeader (3 panels) (Story 1.5.7) + +### 4. Integrate a New AI Platform Provider (UC-14) + +**Goal:** Add a new AI platform backend beyond Llama Stack and Kagenti. + +**Developer workflow:** + +1. Implement `AgenticProvider` interface (chat/chatStream required, optional capabilities) +2. Create `ProviderDescriptor` declaring ID, name, supported capabilities +3. Create `AgenticProviderFactory` that instantiates from config +4. Register via `augmentProviderExtensionPoint` in a Backstage backend module +5. Deploy module alongside Augment backend +6. New provider appears in admin panel's provider switcher — zero Augment source changes + +**Stream normalization:** Implement a stream normalizer mapping native events to `NormalizedStreamEvent` types. + +**Placeholder pattern:** Register provider with `implemented: false` as future placeholder (e.g., Google ADK). + +**Epics/Stories:** Epic 1 (Features 1.1-1.4) + +### 5. Switch AI Provider at Runtime (UC-16) + +**Goal:** Hot-swap between AI platform providers at runtime without downtime. + +**Admin workflow:** + +1. Open admin panel → provider switcher +2. View available providers with capabilities highlighted, active provider marked +3. Select different provider +4. Backend starts new provider, initializes fully, swaps pointer, shuts down old +5. Frontend auto-adapts: chat state resets, agent selection clears, admin sidebar switches, welcome screen updates, history re-scopes + +**Rollback:** If new provider fails to start, system rolls back automatically. Error notification shown. + +**Epics/Stories:** Epic 1 (Feature 1.3, Feature 1.5) + +### 6. Multi-Agent Orchestration — Llama Stack (Epic 2) + +**Goal:** Config-driven multi-agent orchestration without writing code. + +**How it works:** + +- Agents defined in YAML or admin config: name, instructions, tools, model, temperature, handoffs +- Assembled into `POST /v1/responses` calls against the Llama Stack endpoint +- `ResponsesApiCoordinator` generates `transfer_to_{agent}` functions for handoff routing +- Router agent delegates to specialists mid-conversation; context maintained via shared conversation ID +- Agents-as-tools pattern: `call_{agent}` for manager-specialist delegation while keeping control +- Per-agent config: model, temperature, max tokens, tool choice, MCP server subsets, vector store IDs + +**ADK library:** `@augment-adk/augment-adk` handles agent continuity, turn counting, handoff logic, tool execution. + +**Epics/Stories:** Epic 2 (Features 2.1) + +### 7. Kagenti — Framework-Neutral Agent Operations (Epic 3, Feature 3.1) + +**Goal:** Agents built in any framework (LangGraph, CrewAI, AG2, custom) are accessible via RHDH. + +**How it works:** + +- `KagentiProvider` with `KagentiApiClient`: Keycloak OAuth2, retry, namespace-scoped calls +- Speaks A2A protocol over SSE +- `KagentiStreamNormalizer` maps A2A events to `NormalizedStreamEvent` +- Agents deployed as K8s workloads, discovered via A2A protocol +- Namespace-scoped multi-tenancy with backend-enforced allowlists + +**Epics/Stories:** Epic 3 (Features 3.1, 3.6) + +### 8. Providers as RHDH Dynamic Plugins + +**Goal:** Each AI platform provider is packaged as an independent RHDH dynamic plugin that can be installed, removed, and upgraded independently. + +**How it works:** + +- Each provider is a `createBackendModule` (not a standalone plugin) that registers via `augmentProviderExtensionPoint` +- Provider modules have IDs: `llamastack` and `kagenti` +- Both are exported as OCI images for RHDH dynamic plugin loading +- Deployers install only the providers they need — no unused provider code loaded +- Provider modules depend on `augment-common` for shared types and `augmentAiProviderServiceRef` +- Boost ships modular from day one — no monolithic fallback needed + +**RHDH deployment example:** + +```yaml +# dynamic-plugins.override.yaml +- package: @augment/plugin-augment-backend-module-llamastack + integrity: sha512-... + disabled: false +- package: @augment/plugin-augment-backend-module-kagenti + integrity: sha512-... + disabled: false +``` + +### 9. Backstage cacheService Migration + +**Goal:** Replace all home-grown `Map<>` caches with Backstage `cacheService` for Redis backing, consistent TTL semantics, multi-instance safety, and proper cache invalidation. + +**Current state:** 17 caches identified across the codebase. Only 2 have been migrated to `cacheService` (KagentiAgentCardCache, Kagenti modelsCache). The remaining 15 use raw `Map<>` objects with inconsistent TTL, no size bounds, and no multi-instance coordination. + +**Migration strategy:** + +| Cache | Location | TTL | Priority | Notes | +| ---------------------------------- | --------------------------------------------------------------- | ------------------- | -------- | ---------------------------------------------------- | +| RuntimeConfigResolver | `services/RuntimeConfigResolver.ts` | 30s | P0 | Immediate invalidation on write via `cache.delete()` | +| ResponsesApiProvider.\_modelsCache | `providers/llamastack/ResponsesApiProvider.ts` | Match Kagenti | P1 | Eliminates model cache asymmetry | +| McpAuthService tokens | `providers/llamastack/auth/McpAuthService.ts` | From token expiry | P1 | Security-sensitive | +| KeycloakTokenManager | `providers/kagenti/client/KeycloakTokenManager.ts` | From token expiry | P1 | Security-sensitive | +| BackendToolExecutor | `providers/responses-api/tools/BackendToolExecutor.ts` | 5 min | P1 | Add max size limit | +| ConversationRegistry | `providers/responses-api/conversations/ConversationRegistry.ts` | 24h | P1 | Replaces unbounded Map | +| DocumentSyncService | `providers/responses-api/documents/DocumentSyncService.ts` | No expiry | P2 | Content hash tracking | +| KagentiProvider session maps | `providers/kagenti/KagentiProvider.ts` | Session duration | P2 | Session correlation | +| ClientManager | `providers/llamastack/ClientManager.ts` | Identity-keyed | P2 | HTTP client instances | +| EmbeddingCache (toolscope) | `services/toolscope/cache.ts` | Unbounded → bounded | P2 | Via injectable `CacheAdapter` | +| SessionCache (toolscope) | `services/toolscope/session.ts` | 1h | P2 | Via injectable `CacheAdapter` | +| ConfigResolutionService | `providers/llamastack/config/ConfigResolutionService.ts` | Delegates | P2 | Wrapper around RuntimeConfigResolver | +| conversationAgents | `OpenAIAgentsOrchestrator.ts` | Session-scoped | P3 | New cache | +| rateLimiter store | `middleware/rateLimiter.ts` | Per-window | P3 | New cache | +| BackendApprovalStore.pending | `responses-api/tools/BackendApprovalStore.ts` | Request-scoped | P3 | HITL approvals | + +**Design principle:** All providers must use `cacheService` consistently — no asymmetry between Kagenti (cacheService) and Llama Stack (raw Map). Caches use namespace isolation (`coreServices.cache` with provider-specific namespace prefixes). + +--- + +## Architecture Context + +**Core design principle:** Augment is the **experience layer** — the AI frontend and orchestration surface. It does not run models, serve inference, or manage GPUs. Those come from the underlying AI platform (OpenShift AI, Kagenti infrastructure, or customer-provided backends). + +**Provider capability system:** + +``` +AgenticProvider (in augment-common) +├── chat() / chatStream() — required +├── rag? — optional +├── safety? — optional +├── evaluation? — optional +└── conversation? — optional + +augmentAiProviderServiceRef (in augment-common) +└── enables cross-plugin consumption of the active provider + +ProviderManager +├── switchProvider() — start new, swap, shutdown old +├── getActiveProvider() — current provider +└── rollback() — on failure +``` + +**Modular packaging:** + +``` +boost-backend (core plugin) +├── augmentProviderExtensionPoint — provider registration interface +├── ProviderManager — lifecycle, swap, rollback +├── McpEntityProvider — MCP server catalog entities (cross-cutting) +├── VectorStoreEntityProvider — vector store catalog entities (cross-cutting) +├── composes llamastack-entity-provider — (when Llama Stack provider module installed) +├── composes kagenti-entity-provider — (when Kagenti provider module installed) +└── core routes, services, middleware + +plugin-boost-backend-module-llamastack (RHDH dynamic plugin) +├── ResponsesApiProvider — Llama Stack AI capabilities +├── normalizeLlamaStackEvent() — stream normalizer +├── composes llamastack-entity-provider — catalog entities +├── registers via augmentProviderExtensionPoint +└── registers via catalogProcessingExtensionPoint + +plugin-boost-backend-module-kagenti (RHDH dynamic plugin) +├── KagentiProvider — A2A protocol AI capabilities +├── KagentiStreamNormalizer — stream normalizer +├── composes kagenti-entity-provider — catalog entities +├── registers via augmentProviderExtensionPoint +└── registers via catalogProcessingExtensionPoint + +llamastack-entity-provider (independently deployable RHDH dynamic plugin) +├── LlamaStackModelEntityProvider — model catalog entities +├── LlamaStackAgentEntityProvider — agent catalog entities +├── Backstage backend service +└── usable standalone (without boost) OR composed into boost + +kagenti-entity-provider (independently deployable RHDH dynamic plugin) +├── KagentiAgentEntityProvider — agent catalog entities +├── KagentiToolEntityProvider — tool catalog entities +├── Backstage backend service +└── usable standalone (without boost) OR composed into boost +``` + +**Two deployment modes for entity providers:** + +1. **Standalone:** An RHDH deployment installs `llamastack-entity-provider` or `kagenti-entity-provider` as independent dynamic plugins to get AI domain objects in their catalog — without the full boost portal. Useful for teams that use Llama Stack or Kagenti directly but want catalog discoverability. +2. **Composed:** When the full `boost-backend` is installed with provider modules, the same entity provider packages are composed internally. Installing a provider module gives you both AI capabilities and catalog entities. + +**Provider abstraction enforcement:** + +- Frontend: capability-based checks (`capabilities?.agentCatalog`, `capabilities?.agentCards`) — not `providerId === 'kagenti'` string checks +- Backend: provider-specific routes confined to provider module directories — no `as KagentiProvider` casts in shared routes +- Common package: `AgenticProvider` interface and conversation types — not 559 lines of Kagenti-specific types +- All operational caches use Backstage `cacheService` consistently across providers — no asymmetric caching + +**Streaming pipeline (end-to-end):** + +``` +ChatInput → AugmentApiClient → POST /chat/stream + → chatRoutes.ts → setupSseStream → createStreamEventForwarder + → provider.chatStream() → provider normalizer + → NormalizedStreamEvent → SSE → sseStreaming.ts + → useStreamingStateBatching → StreamingMessage.reducer + → VirtualizedMessageList +``` + +See architecture diagrams: `arch-diagrams/02-backend-architecture-overview.png`, `arch-diagrams/02-backend-architecture-overview-may26.png`, `arch-diagrams/04-streaming-pipeline.png`, `arch-diagrams/04-streaming-pipeline-may26.png`, `arch-diagrams/06-backend-detail-provider-framework.png`, `arch-diagrams/06-backend-detail-provider-framework-may26.png` + +See flow diagrams: `use-case-flow-diagrams/UC-14.png`, `UC-16.png` + +--- + +## Traceability + +| Capability | Use Case | Priority | Stories | +| --------------------------------- | --------------- | -------- | ------------------------- | +| Provider Abstraction | UC-14 | P1 | 1.1.1-1.1.3, 1.2.1, 1.4.1 | +| Provider Hot-Swap | UC-16 | P0 | 1.3.1-1.3.3, 1.5.1-1.5.7 | +| Multi-Agent Orchestration | (UC-1 related) | P0 | 2.1.1-2.1.6 | +| Kagenti Provider | (UC-1 related) | P0 | 3.1.1-3.1.2 | +| Providers as RHDH Dynamic Plugins | (new) | P0 | (new) | +| cacheService Migration | (cross-cutting) | P1 | (new) | + +--- + +## Customer Context + +Derived from the Citi engagement. Key architecture principle: "Provider-agnostic. Multiple AI backends supported through a pluggable provider interface. No lock-in to any model serving platform or agent framework." + +Citi runs their own AI infrastructure and needs to switch between providers as their AI strategy evolves. The pluggable architecture ensures Augment is the stable surface while backends change underneath. diff --git a/workspaces/boost/specifications/prd/security-safety-governance.md b/workspaces/boost/specifications/prd/security-safety-governance.md new file mode 100644 index 0000000000..265fbf7db1 --- /dev/null +++ b/workspaces/boost/specifications/prd/security-safety-governance.md @@ -0,0 +1,339 @@ +# PRD: Security, Safety & Governance + +**Product:** Boost — Agentic Developer Portal for Red Hat Developer Hub +**Status:** Requirements for new implementation (informed by Augment reference prototype) +**Date:** 2026-05-19 +**Updated:** 2026-06-02 — reframed for boost; 4-stage lifecycle, 16 fine-grained permissions, RFC 8693 token exchange, SonataFlow approval integration, Backstage RBAC as sole authorization layer +**Priority:** P0 (access control, security posture, governance) / P1 (safety shields, SSRF, resilience) +**Provenance:** Requirements derived from Augment plugin analysis and three tech debt assessments (May 13, May 26, May 30 2026). See `specifications/boost-context.md` for project context. + +--- + +## Why + +Agentic AI platforms operating in enterprise environments — especially regulated financial institutions — must treat security, safety, and governance as foundational capabilities, not optional add-ons. An AI agent that can call tools, read internal documentation, and take actions on live infrastructure without proper access control, content safety, and audit trails is a liability, not a product. + +This PRD defines the enterprise trust model: multi-level access control with fine-grained Backstage RBAC, agent lifecycle governance with approval workflows, per-user identity delegation to AI providers, content safety shields, network security protections, data retention policies, and resilience patterns that ensure the platform is safe to deploy in production. + +## What This Product Does + +Boost implements a three-tier security mode system, fine-grained role-based access control via Backstage RBAC (16 permissions across agent, tool, and infrastructure resource types), agent lifecycle governance (Draft → Pending → Published → Archived) with configurable approval workflows (built-in or SonataFlow-managed), per-user identity delegation to Kagenti via RFC 8693 token exchange, content safety shields on both inputs and outputs, SSRF protection on all backend HTTP paths, optional zero data retention mode, and resilience patterns. All authorization decisions use Backstage `permissions.authorize()` from day one — no parallel authorization systems in route handlers. The security posture is configurable per environment — from zero-auth development mode to full production lockdown with OAuth token propagation to both MCP servers and AI providers. + +## Who It's For + +### Administrator + +Selects security mode, configures RBAC policies with fine-grained permissions, manages agent lifecycle governance (approving/rejecting agent promotions), sets up MCP auth chains, enables safety shields, configures data retention mode, and manages network security. + +### Security Architect + +Designs the security posture, evaluates the auth chain for tool connections, configures per-user token exchange for Kagenti, and configures SPIRE for infrastructure-level mTLS in Kagenti environments. + +### Agent Creator + +Creates agents and submits them for governance review. Subject to ownership-based permissions — can only promote, withdraw, or delete their own draft agents. + +## Boundaries + +### In Scope + +- Three security modes: `development-only-no-auth`, `plugin-only`, `full` +- Fine-grained RBAC via Backstage permissions (16 permissions, 3 resource types, conditional rules) +- Agent lifecycle governance: 4-stage model (Draft → Pending → Published → Archived) with approval workflows +- SonataFlow integration for external approval orchestration +- Per-user Kagenti identity via RFC 8693 OAuth2 Token Exchange +- Frontend SecurityGate with meaningful access-denied page +- CSRF protection via `X-Backstage-Request` header +- Content safety shields (input and output) with fail-open/fail-closed +- SSRF protection on all backend HTTP calls +- Zero Data Retention (ZDR) mode +- MCP 4-level auth chain +- Kagenti SPIRE integration for infrastructure mTLS +- Provider offline detection and error boundaries +- Self-approval prevention (agent creator ≠ agent approver) +- Ownership-based visibility and action gating + +### Out of Scope + +- HITL tool approval (see AI Chat & Interaction PRD — UC-3) +- MCP tool registration (see Agent Creation & Discovery PRD — UC-13) +- Runtime configuration mechanics (see Platform Operations PRD) +- Agent creation paths (see Agent Creation & Discovery PRD) + +### UX/UXD Integration + +Security and governance UI surfaces (access-denied pages, approval queues, review queue, lifecycle stage indicators, safety shield configuration, permission-gated admin sections) must align with RHDH usability and visual design standards: + +- **Mockups as source of truth:** Approval queue UI, review queue filtering, access-denied pages, safety shield configuration panels, and lifecycle governance controls are built from UX/UXD-provided mockups. No governance-facing UI ships without an approved design artifact. +- **PatternFly alignment:** All governance components use PatternFly design system patterns consistent with RHDH. +- **Design review gates:** Frontend PRs modifying governance or security-facing UI require UX/UXD sign-off before merge. + +--- + +## Capabilities + +### 1. Define Security Posture and Access Control (UC-20) + +**Goal:** Configure who can access Augment, who has admin privileges, and how tool connections and AI providers are authenticated. + +**Three security modes:** + +| Mode | Frontend | Backend | Provider Auth | Use Case | +| -------------------------- | --------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------- | +| `development-only-no-auth` | No gate — all users pass as guest | No RBAC, everyone is admin | Static token/TLS (if configured) | Development/demo only | +| `plugin-only` | SecurityGate wraps AugmentPage | user-cookie, augment.access, admin allow-list, real user principal | Token/TLS to Llama Stack, Keycloak OAuth2 for Kagenti | Recommended for production | +| `full` | SecurityGate wraps AugmentPage | Fine-grained RBAC (16 permissions), real user principal, mcpOAuth config | Token/TLS + MCP OAuth chain, Keycloak OAuth2 + per-user token exchange + SPIRE mTLS | Full production with identity delegation | + +**Note:** The legacy mode name `none` is deprecated; deployments should use `development-only-no-auth`. A prominent warning is logged if this mode is detected in a non-development environment. + +**Fine-grained RBAC (16 permissions across 3 resource types):** + +| Permission | Resource Type | Conditional Rules | Description | +| ------------------------- | --------------- | --------------------------------------- | --------------------------------------------------- | +| `augment.agent.list` | — | — | View agent list (visibility filtering by ownership) | +| `augment.agent.register` | — | — | Register a new agent for governance | +| `augment.agent.promote` | `augment-agent` | `IS_OWNER`, `HAS_LIFECYCLE_STAGE` | Submit draft agent for review (draft→pending) | +| `augment.agent.approve` | `augment-agent` | `IS_NOT_CREATOR`, `HAS_LIFECYCLE_STAGE` | Approve pending agent (pending→published) | +| `augment.agent.demote` | `augment-agent` | — | Reject, request-unpublish, approve-unpublish | +| `augment.agent.publish` | `augment-agent` | — | Publish an approved agent | +| `augment.agent.unpublish` | `augment-agent` | `IS_OWNER` | Request unpublishing of a published agent | +| `augment.agent.withdraw` | `augment-agent` | `IS_OWNER` | Withdraw a pending submission | +| `augment.agent.delete` | `augment-agent` | `IS_OWNER`, `HAS_LIFECYCLE_STAGE` | Delete agent (draft stage only for non-admins) | +| `augment.agent.configure` | — | — | Edit agent configuration | +| `augment.tool.promote` | `augment-tool` | `IS_OWNER` | Promote tool through lifecycle | +| `augment.tool.approve` | `augment-tool` | `IS_NOT_CREATOR` | Approve tool promotion | +| `augment.tool.demote` | `augment-tool` | — | Demote tool lifecycle stage | +| `augment.tool.publish` | `augment-tool` | — | Publish a tool | +| `augment.tool.unpublish` | `augment-tool` | — | Unpublish a tool | +| `augment.kagenti.admin` | — | — | Kagenti infrastructure operations | + +**Conditional permission rules:** + +- `IS_OWNER`: Checks `resource.createdBy === currentUser` — enables ownership-scoped actions +- `IS_NOT_CREATOR`: Checks `resource.createdBy !== currentUser` — enforces separation of duties (self-approval prevention) +- `HAS_LIFECYCLE_STAGE`: Checks `resource.lifecycleStage` against allowed stages — enforces valid lifecycle transitions + +**RBAC configuration:** + +- Fine-grained permissions are the primary authorization mechanism from day one +- `augment.access` serves as a top-level gate (if denied, all sub-permissions are denied) +- `augment.admin` is available for deployments that prefer coarse-grained admin control +- `augment.security.adminUsers` config is available for bootstrap/development only + +**MCP auth chain (4 levels):** + +1. Auth references (per-tool) +2. Per-server OAuth (client credentials) +3. ServiceAccount tokens +4. Global fallback + +**Additional controls:** + +- SSRF protection on all backend HTTP calls (ingestion and MCP paths) +- CSRF protection: `X-Backstage-Request` header required on all mutating fetch operations +- Zero Data Retention mode: inference responses not stored on server; continuity uses encrypted reasoning tokens +- Kagenti SPIRE: infrastructure-level mTLS with X.509 certificates per agent pod +- DevSpaces credentials: tokens must be stored encrypted in admin config DB (not plaintext) + +**Frontend enforcement:** + +- `SecurityGate` wraps `AugmentPage` with loading, config errors, and `RequirePermission` +- Fine-grained permission checks via `usePermissions` (batched) per admin panel section +- Unauthorized users see a meaningful access-denied page + +**Epics/Stories:** Epic 8 (Features 8.1, 8.3, 8.4), Epic 3 (Story 3.5.1) + +### 2. Agent Lifecycle Governance (UC-23, UC-24, UC-25) + +**Goal:** Govern the lifecycle of agents from creation through publication with approval workflows, ownership enforcement, and separation of duties. + +**4-stage lifecycle model:** + +``` +Draft → Pending → Published → Archived + ↑ | | + | withdraw request-unpublish + | ↓ ↓ + | Draft Pending (unpublish) + | ↓ + | approve-unpublish → Archived + | reject-unpublish → Published + └── (rejected → Draft) +``` + +**Governance registration:** Agents must be registered for governance (`POST /agents/:id/register-for-governance`) before lifecycle promotion. The `governanceRegistered` flag gates access to lifecycle actions. + +**Lifecycle actions:** + +| Action | From Stage | To Stage | Who Can Do It | +| --------------------------- | ------------------- | ------------------- | -------------------------------------------------- | +| Register for governance | — | Draft | Any authenticated user | +| Submit for review (promote) | Draft | Pending | Owner only | +| Approve | Pending | Published | Admin (not the creator — self-approval prevention) | +| Reject | Pending | Draft | Admin (not the creator) | +| Request unpublish | Published | Pending (unpublish) | Owner or admin | +| Approve unpublish | Pending (unpublish) | Archived | Admin | +| Reject unpublish | Pending (unpublish) | Published | Admin | +| Withdraw | Pending | Draft | Owner only | +| Delete | Draft | (removed) | Owner (draft only) or admin (any stage) | + +**Self-approval prevention:** When an agent is promoted from Pending → Published, the approver must not be the same user who created the agent. This is enforced as both a Backstage permission rule (`IS_NOT_CREATOR`) and a defense-in-depth route guard. + +**Ownership-based visibility:** Non-admin users see only: published agents, their own draft/pending agents, and agents with no `createdBy` (legacy/unowned). Admins see all agents. + +**SonataFlow approval workflow integration:** + +- Dual-mode: built-in lifecycle transitions OR SonataFlow-managed approval workflows +- When SonataFlow is enabled, `promote` triggers a CloudEvents POST to start an external approval workflow +- SonataFlow callbacks via `X-Augment-Workflow-Callback: true` header execute the approved/rejected transition +- Callback loop prevention guards prevent re-triggering workflows on callback-driven transitions +- Fail-closed: if workflow fails to start, agent reverts to Draft with 502 error +- SonataFlow callbacks create a separate trust boundary — callback identity should be verified + +**Cascading delete:** `DELETE /agents/:id` detects the agent's source (kagenti, orchestration, workflow) and cascades cleanup across corresponding backend stores. + +### 3. Per-User Identity Delegation — Kagenti Token Exchange (UC-20 extension) + +**Goal:** Propagate the authenticated user's identity to Kagenti so that agent operations are authorized per-user, not via a shared service-account. + +**Current state:** Augment authenticates to Kagenti using a shared service-account token (Keycloak `client_credentials` grant). All requests appear as the same service identity regardless of which user initiated them. The `X-Backstage-User` header is informational only. + +**Target state:** RFC 8693 OAuth2 Token Exchange. The user's OIDC token (injected by an auth proxy such as oauth2-proxy or Keycloak Gatekeeper) is exchanged for a Kagenti-scoped token, enabling per-user authorization at the provider level. + +**Architecture:** + +- Backend-only implementation: OIDC token read from a configurable request header (default: `X-Forwarded-Access-Token`) +- `TokenExchangeManager` service: implements RFC 8693 exchange against Keycloak, with per-user token caching, concurrent request deduplication, and streaming-compatible token lifecycle +- Graceful fallback on all failures: token exchange failure, missing header, disabled config, or Keycloak error → silently falls back to shared service-account token (no request blocking) +- Configuration: `augment.kagenti.auth.tokenExchange.enabled` (default: false), `audience`, `userTokenHeader` +- `ResponsesApiProvider` (Llama Stack) is unaffected: `setUserContext` method is optional and not implemented + +**Separation of authorization concerns:** + +- **Backstage governs:** UI visibility, agent lifecycle governance (draft/pending/published), ownership, approval workflows, admin operations +- **Kagenti governs:** agent specs, tools, runtime operations — authorized via per-user exchanged token when enabled +- **Kubernetes governs:** pod/deployment operations, namespace scoping, SPIRE mTLS + +### 4. Safety Shields and Guardrails (UC-19) + +**Goal:** Enable content safety filtering on agent inputs and outputs to prevent harmful, injected, or destructive content. + +**How it works:** + +1. Admin enables input shields (applied to user messages before sending to model): + - Prompt injection detection + - Harmful content filtering +2. Admin enables output shields (applied to agent responses before displaying): + - Harmful content filtering + - Destructive command detection +3. Per-shield behavior configuration: fail-open (log and continue) or fail-closed (block the message) +4. Custom safety patterns if needed + +**Shield violation handling:** + +- Violation is logged for review +- Fail-closed: user sees a safety message instead of blocked content +- Fail-open: content passes through but violation is logged + +**Backend implementation:** `SafetyService` delegates to the AI platform's Safety API (Llama Stack). + +**Admin UI:** `SafetyShieldsSection` and `SafetyPatternsSection` in `SafetyEvalPanel`. + +**Epics/Stories:** Epic 8 (Feature 8.2) + +### 5. Resilience Patterns (Epic 8, Feature 8.5) + +**Goal:** Graceful degradation when things go wrong. + +**Provider offline:** + +- `ProviderOfflineBanner` displayed when `useStatus` detects provider is down +- Chat resumes when provider recovers + +**Error handling:** + +- `AugmentErrorBoundary` prevents page crashes +- `ErrorCard` displayed inline on per-message errors +- Snackbar toasts via `useToast` for transient notifications + +**Epics/Stories:** Epic 8 (Feature 8.5) + +--- + +## Architecture Context + +**Security model layers (7 enforcement layers across 3 modes):** + +``` +Frontend Layer +├── SecurityGate.tsx — wraps AugmentPage, checks RequirePermission +├── usePermissions (batched) — fine-grained per admin panel section +└── CSRF — X-Backstage-Request header on all mutating fetches + +Backend Middleware (5 layers) +├── Backstage HTTP — user-cookie / unauthenticated +├── requirePluginAccess — augment.access / skipped +├── authorizeLifecycleAction — fine-grained permission check via permissions.authorize() +├── User identity — real user principal (OIDC) / user-default/guest +└── MCP OAuth — mcpOAuth config / N/A / N/A + +Agent Lifecycle Governance +├── Ownership enforcement — createdBy field, IS_OWNER permission rule +├── Self-approval prevention — IS_NOT_CREATOR rule + defense-in-depth route guard +├── Lifecycle stage gating — HAS_LIFECYCLE_STAGE rule +└── SonataFlow integration — CloudEvents trigger, callback trust boundary + +Provider Authentication +├── Llama Stack — static token/TLS → Token/TLS → Token/TLS + MCP OAuth chain +└── Kagenti — no auth → client_credentials → per-user token exchange (RFC 8693) + SPIRE mTLS + +Cross-Cutting Protections (all modes) +├── SsrfGuard — blocks SSRF on all HTTP paths +├── Zero Data Retention — encrypted reasoning tokens for continuity +└── Content Safety Shields — fail-open/fail-closed per shield +``` + +**Key implementation files:** + +- `middleware/security.ts`: security mode enforcement, `requirePluginAccess`, `authorizeLifecycleAction` +- `permissions.ts`: 16 fine-grained permissions, 2 resource types, 3 conditional rules +- `TokenExchangeManager`: RFC 8693 per-user token exchange for Kagenti +- `AgentApprovalWorkflowService`: SonataFlow integration +- `services/SafetyService`: safety shield delegation +- `services/McpAuthService`: 4-level auth chain +- `services/SsrfGuard`: DNS re-check SSRF protection +- Frontend `SecurityGate.tsx`: permission gating + +See architecture diagrams: `arch-diagrams/10-security-model.png`, `arch-diagrams/10-security-model-may26.png` + +See flow diagrams: `use-case-flow-diagrams/UC-19.png`, `UC-20.png`, `UC-23-may26.png`, `UC-24-may26.png`, `UC-25-may26.png` + +--- + +## Traceability + +| Capability | Use Case | Priority | Stories | +| --------------------------------- | ------------------- | -------- | -------------------------------- | +| Security Posture & Access Control | UC-20 | P0 | 8.1.1-8.1.3, 8.3.1, 8.4.1, 3.5.1 | +| Agent Lifecycle Governance | UC-23, UC-24, UC-25 | P0 | (new) | +| Per-User Token Exchange | UC-20 (extension) | P1 | (new) | +| Fine-Grained Permissions | UC-20 (extension) | P0 | (new) | +| Safety Shields | UC-19 | P1 | 8.2.1-8.2.2 | +| Resilience | (cross-cutting) | P1 | 8.5.1-8.5.2 | + +--- + +## Customer Context + +Derived from the Citi engagement. Architecture principle: "Enterprise-first trust model. Human-in-the-loop approval, RBAC, audit trails, safety shields, and zero data retention are foundational, not optional." + +Citi's regulatory and compliance requirements for AI tooling include audit trails, access controls, data residency, and separation of duties. The security model is designed to meet these requirements while supporting progressive enforcement from development through production. + +The fine-grained permission model and agent lifecycle governance address specific Citi requirements: no single individual should be able to both create and publish an agent to production users (separation of duties), and all governance decisions should be visible to Backstage RBAC policy configuration (no shadow authorization systems). + +Success outcomes addressed: + +- Enterprise security, safety, and compliance are built in (UC-19, UC-20) +- Sensitive operations stay under human control (UC-3, addressed in AI Chat PRD) +- Agent lifecycle governed with approval workflows and separation of duties (UC-23, UC-24, UC-25) +- Per-user identity delegated to AI providers for audit trail (UC-20 extension) diff --git a/workspaces/boost/specifications/prd/use-case-index.md b/workspaces/boost/specifications/prd/use-case-index.md new file mode 100644 index 0000000000..6cd360748f --- /dev/null +++ b/workspaces/boost/specifications/prd/use-case-index.md @@ -0,0 +1,75 @@ +# Use Case Index + +**Product:** Boost — Agentic Developer Portal for Red Hat Developer Hub +**Updated:** 2026-06-02 + +Concise reference for all use cases across the five PRDs. For detailed descriptions, see the owning PRD. + +--- + +## AI Chat & Interaction Experience + +| UC | Title | Priority | Description | +| ---- | -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | +| UC-1 | Streaming Chat | P0 | Ask a question, receive a streamed answer from a specialist AI agent with real-time phase indicators and rich rendering | +| UC-2 | Knowledge-Grounded Answers (RAG) | P0 | Ask about internal docs/runbooks, receive an answer grounded in the org's knowledge base with source citations | +| UC-3 | Human-in-the-Loop Approval | P0 | Review a proposed agent action (tool call) before execution — edit parameters, approve, or reject | +| UC-5 | Conversation History | P0 | Return to past conversations, search, provide feedback, edit/regenerate, export | +| UC-6 | Debug & Inspect Execution | P2 | Execution trace panel, message inspector, session state inspector for agent transparency | + +## Agent Creation & Discovery + +| UC | Title | Priority | Description | +| ----- | ---------------------------- | -------- | --------------------------------------------------------------------------------------------- | +| UC-4 | Browse and Select an Agent | P1 | Discover agents in the gallery, evaluate capabilities, select one to start a conversation | +| UC-7 | Create an Agent (umbrella) | P0 | Four creation paths converge on unified ChatAgent model: no-code, template, DevSpaces, import | +| UC-8 | No-Code Agent Builder | P0 | Create an agent visually — purpose, tools, knowledge base, handoffs — without writing code | +| UC-9 | Discover Agents in Gallery | P1 | Browse curated collection of pre-built agents with rich metadata and preview panels | +| UC-10 | Agent from Software Template | P1 | Bootstrap agent project via Backstage scaffolder with boilerplate, CI/CD, and registration | +| UC-11 | Agent from DevSpaces | P1 | Write agent code in cloud IDE, build container, deploy to Kagenti | +| UC-12 | Import Existing Agent | P0 | Bring an already-built agent (container image or source repo) into Boost | +| UC-13 | Configure MCP Tools | P1 | Register MCP servers, configure auth (4-level chain), set tool approval policies | + +## Pluggable AI Platform Architecture + +| UC | Title | Priority | Description | +| ----- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | +| UC-14 | Integrate a New AI Provider | P1 | Implement AgenticProvider interface, create backend module, register via extension point — zero source changes | +| UC-16 | Switch AI Provider at Runtime | P0 | Hot-swap between providers with rollback on failure; frontend auto-adapts via capability gating | + +## Platform Operations & Deployment + +| UC | Title | Priority | Description | +| ----- | -------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | +| UC-15 | Deploy Boost | P0 | Install and configure in RHDH (dynamic plugins) or vanilla Backstage (static plugins) | +| UC-17 | Manage Platform Agents & Orchestration | P0 | Create, edit, delete agents and orchestration rules from the admin panel | +| UC-18 | Configure RAG Knowledge Pipelines | P0 | Ingest docs into vector stores — GitHub, URL, file upload — with change detection and per-agent scoping | +| UC-21 | Manage Runtime Configuration | P0 | Change model, prompts, tools, caps at runtime via admin panel — 25+ keys, immediate effect | +| UC-22 | White-Label the Portal | P1 | Customize name, logo, colors, prompt groups, featured agents — all at runtime | + +## Security, Safety & Governance + +| UC | Title | Priority | Description | +| ----- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- | +| UC-19 | Safety Shields and Guardrails | P1 | Content safety filtering on inputs/outputs — prompt injection, harmful content, destructive commands | +| UC-20 | Security Posture and Access Control | P0 | Three security modes, 16 fine-grained RBAC permissions, MCP auth chain, SSRF protection, ZDR mode | +| UC-23 | Agent Lifecycle Governance | P0 | 4-stage lifecycle (Draft→Pending→Published→Archived) with ownership, approval workflows | +| UC-24 | Approval Workflow (SonataFlow) | P0 | Dual-mode approval — built-in transitions or SonataFlow-managed with CloudEvents | +| UC-25 | Self-Approval Prevention | P0 | Separation of duties — agent creator cannot approve their own agent for publication | + +--- + +## Summary + +| PRD | Use Cases | P0 Count | +| ---------------------------------- | -------------------------------------------------- | --------- | +| AI Chat & Interaction Experience | UC-1, UC-2, UC-3, UC-5, UC-6 | 4 | +| Agent Creation & Discovery | UC-4, UC-7, UC-8, UC-9, UC-10, UC-11, UC-12, UC-13 | 3 | +| Pluggable AI Platform Architecture | UC-14, UC-16 | 1 | +| Platform Operations & Deployment | UC-15, UC-17, UC-18, UC-21, UC-22 | 4 | +| Security, Safety & Governance | UC-19, UC-20, UC-23, UC-24, UC-25 | 4 | +| **Total** | **25 use cases** | **16 P0** | + +## Diagram Reference + +All use case flow diagrams are in `use-case-flow-diagrams/`. Updated May 26 versions (suffix `-may26`) exist for: UC-4, UC-7, UC-9, UC-17, UC-20. Use cases UC-23, UC-24, UC-25 were added May 26. From 7452b507bac54361e5609abc1a9be6e87af4267e Mon Sep 17 00:00:00 2001 From: gabemontero Date: Wed, 3 Jun 2026 12:45:12 -0400 Subject: [PATCH 2/8] durandom-rm-png-refs Signed-off-by: gabemontero --- .../boost/specifications/prd/agent-creation-discovery.md | 4 ---- .../specifications/prd/ai-chat-interaction-experience.md | 4 ---- .../specifications/prd/platform-operations-deployment.md | 4 ---- .../specifications/prd/pluggable-ai-platform-architecture.md | 4 ---- .../boost/specifications/prd/security-safety-governance.md | 4 ---- 5 files changed, 20 deletions(-) diff --git a/workspaces/boost/specifications/prd/agent-creation-discovery.md b/workspaces/boost/specifications/prd/agent-creation-discovery.md index 6aae3801c6..eb646c0dbf 100644 --- a/workspaces/boost/specifications/prd/agent-creation-discovery.md +++ b/workspaces/boost/specifications/prd/agent-creation-discovery.md @@ -304,10 +304,6 @@ Home Dashboard, Agents, Tools, Build Pipelines, Sandbox, Platform Links, Dashboa - Backend execution mode (`BackendToolExecutor`) for air-gapped environments - Tool scoping: per-agent allowed tool subsets via configuration -See architecture diagrams: `arch-diagrams/06-backend-detail-provider-framework.png`, `arch-diagrams/06-backend-detail-provider-framework-may26.png`, `arch-diagrams/08-backend-detail-kagenti.png`, `arch-diagrams/08-backend-detail-kagenti-may26.png` - -See flow diagrams: `use-case-flow-diagrams/UC-4.png`, `UC-4-may26.png`, `UC-7.png`, `UC-7-may26.png` through `UC-13.png`, `UC-23-may26.png`, `UC-24-may26.png`, `UC-25-may26.png` - --- ## Traceability diff --git a/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md b/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md index 79a69c44e9..159f59774e 100644 --- a/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md +++ b/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md @@ -213,10 +213,6 @@ Boost builds composable from the start, avoiding augment's monolithic frontend p - `NormalizedStreamEvent` union type covering all stream event categories - Permission contracts: `augmentAccessPermission`, `augmentAdminPermission` -See architecture diagrams: `arch-diagrams/00-frontend-architecture.png`, `arch-diagrams/00-frontend-architecture-may26.png`, `arch-diagrams/04-streaming-pipeline.png`, `arch-diagrams/04-streaming-pipeline-may26.png` - -See flow diagrams: `use-case-flow-diagrams/UC-1.png` through `UC-6.png`, `UC-9-may26.png` - --- ## Traceability diff --git a/workspaces/boost/specifications/prd/platform-operations-deployment.md b/workspaces/boost/specifications/prd/platform-operations-deployment.md index dcc94133b4..f5417270a0 100644 --- a/workspaces/boost/specifications/prd/platform-operations-deployment.md +++ b/workspaces/boost/specifications/prd/platform-operations-deployment.md @@ -273,10 +273,6 @@ Sources (GitHub, URL, File Upload) → Agent RAG queries at chat time ``` -See architecture diagrams: `arch-diagrams/02-backend-architecture-overview.png`, `arch-diagrams/02-backend-architecture-overview-may26.png`, `arch-diagrams/05-backend-detail-routes.png`, `arch-diagrams/05-backend-detail-routes-may26.png`, `arch-diagrams/09-backend-detail-services.png`, `arch-diagrams/09-backend-detail-services-may26.png` - -See flow diagrams: `use-case-flow-diagrams/UC-15.png` through `UC-22.png`, `UC-17-may26.png`, `UC-20-may26.png` - --- ## Traceability diff --git a/workspaces/boost/specifications/prd/pluggable-ai-platform-architecture.md b/workspaces/boost/specifications/prd/pluggable-ai-platform-architecture.md index 6cbe3c7ed1..3f347a11c3 100644 --- a/workspaces/boost/specifications/prd/pluggable-ai-platform-architecture.md +++ b/workspaces/boost/specifications/prd/pluggable-ai-platform-architecture.md @@ -316,10 +316,6 @@ ChatInput → AugmentApiClient → POST /chat/stream → VirtualizedMessageList ``` -See architecture diagrams: `arch-diagrams/02-backend-architecture-overview.png`, `arch-diagrams/02-backend-architecture-overview-may26.png`, `arch-diagrams/04-streaming-pipeline.png`, `arch-diagrams/04-streaming-pipeline-may26.png`, `arch-diagrams/06-backend-detail-provider-framework.png`, `arch-diagrams/06-backend-detail-provider-framework-may26.png` - -See flow diagrams: `use-case-flow-diagrams/UC-14.png`, `UC-16.png` - --- ## Traceability diff --git a/workspaces/boost/specifications/prd/security-safety-governance.md b/workspaces/boost/specifications/prd/security-safety-governance.md index 265fbf7db1..dfd704818a 100644 --- a/workspaces/boost/specifications/prd/security-safety-governance.md +++ b/workspaces/boost/specifications/prd/security-safety-governance.md @@ -304,10 +304,6 @@ Cross-Cutting Protections (all modes) - `services/SsrfGuard`: DNS re-check SSRF protection - Frontend `SecurityGate.tsx`: permission gating -See architecture diagrams: `arch-diagrams/10-security-model.png`, `arch-diagrams/10-security-model-may26.png` - -See flow diagrams: `use-case-flow-diagrams/UC-19.png`, `UC-20.png`, `UC-23-may26.png`, `UC-24-may26.png`, `UC-25-may26.png` - --- ## Traceability From 2d9059f20aa9ce7612ee1ad48efe1129c1c5511f Mon Sep 17 00:00:00 2001 From: gabemontero Date: Wed, 3 Jun 2026 12:49:12 -0400 Subject: [PATCH 3/8] durandom-rm-augment-forward-looking-scenarios Signed-off-by: gabemontero --- .../specs/frontend-composability/spec.md | 2 +- .../specs/fine-grained-permissions/spec.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md index 58a8412d33..bd9278ba4a 100644 --- a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md @@ -67,7 +67,7 @@ Deployers control feature visibility via `app-config.yaml`. #### Scenario: Backstage feature flags registration -- **WHEN** the augment plugin is loaded +- **WHEN** the boost plugin is loaded - **THEN** it registers feature flags with Backstage's `featureFlagsApiRef` - **AND** flags can be toggled in the Backstage settings UI without code changes or restarts diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md index fa14fffb6c..9f44ec2707 100644 --- a/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md @@ -10,7 +10,7 @@ RBAC policies govern agent lifecycle transitions with ownership and separation-o #### Scenario: Agent permission definitions -- **WHEN** the augment plugin registers permissions via `permissionsRegistry.addPermissions()` +- **WHEN** the boost plugin registers permissions via `permissionsRegistry.addPermissions()` - **THEN** the following agent permissions are registered: | Permission | Resource Type | Conditional Rules | Gates | |---|---|---|---| @@ -45,7 +45,7 @@ RBAC policies govern tool lifecycle transitions. #### Scenario: Tool permission definitions -- **WHEN** the augment plugin registers permissions +- **WHEN** the boost plugin registers permissions - **THEN** the following tool permissions are registered: | Permission | Resource Type | Conditional Rules | Gates | |---|---|---|---| @@ -123,7 +123,7 @@ A shared middleware replaces scattered route-level guards. #### Scenario: Functional permission definitions -- **WHEN** the augment plugin registers permissions +- **WHEN** the boost plugin registers permissions - **THEN** the following functional permissions are also registered: | Permission | Action | Gates | |---|---|---| From 3d28710a80f8ffc7011f885f24ab61d3c0404946 Mon Sep 17 00:00:00 2001 From: gabemontero Date: Wed, 3 Jun 2026 12:53:56 -0400 Subject: [PATCH 4/8] durandom-clarify-uc-4 Signed-off-by: gabemontero --- .../boost/specifications/prd/ai-chat-interaction-experience.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md b/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md index 159f59774e..5a0361c558 100644 --- a/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md +++ b/workspaces/boost/specifications/prd/ai-chat-interaction-experience.md @@ -128,6 +128,8 @@ All frontend components and UI flows must align with RHDH usability and visual d **Epics/Stories:** Epic 5 (Features 5.1, 5.2) +> **Note:** UC-4 (Agent Gallery & Discovery) is defined in the [Agent Creation & Discovery PRD](agent-creation-discovery.md). + ### 4. Conversation History (UC-5) **Goal:** Return to past conversations, search history, provide feedback, and export sessions. From 9e1e5e816ded6d441901270177eb32878b048e91 Mon Sep 17 00:00:00 2001 From: gabemontero Date: Wed, 3 Jun 2026 12:56:17 -0400 Subject: [PATCH 5/8] durandom-spec-draft-status Signed-off-by: gabemontero --- .../openspec/changes/agent-creation-discovery/.openspec.yaml | 1 + .../agent-creation-discovery/specs/agent-creation-paths/spec.md | 2 ++ .../agent-creation-discovery/specs/agent-gallery/spec.md | 2 ++ .../agent-creation-discovery/specs/catalog-entities/spec.md | 2 ++ .../changes/agent-creation-discovery/specs/mcp-tools/spec.md | 2 ++ .../changes/ai-chat-interaction-experience/.openspec.yaml | 1 + .../specs/conversation-history/spec.md | 2 ++ .../specs/frontend-composability/spec.md | 2 ++ .../ai-chat-interaction-experience/specs/hitl-approval/spec.md | 2 ++ .../ai-chat-interaction-experience/specs/rag-knowledge/spec.md | 2 ++ .../ai-chat-interaction-experience/specs/streaming-chat/spec.md | 2 ++ .../changes/platform-operations-deployment/.openspec.yaml | 1 + .../specs/cache-migration/spec.md | 2 ++ .../platform-operations-deployment/specs/deployment/spec.md | 2 ++ .../platform-operations-deployment/specs/rag-pipelines/spec.md | 2 ++ .../platform-operations-deployment/specs/runtime-config/spec.md | 2 ++ .../platform-operations-deployment/specs/white-label/spec.md | 2 ++ .../changes/pluggable-ai-platform-architecture/.openspec.yaml | 1 + .../specs/multi-agent-orchestration/spec.md | 2 ++ .../specs/normalized-streaming/spec.md | 2 ++ .../specs/provider-abstraction/spec.md | 2 ++ .../specs/provider-hot-swap/spec.md | 2 ++ .../specs/provider-packaging/spec.md | 2 ++ .../openspec/changes/security-safety-governance/.openspec.yaml | 1 + .../security-safety-governance/specs/access-control/spec.md | 2 ++ .../specs/fine-grained-permissions/spec.md | 2 ++ .../changes/security-safety-governance/specs/resilience/spec.md | 2 ++ .../security-safety-governance/specs/safety-shields/spec.md | 2 ++ 28 files changed, 51 insertions(+) diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml b/workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml index 28882f7998..439f3c3852 100644 --- a/workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml @@ -1,2 +1,3 @@ schema: spec-driven created: 2026-05-19 +status: draft diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md index 2c986b11a2..517ec09958 100644 --- a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md @@ -1,5 +1,7 @@ # Agent Creation Paths +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Four creation methods converge on a unified `ChatAgent` model. All paths produce agents visible in the gallery and available in chat. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md index c0da65b0f8..08da947d3c 100644 --- a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md @@ -1,5 +1,7 @@ # Agent Gallery and Discovery +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Browse, search, filter, and select agents from a curated gallery. The gallery merges agents from all providers into a unified view. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md index aa13d3c915..3ed5670fad 100644 --- a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md @@ -1,5 +1,7 @@ # Catalog Entities for AI Domain Objects +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + AI agents, models, MCP servers, and vector stores are modeled as Backstage catalog entities. This replaces in-memory caches with catalog-managed lifecycle, providing discoverability, ownership, search, and RBAC integration. NOTE: These recommendations align with in-flight upstream Backstage initiatives: diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/mcp-tools/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/mcp-tools/spec.md index f16c4a9252..f729a3189d 100644 --- a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/mcp-tools/spec.md +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/mcp-tools/spec.md @@ -1,5 +1,7 @@ # MCP Tool Configuration +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Connect agents to live systems by registering MCP servers, configuring authentication, and setting tool approval policies. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/.openspec.yaml b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/.openspec.yaml index 28882f7998..439f3c3852 100644 --- a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/.openspec.yaml +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/.openspec.yaml @@ -1,2 +1,3 @@ schema: spec-driven created: 2026-05-19 +status: draft diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/conversation-history/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/conversation-history/spec.md index 85dfd3a55e..2f8f4087e5 100644 --- a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/conversation-history/spec.md +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/conversation-history/spec.md @@ -1,5 +1,7 @@ # Conversation History +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Persistent, searchable conversation history with feedback, export, and developer inspection tools. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md index bd9278ba4a..7c88336d36 100644 --- a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/frontend-composability/spec.md @@ -1,5 +1,7 @@ # Frontend Composability +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + The frontend must be decomposed from a monolithic `AugmentPage` into composable extensions with lazy loading, feature flags, and capability-driven rendering. ## ADDED Requirements diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/hitl-approval/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/hitl-approval/spec.md index e4d472ce69..5a6248da2c 100644 --- a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/hitl-approval/spec.md +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/hitl-approval/spec.md @@ -1,5 +1,7 @@ # Human-in-the-Loop Approval +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Review proposed agent actions (tool calls) before execution, with the ability to edit parameters, approve, or reject. No destructive action executes without explicit developer consent. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/rag-knowledge/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/rag-knowledge/spec.md index 08c53b852c..454f9d711f 100644 --- a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/rag-knowledge/spec.md +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/rag-knowledge/spec.md @@ -1,5 +1,7 @@ # Knowledge-Grounded Answers (RAG) +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Answers grounded in the organization's own documentation, with source citations enabling developers to trace every claim to a source. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/streaming-chat/spec.md b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/streaming-chat/spec.md index abec003fc2..eb5aa9856e 100644 --- a/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/streaming-chat/spec.md +++ b/workspaces/boost/openspec/changes/ai-chat-interaction-experience/specs/streaming-chat/spec.md @@ -1,5 +1,7 @@ # Streaming Chat +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Real-time streamed conversation with specialist AI agents, including phase indicators, rich rendering, and provider-adaptive behavior. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/.openspec.yaml b/workspaces/boost/openspec/changes/platform-operations-deployment/.openspec.yaml index 28882f7998..439f3c3852 100644 --- a/workspaces/boost/openspec/changes/platform-operations-deployment/.openspec.yaml +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/.openspec.yaml @@ -1,2 +1,3 @@ schema: spec-driven created: 2026-05-19 +status: draft diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md index 2a28d081a6..125f3d39cb 100644 --- a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md @@ -1,5 +1,7 @@ # Operational Caching via Backstage cacheService +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + All operational caches use Backstage `cacheService` from day one — no raw `Map<>` caches. This provides Redis-backed caching in production, consistent TTL semantics, and multi-instance safety. The cache inventory below is derived from augment's 17-cache analysis to ensure boost covers all the same operational caching needs with proper architecture. NOTE: Provider-specific caches (#2-#7) are covered in the platform-architecture change. Catalog entity candidate caches are covered in the agent-creation-discovery change. This spec covers the remaining operational caches (#1, #8-#14) plus 3 new caches identified in the May 26 analysis (#15-#17). diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/deployment/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/deployment/spec.md index ea3a60c3de..20db10f769 100644 --- a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/deployment/spec.md +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/deployment/spec.md @@ -1,5 +1,7 @@ # Plugin Deployment +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Install and configure Augment in an RHDH or vanilla Backstage instance via two deployment paths. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/rag-pipelines/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/rag-pipelines/spec.md index d8c9ca75f0..3b52679946 100644 --- a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/rag-pipelines/spec.md +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/rag-pipelines/spec.md @@ -1,5 +1,7 @@ # RAG Knowledge Pipelines +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Ingest customer documentation into vector stores so agents can ground their answers in real data. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md index 385c80d8c7..f01fa7ef93 100644 --- a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md @@ -1,5 +1,7 @@ # Runtime Configuration Engine +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Change Augment's behavior at runtime — model, system prompt, tools, caps, and more — without restarting. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/white-label/spec.md b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/white-label/spec.md index 78ec5a3bb4..98b5e6771a 100644 --- a/workspaces/boost/openspec/changes/platform-operations-deployment/specs/white-label/spec.md +++ b/workspaces/boost/openspec/changes/platform-operations-deployment/specs/white-label/spec.md @@ -1,5 +1,7 @@ # White-Label Branding +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Customize the Augment experience to match the organization's brand — all at runtime, no deployment required. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/.openspec.yaml b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/.openspec.yaml index 28882f7998..439f3c3852 100644 --- a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/.openspec.yaml +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/.openspec.yaml @@ -1,2 +1,3 @@ schema: spec-driven created: 2026-05-19 +status: draft diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/multi-agent-orchestration/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/multi-agent-orchestration/spec.md index c6d829b27c..cc9e5f0424 100644 --- a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/multi-agent-orchestration/spec.md +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/multi-agent-orchestration/spec.md @@ -1,5 +1,7 @@ # Multi-Agent Orchestration +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Config-driven multi-agent orchestration without writing code. Llama Stack agents are defined in YAML and assembled into handoff chains. Kagenti agents are framework-neutral K8s workloads discovered via A2A protocol. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/normalized-streaming/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/normalized-streaming/spec.md index d602254682..860eebdf41 100644 --- a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/normalized-streaming/spec.md +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/normalized-streaming/spec.md @@ -1,5 +1,7 @@ # Normalized Streaming Protocol +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + One event contract between all backend providers and the frontend. Each provider maps its native events to `NormalizedStreamEvent` so the frontend works identically regardless of active backend. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-abstraction/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-abstraction/spec.md index a53167af58..2cd161152f 100644 --- a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-abstraction/spec.md +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-abstraction/spec.md @@ -1,5 +1,7 @@ # Provider Abstraction +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Augment abstracts AI platform backends behind a pluggable provider interface, enabling any AI platform to be integrated without forking the plugin. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-hot-swap/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-hot-swap/spec.md index 1391807d88..d6a185e3e7 100644 --- a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-hot-swap/spec.md +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-hot-swap/spec.md @@ -1,5 +1,7 @@ # Provider Hot-Swap +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Switch AI platform providers at runtime without downtime or data loss. The system starts the new provider, validates it, swaps the active pointer, and shuts down the old — with automatic rollback on failure. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md index 43ae19fab4..611285630c 100644 --- a/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md +++ b/workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md @@ -1,5 +1,7 @@ # Provider Packaging as Backstage Modules +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Each AI platform provider must be packaged as an independent Backstage backend module, following RHDH dynamic plugin conventions. This enables deployers to install only the providers they need and allows providers to evolve independently. ## ADDED Requirements diff --git a/workspaces/boost/openspec/changes/security-safety-governance/.openspec.yaml b/workspaces/boost/openspec/changes/security-safety-governance/.openspec.yaml index 28882f7998..439f3c3852 100644 --- a/workspaces/boost/openspec/changes/security-safety-governance/.openspec.yaml +++ b/workspaces/boost/openspec/changes/security-safety-governance/.openspec.yaml @@ -1,2 +1,3 @@ schema: spec-driven created: 2026-05-19 +status: draft diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md index 8a4c8102e9..9d43323e90 100644 --- a/workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md @@ -1,5 +1,7 @@ # Access Control and Security Posture +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Multi-level security configuration controlling who accesses Augment, who has admin privileges, and how tool connections are authenticated. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md index 9f44ec2707..5295d016e0 100644 --- a/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/fine-grained-permissions/spec.md @@ -1,5 +1,7 @@ # Fine-Grained Permissions +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Expand from 2 coarse permissions to 16 fine-grained permissions across 3 resource types with conditional rules, replacing custom route-level governance with proper Backstage RBAC. This eliminates the parallel authorization system (2,132 lines of custom governance code vs. 73 lines of Backstage permissions) by migrating all 12+ authorization decisions into `permissions.authorize()`. ## ADDED Requirements diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/resilience/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/resilience/spec.md index 9ecaf20cd3..0f982a9862 100644 --- a/workspaces/boost/openspec/changes/security-safety-governance/specs/resilience/spec.md +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/resilience/spec.md @@ -1,5 +1,7 @@ # Resilience Patterns +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Graceful degradation when things go wrong — provider offline detection, error boundaries, and transient notifications. ## EXISTING Requirements diff --git a/workspaces/boost/openspec/changes/security-safety-governance/specs/safety-shields/spec.md b/workspaces/boost/openspec/changes/security-safety-governance/specs/safety-shields/spec.md index eb344c34cc..aaf5b6876c 100644 --- a/workspaces/boost/openspec/changes/security-safety-governance/specs/safety-shields/spec.md +++ b/workspaces/boost/openspec/changes/security-safety-governance/specs/safety-shields/spec.md @@ -1,5 +1,7 @@ # Safety Shields and Guardrails +> **Status: Draft** — Pre-implementation specification. Subject to change during implementation. + Content safety filtering on agent inputs and outputs to prevent harmful, injected, or destructive content. ## EXISTING Requirements From b63d58dd26eeb6fb60f96b9d4bd82e7a5fb533b5 Mon Sep 17 00:00:00 2001 From: gabemontero Date: Wed, 3 Jun 2026 12:59:50 -0400 Subject: [PATCH 6/8] fullsend-fix-filesystem-path Signed-off-by: gabemontero --- .../boost/openspec/changes/agent-creation-discovery/design.md | 2 +- .../agent-creation-discovery/specs/catalog-entities/spec.md | 2 +- .../boost/openspec/changes/agent-creation-discovery/tasks.md | 4 ++-- workspaces/boost/specifications/boost-context.md | 2 +- .../boost/specifications/prd/agent-creation-discovery.md | 2 +- .../specifications/prd/platform-operations-deployment.md | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/design.md b/workspaces/boost/openspec/changes/agent-creation-discovery/design.md index 9c855b6e67..43574b865c 100644 --- a/workspaces/boost/openspec/changes/agent-creation-discovery/design.md +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/design.md @@ -41,7 +41,7 @@ Entity providers are separate packages registered as Backstage backend services, **Composed mode:** Boost provider modules compose these same packages internally — one install gives you AI capabilities + catalog entities. -Packages live at `rhdh-plugins/workspace/boost/plugins/llamastack-entity-provider` and `kagenti-entity-provider`. +Packages live at `rhdh-plugins/workspaces/boost/plugins/llamastack-entity-provider` and `kagenti-entity-provider`. ### Decision 3: Gradual cache elimination diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md index 3ed5670fad..2a8bae6056 100644 --- a/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md @@ -24,7 +24,7 @@ Entity providers are **independently deployable Backstage backend services**, ea **Two deployment modes:** -1. **Standalone:** Install `llamastack-entity-provider` or `kagenti-entity-provider` as independent RHDH dynamic plugins — gets AI domain objects in the catalog without the rest of boost. Packages live at `rhdh-plugins/workspace/boost/plugins/`. +1. **Standalone:** Install `llamastack-entity-provider` or `kagenti-entity-provider` as independent RHDH dynamic plugins — gets AI domain objects in the catalog without the rest of boost. Packages live at `rhdh-plugins/workspaces/boost/plugins/`. 2. **Composed:** When `boost-backend` is installed with provider modules, the same entity provider packages are composed internally — installing a provider module gives you both AI capabilities and catalog entities. Cross-cutting entities (MCP servers, vector stores) that aren't provider-specific live in the core plugin. diff --git a/workspaces/boost/openspec/changes/agent-creation-discovery/tasks.md b/workspaces/boost/openspec/changes/agent-creation-discovery/tasks.md index 7a085c77ae..9a4f95642e 100644 --- a/workspaces/boost/openspec/changes/agent-creation-discovery/tasks.md +++ b/workspaces/boost/openspec/changes/agent-creation-discovery/tasks.md @@ -4,7 +4,7 @@ ### 1a. kagenti-entity-provider package -- [ ] 1a.1 Create `kagenti-entity-provider` package at `rhdh-plugins/workspace/boost/plugins/kagenti-entity-provider` +- [ ] 1a.1 Create `kagenti-entity-provider` package at `rhdh-plugins/workspaces/boost/plugins/kagenti-entity-provider` - [ ] 1a.2 Register as Backstage backend service per backend system architecture - [ ] 1a.3 Implement `KagentiAgentEntityProvider` polling Kagenti API for agents (kind: Component, spec.type: ai-agent) - [ ] 1a.4 Implement `KagentiToolEntityProvider` reading tool configs from Kagenti (kind: Resource, spec.type: ai-tool) @@ -13,7 +13,7 @@ ### 1b. llamastack-entity-provider package -- [ ] 1b.1 Create `llamastack-entity-provider` package at `rhdh-plugins/workspace/boost/plugins/llamastack-entity-provider` +- [ ] 1b.1 Create `llamastack-entity-provider` package at `rhdh-plugins/workspaces/boost/plugins/llamastack-entity-provider` - [ ] 1b.2 Register as Backstage backend service per backend system architecture - [ ] 1b.3 Implement `LlamaStackModelEntityProvider` polling `/v1/models` (kind: Resource, spec.type: ai-model) - [ ] 1b.4 Implement `LlamaStackAgentEntityProvider` reading configured agents from YAML/admin config (kind: Component, spec.type: ai-agent) diff --git a/workspaces/boost/specifications/boost-context.md b/workspaces/boost/specifications/boost-context.md index 03d23bc90f..7b3d421c59 100644 --- a/workspaces/boost/specifications/boost-context.md +++ b/workspaces/boost/specifications/boost-context.md @@ -27,7 +27,7 @@ The Augment plugin (in `redhat-developer/rhdh-plugins`, workspace `augment`) is ## Workspace Structure -All packages live at `rhdh-plugins/workspace/boost/plugins/`: +All packages live at `rhdh-plugins/workspaces/boost/plugins/`: ``` workspace/boost/plugins/ diff --git a/workspaces/boost/specifications/prd/agent-creation-discovery.md b/workspaces/boost/specifications/prd/agent-creation-discovery.md index eb646c0dbf..4f35694b47 100644 --- a/workspaces/boost/specifications/prd/agent-creation-discovery.md +++ b/workspaces/boost/specifications/prd/agent-creation-discovery.md @@ -249,7 +249,7 @@ All methods produce an agent visible in the gallery and available in chat. - `llamastack-entity-provider` — emits Llama Stack models and agents as catalog entities. Loadable standalone (without the rest of boost) for RHDH deployments that use Llama Stack but don't need the full agentic portal. - `kagenti-entity-provider` — emits Kagenti agents and tools as catalog entities. Loadable standalone for RHDH deployments that use Kagenti but don't need the full portal. -These packages live at `rhdh-plugins/workspace/boost/plugins/` and are registered as Backstage backend services per the [Backstage backend system architecture](https://backstage.io/docs/backend-system/architecture/services/). When the full `boost-backend` plugin is installed, it composes these same entity provider packages internally alongside the agentic provider modules. Cross-cutting entities (MCP servers, vector stores) that aren't provider-specific live in the core plugin. +These packages live at `rhdh-plugins/workspaces/boost/plugins/` and are registered as Backstage backend services per the [Backstage backend system architecture](https://backstage.io/docs/backend-system/architecture/services/). When the full `boost-backend` plugin is installed, it composes these same entity provider packages internally alongside the agentic provider modules. Cross-cutting entities (MCP servers, vector stores) that aren't provider-specific live in the core plugin. **Entity kind strategy:** diff --git a/workspaces/boost/specifications/prd/platform-operations-deployment.md b/workspaces/boost/specifications/prd/platform-operations-deployment.md index f5417270a0..3b19e1f320 100644 --- a/workspaces/boost/specifications/prd/platform-operations-deployment.md +++ b/workspaces/boost/specifications/prd/platform-operations-deployment.md @@ -61,7 +61,7 @@ Admin panels, branding controls, RAG configuration, and onboarding flows must al **Workspace package structure:** -All packages live at `rhdh-plugins/workspace/boost/plugins/`: +All packages live at `rhdh-plugins/workspaces/boost/plugins/`: | Package | Type | Description | | --------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- | From a2746e64ded23ca21996154627e4efc82de39a00 Mon Sep 17 00:00:00 2001 From: gabemontero Date: Wed, 3 Jun 2026 13:04:43 -0400 Subject: [PATCH 7/8] fullsend-update-readme-high-level-intent Signed-off-by: gabemontero --- workspaces/boost/README.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/workspaces/boost/README.md b/workspaces/boost/README.md index 98959588f0..7cc4b5b274 100644 --- a/workspaces/boost/README.md +++ b/workspaces/boost/README.md @@ -2,7 +2,36 @@ This workspace contains the Boost plugin family for Red Hat Developer Hub. -Boost is a rewrite of the [Augment](../augment/) plugin. +## Why Boost Exists + +Boost is a clean-room reimplementation of the [Augment](../augment/) plugin. Rather than refactoring Augment's accumulated tech debt in-place, Boost starts from a new codebase and implements the same (and evolving) product requirements with the right architecture from day one. There is no migration path or code sharing between the two — Augment remains the reference prototype and source of requirements, while Boost is the forward-looking implementation. + +The rationale for this approach is documented in detail in [`specifications/boost-context.md`](specifications/boost-context.md). + +## Directory Structure + +This workspace uses a specification-driven layout that differs from other workspaces in the repo: + +``` +workspaces/boost/ +├── specifications/ # Product requirements +│ ├── boost-context.md # Project rationale, principles, and relationship to Augment +│ └── prd/ # Product Requirements Documents (one per capability area) +├── openspec/ # Implementation specifications (OpenSpec format) +│ └── changes/ # One directory per change, each containing: +│ ├── .openspec.yaml # Change metadata and status +│ ├── proposal.md # Problem statement and approach +│ ├── design.md # Architecture decisions +│ ├── tasks.md # Implementation task breakdown +│ └── specs/ # Behavioral specs (Given/When/Then scenarios) +└── plugins/ # Plugin packages (not yet created) +``` + +**`specifications/`** contains the product-level requirements — what Boost must do and why. The PRDs are organized by capability area: AI chat, agent discovery, platform architecture, security, and operations. + +**`openspec/`** contains the implementation-level specifications — how each capability area will be built. Each change includes a proposal, design decisions, task breakdown, and behavioral specs that serve as acceptance criteria. + +All specs are currently in **draft** status (pre-implementation). They will be maintained alongside the code as implementation progresses. ## Plugins From d406f1774edeadcc56865505e117a3a39a68244c Mon Sep 17 00:00:00 2001 From: gabemontero Date: Wed, 3 Jun 2026 13:30:11 -0400 Subject: [PATCH 8/8] gabe-readme-tweak-to-why-stmt Signed-off-by: gabemontero --- workspaces/boost/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/workspaces/boost/README.md b/workspaces/boost/README.md index 7cc4b5b274..8e3aada84f 100644 --- a/workspaces/boost/README.md +++ b/workspaces/boost/README.md @@ -4,7 +4,11 @@ This workspace contains the Boost plugin family for Red Hat Developer Hub. ## Why Boost Exists -Boost is a clean-room reimplementation of the [Augment](../augment/) plugin. Rather than refactoring Augment's accumulated tech debt in-place, Boost starts from a new codebase and implements the same (and evolving) product requirements with the right architecture from day one. There is no migration path or code sharing between the two — Augment remains the reference prototype and source of requirements, while Boost is the forward-looking implementation. +Boost is a clean-room reimplementation of the [Augment](../augment/) plugin. This effort: + +- Initially serves as a litmus test for our organization's agentic SDLC initiatives that are based on [Fullsend](https://github.com/fullsend-ai/fullsend). +- Subsequently provides a comparison with Augment as it evolves in parallel via work from Red Hat Consulting, where we can see how differences in RHDH architectural alignment and accumulated technical debt impact how well each plugin addresses customer requirements. + - As Augment remains the reference prototype and source of requirements, being able to properly translate those requirements into Boost will be an interesting subplot of this exercise. The rationale for this approach is documented in detail in [`specifications/boost-context.md`](specifications/boost-context.md).