feat(#3297): scaffold boost-common package with shared types, service ref, and permissions

[fullsend-ai-coder]

Create the boost-common plugin package that all other boost packages depend on. This is a common-library providing shared interfaces, the AI provider service ref, and fine-grained permission definitions.

Types and interfaces (tasks 1.1-1.3):

• AgenticProvider, ProviderDescriptor, ProviderCapabilities interfaces
• NormalizedStreamEvent union type (text_delta, tool_call, tool_result,
  error, done)
• ConversationSummary, ConversationDetails, InputItem conversation types
• ChatRequest, ChatResponse, and optional capability interfaces (Rag,
  Safety, Evaluation, Conversation)

Service ref (task 1.4):

• boostAiProviderServiceRef via createServiceRef with ID
  'boost.ai-provider' and AgenticProvider type parameter

Permissions (security tasks 1.1-1.4):

• 10 agent permissions (list, register, promote, approve, demote,
  publish, unpublish, withdraw, delete, configure)
• 5 tool permissions (promote, approve, demote, publish, unpublish)
• 1 infrastructure permission (kagenti.admin)
• 5 functional permissions (chat.read, chat.create, documents.manage,
  mcp.manage, config.manage)
• Resource types: boost-agent, boost-tool
• Conditional rule name constants: IS_OWNER, IS_NOT_CREATOR,
  HAS_LIFECYCLE_STAGE

Provider isolation (task 1.6):

• No provider-specific types in the common package; test verifies no
  LlamaStack/Kagenti type leaks

Note: yarn install and test/lint/build commands could not run in the sandbox due to network restrictions (npm registry unreachable). Tests and prettier formatting require manual verification after dependency installation. The test file validates all export shapes, permission counts (16 resource + 5 functional = 21 total), resource type assignments, and absence of provider-specific types.

---

Closes #3297

Post-script verification

• Branch is not main/master (agent/3297-boost-common-package)
• Secret scan passed (gitleaks — 5c9083af21efc8f88dad77d38493cb136d4ddb9a..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[rhdh-gh-app]

Missing Changesets

The following package(s) are changed by this PR but do not have a changeset:

• @red-hat-developer-hub/backstage-plugin-boost-common

See CONTRIBUTING.md for more information about how to add changesets.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@red-hat-developer-hub/backstage-plugin-boost-common	workspaces/boost/plugins/boost-common	none	v0.1.0

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fullsend-ai-review]

Review

Findings

Medium

• [naming-coherence / api-contract] workspaces/boost/plugins/boost-common/src/permissions.ts:318 — The boostResourcePermissions array is documented as "All 16 resource permissions (10 agent + 5 tool + 1 kagenti-infra)" but includes 4 permissions that lack a resourceType property: boostAgentListPermission, boostAgentRegisterPermission, boostAgentConfigurePermission, and boostKagentiAdminPermission. Only 12 of the 16 entries are actually resource-typed permissions eligible for conditional policy evaluation. The section header comment "Agent permissions (10 resource permissions)" is also inaccurate — only 7 of 10 agent permissions carry a resourceType. The test at index.test.ts:192 reinforces this misleading invariant by asserting length 16 without verifying resourceType on each entry. This naming will mislead downstream permission policy authors.
  Remediation: Either (a) rename to boostCorePermissions or similar to avoid implying all entries are resource-typed, or (b) split into separate arrays for true resource permissions (those with resourceType) and basic permissions, then compose boostPermissions from both. Update the section header comments and tests accordingly.

Low

• [backward-compatible-extensibility] workspaces/boost/plugins/boost-common/src/types.ts:117 — InputItem.role is a closed union ('user' | 'assistant' | 'system'). Adding new roles (e.g., 'tool', 'developer') in the future will be a breaking change for consumers with exhaustive matching. Similarly, NormalizedStreamEvent is a closed discriminated union — adding new event variants (e.g., 'thinking', 'usage') will break exhaustive switch/case handling. For a v0.1.0 package this is acceptable, but consider documenting that these unions may grow.

• [backward-compatible-extensibility] workspaces/boost/plugins/boost-common/src/types.ts:119 — InputItem.content is typed as a plain string, but many AI providers support structured content (arrays of text, images, tool-use blocks). Changing this later would be a breaking change. Consider adding an optional parts?: unknown[] field for future extensibility.

• [api-shape] workspaces/boost/plugins/boost-common/src/index.ts — Uses export * from (barrel re-exports) for all modules including types. The more mature lightspeed-common package in this repo uses explicit named re-exports with export type { ... }, which provides clearer public API surface and avoids accidentally leaking internal types.

• [api-surface-design] workspaces/boost/plugins/boost-common/src/types.ts:59 — RagCapability.query returns Promise<unknown>, providing no type safety for consumers. Consider defining a minimal result interface.

• [naming-convention] workspaces/boost/plugins/boost-common/package.json — The pluginPackages array only lists the common package itself. Established pattern in the repo (see augment-common, lightspeed-common) is to list all sibling packages. Update when sibling packages are added.

Info

• [scope-alignment] The PR introduces RagCapability, SafetyCapability, EvaluationCapability, ConversationCapability, ChatRequest, and ChatResponse interfaces not explicitly listed in issue boost-common — Shared types, service ref, and permission definitions (issue 1 of 15) #3297 tasks, but these are structurally required by the AgenticProvider interface (task 1.1). Justified scope expansion.

• [specification-gap] The fine-grained permissions spec references boost.access (top-level gate) and boost.admin (coarse-grained fallback) permissions. These are not defined in this PR — likely deferred to a later issue in the 15-issue series.

• [code-organization] The boost-common types (ProviderCapabilities, ProviderDescriptor, NormalizedStreamEvent, ConversationSummary, etc.) overlap with types in augment-common. Noted for awareness — may be intentional if boost replaces augment.

• [architectural-coherence] The boostAiProviderServiceRef implementation matches the code sample in openspec/changes/pluggable-ai-platform-architecture/design.md Decision 1. Package naming, pluginId, permission naming, and resource types align with AGENTS.md conventions.

[gabemontero]

per discussion with @durandom in https://redhat-internal.slack.com/archives/C0AR8BTMSJH/p1780929700288199 I'm going to punt on use of fullsend for addressing #3297 for now