Feature registry

Not sure whether to use FeatureProvider or session tools? Read Tools and features first.

FeatureProvider manages feature state (history, visibility, tool execution) but ships no business features. Your app provides a registry that maps agent tool names to React components and handlers.

Architecture

Basic setup

import { FeatureProvider } from '@scenaro/sdk/react';
import { SearchFeature } from './features/search';
import { searchHandler } from './features/search-handler';

const FEATURE_REGISTRY = new Map([
  ['collection:items:search', {
    component: SearchFeature,
    handlers: { search_collection_items: searchHandler },
    primaryTool: 'search_collection_items',
    toolNames: ['search_collection_items'],
  }],
]);

<FeatureProvider
  registry={FEATURE_REGISTRY}
  onResetBuckets={() => bucketStorage.resetAll()}
  clearHistoryOnSessionEnd={false}
  initialVisibility={true}
  initialPosition="right"
>
  {children}
</FeatureProvider>

ToolRegistryEntry

Field	Type	Description
`component`	`React.ComponentType`	UI rendered when the feature is active
`handlers`	`Record<string, ToolHandler>`	Async functions called on tool RPC
`primaryTool`	`string`	Main tool name for this feature
`toolNames`	`string[]`	All tool names that map to this feature
`overlay`	`boolean`	Render as overlay vs inline panel
`propsSelector`	`function`	Map tool state → component props

Tool handler signature

type ToolHandler = (
  requestId: string,
  args: unknown,
  settings?: Record<string, unknown>,
  collections?: unknown[],
) => Promise<ToolExecutionResult> | ToolExecutionResult;

Return shape:

{
  requestId: string;
  response: {
    code: 'SUCCESS' | 'ERROR' | 'TIMEOUT' | 'CANCELLED';
    data: unknown; // sent back to the agent
  };
  componentData?: Record<string, unknown>; // updates UI state
}

Config handshake

When the agent joins, it sends a config message with features and collections. FeatureProvider:

Registers available features from the config
Maps tool names to registry entries
The session (useScenaroSession) registers Transport RPC methods for each tool

For simple one-off tools that don’t need feature UI, you can skip the registry and pass plain functions via the tools option of useScenaroSession. See React integration.

Common feature IDs

Feature ID	Description
`collection:items:search`	Search and explore catalog items
`collection:items:display`	Product detail sheet
`collection:items:comparison`	Side-by-side comparison
`bucket:list:crud`	Basket / list management
`workflow:conversation:end`	End conversation, redirect

Feature IDs come from Cockpit configuration. Your registry keys must match.

What stays outside the SDK

Per the architecture decision (July 2026):

Feature UI components (too brand-specific)
Collection API clients
Product templates and styling
Custom FeatureManager wrappers (legacy — migrate to FeatureProvider)

​Architecture

​Basic setup

​ToolRegistryEntry

​Tool handler signature

​Config handshake

​Common feature IDs

​What stays outside the SDK

​Recipes

Architecture

Basic setup

ToolRegistryEntry

Tool handler signature

Config handshake

Common feature IDs

What stays outside the SDK

Recipes