feat(#3307): add boost-backend-module-kagenti provider module (#3573)

* feat(#3307): add boost-backend-module-kagenti provider module

Create the Kagenti provider module as an independent
createBackendModule with pluginId 'boost' and moduleId
'kagenti'. The module registers KagentiProvider via the
boostProviderExtensionPoint, enabling Kagenti as an AI
backend using the A2A protocol.

Implementation includes:
- KagentiProvider implementing AgenticProvider with A2A
  protocol integration for chat and streaming
- KagentiProviderFactory reading connection config from
  boost.providers.kagenti and creating all caches
- AgentCardCache using cacheService with 5m TTL (task 3.3)
- KeycloakTokenCache with dynamic TTL per token (task 3.4)
- SessionMap for A2A sessions with 24h TTL (task 3.7)
- Kagenti-specific types (agent cards, A2A protocol,
  namespaces) defined in the module only (task 3b.1)
- No cross-provider imports (task 2.5)

All caches use Backstage coreServices.cache per Decision 3.
No raw Map<> caches. 25 tests passing with coverage.

Closes #3307

* fix: address review — canceled state, chat fetch guard, cache object handling

- Handle 'canceled' task status in normalizeStreamEvent (yields error event)
- Wrap chat() fetch in try/catch for consistent error handling with chatStream()
- Handle pre-parsed objects from cache backends in AgentCardCache and SessionMap
- Add tests for all three fixes (31 tests passing)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: use unknown cast for cache JsonValue to domain type conversions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: annotate entity provider composition as deferred to issue #3308

The provider-packaging spec referenced catalogProcessingExtensionPoint
entity provider composition in both module registration scenarios.
That work is tracked in the agent-creation-discovery change (issue #3308),
not in the provider module issues. Added cross-reference annotations.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: check task status in chat(), add done after failed/canceled, validate TTL

- chat() now throws on failed/canceled A2A task status instead of
  returning empty string
- normalizeStreamEvent yields done after failed/canceled for symmetry
  with completed state (stream terminates immediately)
- KeycloakTokenCache.set() skips cache for non-positive TTL values
- Added tests: chat() failed/canceled, chatStream failed, TTL validation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Co-authored-by: gabemontero <gmontero@redhat.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

workspaces/boost/openspec/changes/pluggable-ai-platform-architecture/specs/provider-packaging/spec.md

@@ -15,8 +15,8 @@ The Llama Stack provider MUST be packaged as an independent Backstage backend mo
 - **WHEN** the `plugin-boost-backend-module-llamastack` package is installed
 - **THEN** it creates a `createBackendModule` with `pluginId: 'boost'` and `moduleId: 'llamastack'`
 - **AND** it registers `ResponsesApiProviderFactory` via `boostProviderExtensionPoint` (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 composes `llamastack-entity-provider` internally, registering its entity providers via `catalogProcessingExtensionPoint` _(deferred to `agent-creation-discovery` change, issue #3308)_
+- **AND** `llamastack-entity-provider` is also independently deployable as its own RHDH dynamic plugin (without boost) _(deferred to `agent-creation-discovery` change, issue #3308)_
 - **AND** it depends on `coreServices.config` for Llama Stack connection settings
 - **AND** it depends on `coreServices.logger` and `coreServices.cache` for operational services
 
@@ -47,8 +47,8 @@ The Kagenti provider MUST be packaged as an independent Backstage backend module
 - **WHEN** the `plugin-boost-backend-module-kagenti` package is installed
 - **THEN** it creates a `createBackendModule` with `pluginId: 'boost'` and `moduleId: 'kagenti'`
 - **AND** it registers `KagentiProviderFactory` via `boostProviderExtensionPoint` (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 composes `kagenti-entity-provider` internally, registering its entity providers via `catalogProcessingExtensionPoint` _(deferred to `agent-creation-discovery` change, issue #3308)_
+- **AND** `kagenti-entity-provider` is also independently deployable as its own RHDH dynamic plugin (without boost) _(deferred to `agent-creation-discovery` change, issue #3308)_
 - **AND** it depends on `coreServices.config` for Kagenti/Keycloak connection settings
 - **AND** it depends on `coreServices.cache` for agent card caching and token management
 

workspaces/boost/plugins/boost-backend-module-kagenti/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

workspaces/boost/plugins/boost-backend-module-kagenti/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@red-hat-developer-hub/backstage-plugin-boost-backend-module-kagenti",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Kagenti provider module for the boost AI platform",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "backstage": {
+    "role": "backend-plugin-module",
+    "pluginId": "boost",
+    "pluginPackage": "@red-hat-developer-hub/backstage-plugin-boost-backend",
+    "pluginPackages": [
+      "@red-hat-developer-hub/backstage-plugin-boost-backend",
+      "@red-hat-developer-hub/backstage-plugin-boost-backend-module-kagenti",
+      "@red-hat-developer-hub/backstage-plugin-boost-common",
+      "@red-hat-developer-hub/backstage-plugin-boost-node"
+    ]
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
+  "dependencies": {
+    "@backstage/backend-plugin-api": "^1.9.1",
+    "@red-hat-developer-hub/backstage-plugin-boost-common": "workspace:^",
+    "@red-hat-developer-hub/backstage-plugin-boost-node": "workspace:^"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.34.5"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "backstage-cli package build",
+    "clean": "backstage-cli package clean",
+    "lint": "backstage-cli package lint",
+    "lint:check": "backstage-cli package lint",
+    "lint:fix": "backstage-cli package lint --fix",
+    "test": "backstage-cli package test --passWithNoTests --coverage",
+    "tsc": "tsc",
+    "start": "backstage-cli package start",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/redhat-developer/rhdh-plugins.git",
+    "directory": "workspaces/boost/plugins/boost-backend-module-kagenti"
+  },
+  "homepage": "https://red.ht/rhdh",
+  "bugs": "https://github.com/redhat-developer/rhdh-plugins/issues"
+}

workspaces/boost/plugins/boost-backend-module-kagenti/report.api.md

@@ -0,0 +1,11 @@
+## API Report File for "@red-hat-developer-hub/backstage-plugin-boost-backend-module-kagenti"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { BackendFeature } from '@backstage/backend-plugin-api';
+
+// @public
+const boostModuleKagenti: BackendFeature;
+export default boostModuleKagenti;
+```

workspaces/boost/plugins/boost-backend-module-kagenti/src/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Kagenti provider module for the boost AI platform.
+ *
+ * @packageDocumentation
+ */
+
+export { boostModuleKagenti as default } from './module';

workspaces/boost/plugins/boost-backend-module-kagenti/src/module.ts

@@ -0,0 +1,89 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  coreServices,
+  createBackendModule,
+} from '@backstage/backend-plugin-api';
+import { boostProviderExtensionPoint } from '@red-hat-developer-hub/backstage-plugin-boost-node';
+import { KagentiProviderFactory } from './provider/KagentiProviderFactory';
+
+/**
+ * Kagenti provider module for the boost plugin.
+ *
+ * Registers a KagentiProvider via the boost extension point,
+ * enabling Kagenti as an AI backend via the A2A protocol. All
+ * caches use Backstage cacheService (Decision 3).
+ *
+ * Install alongside the core boost plugin:
+ *
+ * ```ts
+ * // packages/backend/src/index.ts
+ * backend.add(import('@red-hat-developer-hub/backstage-plugin-boost-backend'));
+ * backend.add(import('@red-hat-developer-hub/backstage-plugin-boost-backend-module-kagenti'));
+ * ```
+ *
+ * @public
+ */
+export const boostModuleKagenti = createBackendModule({
+  pluginId: 'boost',
+  moduleId: 'kagenti',
+  register(reg) {
+    reg.registerInit({
+      deps: {
+        providers: boostProviderExtensionPoint,
+        config: coreServices.rootConfig,
+        cache: coreServices.cache,
+        logger: coreServices.logger,
+      },
+      async init({ providers, config, cache, logger }) {
+        logger.info('Initializing Kagenti provider module');
+
+        const factory = new KagentiProviderFactory({
+          config,
+          cache,
+          logger,
+        });
+
+        const { provider, agentCardCache, keycloakTokenCache, sessionMap } =
+          factory.create();
+
+        // Register the provider with the boost plugin
+        providers.registerProvider(provider);
+
+        logger.info(
+          `Kagenti provider registered (id: ${provider.descriptor.id})`,
+        );
+        logger.info(
+          `Caches initialized: agentCard (5m TTL), keycloakToken (dynamic TTL), ` +
+            `sessionMap (24h TTL)`,
+        );
+
+        // Log cache readiness (these are available for future route handlers)
+        logger.debug(
+          `AgentCardCache: ready, KeycloakTokenCache: ready, SessionMap: ready`,
+        );
+
+        // Suppress unused-variable warnings — these caches are initialized
+        // and available for provider-internal operations. Future iterations
+        // will wire them into route handlers and orchestration flows.
+        void agentCardCache;
+        void keycloakTokenCache;
+        void sessionMap;
+      },
+    });
+  },
+});

workspaces/boost/plugins/boost-backend-module-kagenti/src/provider/AgentCardCache.test.ts

@@ -0,0 +1,103 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type {
+  CacheService,
+  LoggerService,
+} from '@backstage/backend-plugin-api';
+import { AgentCardCache } from './AgentCardCache';
+import type { AgentCard } from '../types';
+
+function createMockLogger(): LoggerService {
+  return {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    debug: jest.fn(),
+    child: jest.fn().mockReturnThis(),
+  };
+}
+
+function createMockCache(): CacheService {
+  const store = new Map<string, unknown>();
+  const cache: CacheService = {
+    get: jest.fn(async (key: string) => store.get(key)) as CacheService['get'],
+    set: jest.fn(async (key: string, value: unknown) => {
+      store.set(key, value);
+    }),
+    delete: jest.fn(async (key: string) => {
+      store.delete(key);
+    }),
+    withOptions: jest.fn().mockReturnThis(),
+  };
+  return cache;
+}
+
+describe('AgentCardCache', () => {
+  let cache: CacheService;
+  let agentCardCache: AgentCardCache;
+
+  beforeEach(() => {
+    cache = createMockCache();
+    agentCardCache = new AgentCardCache({
+      cache,
+      logger: createMockLogger(),
+    });
+  });
+
+  it('uses cacheService withOptions with 5m TTL', () => {
+    expect(cache.withOptions).toHaveBeenCalledWith({
+      defaultTtl: { minutes: 5 },
+    });
+  });
+
+  it('stores and retrieves agent cards', async () => {
+    const cards: AgentCard[] = [
+      { id: 'agent-1', name: 'Agent One', url: 'http://agent-1:8080' },
+      { id: 'agent-2', name: 'Agent Two', url: 'http://agent-2:8080' },
+    ];
+
+    await agentCardCache.set(cards);
+    const result = await agentCardCache.get();
+    expect(result).toEqual(cards);
+  });
+
+  it('returns undefined when no cards are cached', async () => {
+    const result = await agentCardCache.get();
+    expect(result).toBeUndefined();
+  });
+
+  it('invalidates cached cards', async () => {
+    const cards: AgentCard[] = [
+      { id: 'agent-1', name: 'Agent One', url: 'http://agent-1:8080' },
+    ];
+
+    await agentCardCache.set(cards);
+    await agentCardCache.invalidate();
+    const result = await agentCardCache.get();
+    expect(result).toBeUndefined();
+  });
+
+  it('handles pre-parsed array returned by cache backend', async () => {
+    const cards: AgentCard[] = [
+      { id: 'agent-1', name: 'Agent One', url: 'http://agent-1:8080' },
+    ];
+    (cache.get as jest.Mock).mockResolvedValueOnce(cards);
+
+    const result = await agentCardCache.get();
+    expect(result).toEqual(cards);
+  });
+});