feat(#3304): add HITL approval store backed by cacheService (#3566)

* feat(#3304): add HITL approval store backed by cacheService

Implement BackendApprovalStore for human-in-the-loop tool call
approval state (task 1.10). The store uses Backstage cacheService
with a 10-minute TTL for request-scoped approval lifecycle.

The store supports:
- Creating pending approval requests when the inference loop
  pauses on a tool call with requireApproval: true
- Approving requests with optional parameter edits
- Rejecting requests
- Deleting expired or resolved requests

Follows the same cache-backed pattern as ConversationAgentCache
(task 1.8) and RateLimiter (task 1.9). Handles both string and
auto-deserialized object cache backends.

Wired into the boost backend plugin init and exported from the
package public API. 16 tests covering all operations and edge
cases (corrupt entries, duplicate resolution, unknown IDs).

Closes #3304

* fix: update API report for BackendApprovalStore exports

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

* refactor: move ApprovalRequest and ApprovalStatus types to boost-common

Frontend will need these types for the HITL approval dialog.
BackendApprovalStore now imports from boost-common instead of
defining the types locally.

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/plugins/boost-backend/report.api.md

@@ -5,6 +5,7 @@
 ```ts
 import type { AgenticProvider } from '@red-hat-developer-hub/backstage-plugin-boost-common';
 import type { AgentRecord } from '@red-hat-developer-hub/backstage-plugin-boost-common';
+import type { ApprovalRequest } from '@red-hat-developer-hub/backstage-plugin-boost-common';
 import { BackendFeature } from '@backstage/backend-plugin-api';
 import type { CacheService } from '@backstage/backend-plugin-api';
 import type { ConversationDetails } from '@red-hat-developer-hub/backstage-plugin-boost-common';
@@ -90,6 +91,26 @@ export interface AuthorizeLifecycleActionOptions {
   permissions: PermissionsService;
 }
 
+// @public
+export class BackendApprovalStore {
+  constructor(options: BackendApprovalStoreOptions);
+  approve(
+    requestId: string,
+    resolvedArgs?: string,
+  ): Promise<ApprovalRequest | undefined>;
+  create(request: ApprovalRequest): Promise<void>;
+  delete(requestId: string): Promise<void>;
+  get(requestId: string): Promise<ApprovalRequest | undefined>;
+  reject(requestId: string): Promise<ApprovalRequest | undefined>;
+  static readonly TTL_MS: number;
+}
+
+// @public
+export interface BackendApprovalStoreOptions {
+  cache: CacheService;
+  logger: LoggerService;
+}
+
 // @public
 export const BOOST_CONFIG_SCHEMA_VERSION = 1;
 

workspaces/boost/plugins/boost-backend/src/approval/BackendApprovalStore.test.ts

@@ -0,0 +1,197 @@
+/*
+ * 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 type { ApprovalRequest } from '@red-hat-developer-hub/backstage-plugin-boost-common';
+import { BackendApprovalStore } from './BackendApprovalStore';
+
+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;
+}
+
+function createPendingRequest(
+  overrides?: Partial<ApprovalRequest>,
+): ApprovalRequest {
+  return {
+    requestId: 'req-1',
+    conversationId: 'conv-1',
+    toolCallId: 'tc-1',
+    toolName: 'deploy-service',
+    args: '{"service":"my-app","env":"production"}',
+    status: 'pending',
+    userRef: 'user:default/developer',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    message: 'Deploy my-app to production?',
+    ...overrides,
+  };
+}
+
+describe('BackendApprovalStore', () => {
+  let cache: CacheService;
+  let store: BackendApprovalStore;
+
+  beforeEach(() => {
+    cache = createMockCache();
+    store = new BackendApprovalStore({
+      cache,
+      logger: createMockLogger(),
+    });
+  });
+
+  it('uses cacheService withOptions for namespace isolation', () => {
+    expect(cache.withOptions).toHaveBeenCalledWith({
+      defaultTtl: BackendApprovalStore.TTL_MS,
+    });
+  });
+
+  it('has a 10-minute TTL', () => {
+    expect(BackendApprovalStore.TTL_MS).toBe(10 * 60 * 1000);
+  });
+
+  describe('create and get', () => {
+    it('stores and retrieves an approval request', async () => {
+      const request = createPendingRequest();
+      await store.create(request);
+      const result = await store.get('req-1');
+      expect(result).toEqual(request);
+    });
+
+    it('returns undefined for unknown request', async () => {
+      const result = await store.get('unknown');
+      expect(result).toBeUndefined();
+    });
+
+    it('handles auto-deserialized object from cache backend', async () => {
+      const request = createPendingRequest();
+      // Simulate a cache backend that auto-deserializes JSON
+      (cache.get as jest.Mock).mockResolvedValueOnce(request);
+      const result = await store.get('req-1');
+      expect(result).toEqual(request);
+    });
+
+    it('returns undefined for corrupt cache entry', async () => {
+      (cache.get as jest.Mock).mockResolvedValueOnce('not-valid-json{');
+      const result = await store.get('req-1');
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined for non-approval object in cache', async () => {
+      (cache.get as jest.Mock).mockResolvedValueOnce({ unrelated: true });
+      const result = await store.get('req-1');
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('approve', () => {
+    it('approves a pending request with original args', async () => {
+      await store.create(createPendingRequest());
+      const result = await store.approve('req-1');
+
+      expect(result).toBeDefined();
+      expect(result!.status).toBe('approved');
+      expect(result!.resolvedAt).toBeDefined();
+      expect(result!.resolvedArgs).toBe(
+        '{"service":"my-app","env":"production"}',
+      );
+    });
+
+    it('approves with edited arguments', async () => {
+      await store.create(createPendingRequest());
+      const editedArgs = '{"service":"my-app","env":"staging"}';
+      const result = await store.approve('req-1', editedArgs);
+
+      expect(result).toBeDefined();
+      expect(result!.status).toBe('approved');
+      expect(result!.resolvedArgs).toBe(editedArgs);
+    });
+
+    it('returns undefined for unknown request', async () => {
+      const result = await store.approve('unknown');
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined for already-approved request', async () => {
+      await store.create(createPendingRequest());
+      await store.approve('req-1');
+      const result = await store.approve('req-1');
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined for already-rejected request', async () => {
+      await store.create(createPendingRequest());
+      await store.reject('req-1');
+      const result = await store.approve('req-1');
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('reject', () => {
+    it('rejects a pending request', async () => {
+      await store.create(createPendingRequest());
+      const result = await store.reject('req-1');
+
+      expect(result).toBeDefined();
+      expect(result!.status).toBe('rejected');
+      expect(result!.resolvedAt).toBeDefined();
+      expect(result!.resolvedArgs).toBeUndefined();
+    });
+
+    it('returns undefined for unknown request', async () => {
+      const result = await store.reject('unknown');
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined for already-resolved request', async () => {
+      await store.create(createPendingRequest());
+      await store.approve('req-1');
+      const result = await store.reject('req-1');
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('delete', () => {
+    it('removes an approval request', async () => {
+      await store.create(createPendingRequest());
+      await store.delete('req-1');
+      const result = await store.get('req-1');
+      expect(result).toBeUndefined();
+    });
+  });
+});