@umbraco-ai/core 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umbraco-ai/core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "types": "./types/umbraco-ai-public-types.d.ts",
   "files": [

package/types/umbraco-ai-public-types.d.ts

@@ -1,10 +1,13 @@
 import { CSSResult } from 'lit';
 import { HTMLElementConstructor } from '@umbraco-cms/backoffice/extension-api';
+import type { ManifestApi } from '@umbraco-cms/backoffice/extension-api';
 import type { ManifestBase } from '@umbraco-cms/backoffice/extension-api';
+import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
 import { Observable } from '@umbraco-cms/backoffice/external/rxjs';
 import { Observable as Observable_2 } from 'rxjs';
 import { TemplateResult } from 'lit-html';
-import type { TemplateResult as TemplateResult_2 } from '@umbraco-cms/backoffice/external/lit';
+import { TemplateResult as TemplateResult_2 } from '@umbraco-cms/backoffice/external/lit';
+import { UmbApi } from '@umbraco-cms/backoffice/extension-api';
 import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
 import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
 import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
@@ -18,6 +21,8 @@ import { UmbModalBaseElement } from '@umbraco-cms/backoffice/modal';
 import { UmbModalToken } from '@umbraco-cms/backoffice/modal';
 import { UUIFormControlMixinElement } from '@umbraco-ui/uui-base';
 
+export declare const coreClientReady: Promise<void>;
+
 /**
  * Helper to create context item from serialized entity.
  */
@@ -41,7 +46,7 @@ export declare function dispatchActionEvent(host: any, event: Event): void;
 declare type EntityVersionComparisonResponseModel = {
     fromVersion: number;
     toVersion: number;
-    changes: Array<PropertyChangeModel>;
+    changes: Array<ValueChangeModel>;
 };
 
 declare type EntityVersionHistoryResponseModel = {
@@ -83,11 +88,43 @@ export declare interface ManifestEntityAdapter extends ManifestBase {
     }>;
 }
 
-declare type PropertyChangeModel = {
-    propertyName: string;
-    oldValue?: string | null;
-    newValue?: string | null;
-};
+/**
+ * Manifest for request context contributor extensions.
+ *
+ * Request context contributors are invoked before each AI request to gather
+ * ambient context (current section, entity, surface, etc.) into
+ * UaiRequestContextItem[] for the backend.
+ *
+ * Core contributors are unconditional (always run).
+ * Product-specific contributors can use Umbraco's conditions framework
+ * to gate when they contribute.
+ *
+ * @example
+ * ```typescript
+ * // Unconditional contributor (always contributes)
+ * const manifest: ManifestUaiRequestContextContributor = {
+ *     type: "uaiRequestContextContributor",
+ *     alias: "UmbracoAI.RequestContextContributor.Section",
+ *     name: "Section Request Context Contributor",
+ *     api: () => import("./section.contributor.js"),
+ *     weight: 100,
+ * };
+ *
+ * // Kind-based contributor (api provided by kind, meta configures it)
+ * const surfaceManifest: ManifestUaiRequestContextContributor = {
+ *     type: "uaiRequestContextContributor",
+ *     kind: "agentSurface",
+ *     alias: "UmbracoAI.Copilot.RequestContextContributor.AgentSurface",
+ *     name: "Copilot Agent Surface Request Context Contributor",
+ *     meta: { surface: "copilot" },
+ * };
+ * ```
+ */
+export declare interface ManifestUaiRequestContextContributor extends ManifestApi<UaiRequestContextContributorApi> {
+    type: typeof UAI_REQUEST_CONTEXT_CONTRIBUTOR_EXTENSION_TYPE;
+    /** Optional metadata passed to the contributor's `contribute()` method. */
+    meta?: Record<string, unknown>;
+}
 
 /**
  * Resolve an entity adapter by entity type.
@@ -109,6 +146,39 @@ declare type PropertyChangeModel = {
  */
 export declare function resolveEntityAdapterByType(entityType: string): Promise<UaiEntityAdapterApi | undefined>;
 
+/**
+ * Converts a string to camelCase by splitting on separators (-, _, ., spaces).
+ * Used for converting tool/scope IDs to localization key format.
+ *
+ * @example
+ * toCamelCase("content-read") // "contentRead"
+ * toCamelCase("media_write") // "mediaWrite"
+ * toCamelCase("some.scope") // "someScope"
+ */
+export declare function toCamelCase(str: string): string;
+
+export declare type ToolItemResponseModel = {
+    id: string;
+    name: string;
+    description: string;
+    scopeId: string;
+    isDestructive: boolean;
+    tags: Array<string>;
+};
+
+export declare type ToolScopeItemResponseModel = {
+    id: string;
+    icon: string;
+    isDestructive: boolean;
+    domain: string;
+};
+
+export declare const UAI_ADDONS_MENU_ALIAS = "Uai.Menu.Addons";
+
+export declare const UAI_AI_SECTION_PATHNAME = "ai";
+
+export declare const UAI_CORE_MENU_ALIAS = "Uai.Menu.Core";
+
 /**
  * A constant representing an empty GUID.
  * @public
@@ -122,11 +192,18 @@ export declare const UAI_ENTITY_ADAPTER_EXTENSION_TYPE = "uaiEntityAdapter";
 
 export declare const UAI_ITEM_PICKER_MODAL: UmbModalToken<UaiItemPickerModalData, UaiItemPickerModalValue>;
 
+/**
+ * Extension type alias for request context contributors.
+ */
+declare const UAI_REQUEST_CONTEXT_CONTRIBUTOR_EXTENSION_TYPE = "uaiRequestContextContributor";
+
 /**
  * Modal token for the rollback confirmation modal.
  */
 export declare const UAI_ROLLBACK_MODAL: UmbModalToken<UaiRollbackModalData, UaiRollbackModalValue>;
 
+export declare const UAI_SECTION_ALIAS = "Uai.Section.AI";
+
 /**
  * Context token for consuming the Workspace Registry.
  * Use this to access active workspaces from any component.
@@ -225,7 +302,7 @@ export declare interface UaiChatResult {
  * Chat message role.
  * @public
  */
-export declare type UaiChatRole = 'user' | 'assistant' | 'system';
+export declare type UaiChatRole = "user" | "assistant" | "system";
 
 /**
  * Streaming chunk from chat completion.
@@ -401,11 +478,17 @@ export declare class UaiDocumentAdapter implements UaiEntityAdapterApi {
      */
     serializeForLlm(workspaceContext: unknown): Promise<UaiSerializedEntity>;
     /**
-     * Apply a property change to the document workspace.
+     * Apply a value change to the document workspace.
      * Changes are staged in the workspace - user must save to persist.
+     * For CMS documents, the path is treated as the property alias.
      * Only supports text-based properties (TextBox, TextArea) for now.
      */
-    applyPropertyChange(workspaceContext: unknown, change: UaiPropertyChange): Promise<UaiPropertyChangeResult>;
+    applyValueChange(workspaceContext: unknown, change: UaiValueChange): Promise<UaiValueChangeResult>;
+    /**
+     * Cleanup method required by UmbApi base type.
+     * Currently no resources to clean up as the adapter is stateless.
+     */
+    destroy(): void;
 }
 
 /**
@@ -420,6 +503,7 @@ export declare interface UaiEditableModelFieldModel {
     defaultValue?: unknown;
     sortOrder: number;
     isRequired: boolean;
+    group?: string;
 }
 
 /**
@@ -512,7 +596,7 @@ export declare class UaiEntityActionEvent extends UmbEntityActionEvent {
  * - Serializing entity data for LLM consumption
  * - Applying property changes (optional)
  */
-export declare interface UaiEntityAdapterApi {
+export declare interface UaiEntityAdapterApi extends UmbApi {
     readonly entityType: string;
     /**
      * Check if this adapter can handle the given workspace context.
@@ -547,13 +631,13 @@ export declare interface UaiEntityAdapterApi {
      */
     serializeForLlm(workspaceContext: unknown): Promise<UaiSerializedEntity>;
     /**
-     * Apply a property change to the workspace (staged, not persisted).
+     * Apply a value change to the workspace (staged, not persisted).
      * Optional - some entity types may be read-only.
      * @param workspaceContext The workspace context to modify
-     * @param change The property change to apply
+     * @param change The value change to apply
      * @returns Result indicating success or failure with error message
      */
-    applyPropertyChange?(workspaceContext: unknown, change: UaiPropertyChange): Promise<UaiPropertyChangeResult>;
+    applyValueChange?(workspaceContext: unknown, change: UaiValueChange): Promise<UaiValueChangeResult>;
 }
 
 /**
@@ -590,23 +674,33 @@ export declare class UaiEntityAdapterContext extends UmbControllerBase {
     /**
      * Serialize the selected entity for LLM context injection.
      * Returns undefined if no entity is selected.
+     * Waits for initialization to complete before attempting to serialize.
      */
     serializeSelectedEntity(): Promise<UaiSerializedEntity | undefined>;
     /**
-     * Apply a property change to the currently selected entity.
+     * Apply a value change to the currently selected entity.
      * Changes are staged in the workspace - user must save to persist.
-     * @param change The property change to apply
+     * Waits for initialization to complete before attempting to apply changes.
+     * @param change The value change to apply
      * @returns Result indicating success or failure with error message
      */
-    applyPropertyChange(change: UaiPropertyChange): Promise<UaiPropertyChangeResult>;
+    applyValueChange(change: UaiValueChange): Promise<UaiValueChangeResult>;
 }
 
 /**
- * Entity Adapter Types
- *
- * Minimal interfaces for the entity adapter system that enables
- * AI tools to interact with Umbraco entities being edited.
+ * Extended menu item manifest that supports child entity types for entity container menu items.
  */
+export declare interface UaiEntityContainerMenuItemManifest extends ManifestMenuItem {
+    kind: 'entityContainer';
+    meta: ManifestMenuItem['meta'] & {
+        /**
+         * Child entity types that should keep this menu item highlighted when active.
+         * Used by the entityContainer menu item kind to maintain highlighting when navigating to child entities.
+         */
+        childEntityTypes?: string[];
+    };
+}
+
 /**
  * Represents the identity of an entity being edited.
  * Supports hierarchical relationships via recursive parentContext.
@@ -641,10 +735,37 @@ export declare class UaiEntityDeletedRedirectController extends UmbControllerBas
     constructor(host: UmbControllerHost, args: UaiEntityDeletedRedirectArgs);
 }
 
+/**
+ * Frontend tool metadata for display in tool pickers.
+ * This is the minimal data needed by consumers to list available frontend tools.
+ */
+export declare interface UaiFrontendToolData {
+    /** Unique tool identifier (matches AG-UI tool call name) */
+    id: string;
+    /** Display name for the tool */
+    name: string;
+    /** Description of what the tool does */
+    description: string;
+    /** Scope identifier for permission grouping */
+    scopeId: string;
+}
+
+/**
+ * Repository API for accessing frontend tool metadata.
+ * Implemented by packages that provide frontend tools (e.g., Copilot).
+ */
+export declare interface UaiFrontendToolRepositoryApi extends UmbApi {
+    /**
+     * Get all available frontend tools.
+     * @returns Array of frontend tool metadata
+     */
+    getTools(): Promise<UaiFrontendToolData[]>;
+}
+
 export declare interface UaiItemPickerModalData {
     items?: UaiPickableItemModel[];
     fetchItems?: () => Promise<UaiPickableItemModel[]>;
-    selectionMode?: 'single' | 'multiple';
+    selectionMode?: "single" | "multiple";
     tagTemplate?: (item: UaiPickableItemModel) => TemplateResult_2;
     title?: string;
     buttonLabel?: string;
@@ -702,6 +823,10 @@ export declare class UaiModelEditorElement extends UmbLitElement {
      * Placeholder text shown when the schema has no fields.
      */
     emptyMessage?: string;
+    /**
+     * Placeholder text shown when the schema has no fields.
+     */
+    defaultGroup?: string;
     private _propertyValues;
     shouldUpdate(changedProperties: Map<string, unknown>): boolean;
     updated(changedProperties: Map<string, unknown>): void;
@@ -792,28 +917,68 @@ export declare class UaiProfilePickerElement extends UaiProfilePickerElement_bas
 declare const UaiProfilePickerElement_base: HTMLElementConstructor<UmbFormControlMixinElement<string | string[] | undefined>> & typeof UmbLitElement;
 
 /**
- * Request to change a property value.
- * Changes are staged in the workspace - user must save to persist.
+ * Mutable context bag passed to each contributor.
+ * Mirrors the backend AIRuntimeContext pattern -- contributors
+ * call `add()` to push context items rather than returning them.
  */
-export declare interface UaiPropertyChange {
-    /** Property alias */
-    alias: string;
-    /** New value to set */
-    value: unknown;
-    /** Culture for variant content (undefined = invariant) */
-    culture?: string;
-    /** Segment for segmented content (undefined = no segment) */
-    segment?: string;
+export declare class UaiRequestContext {
+    #private;
+    /**
+     * Add a context item to the request context.
+     */
+    add(item: UaiRequestContextItem): void;
+    /**
+     * Get all contributed context items.
+     */
+    getItems(): UaiRequestContextItem[];
 }
 
 /**
- * Result of a property change operation.
+ * Collects request context from all registered contributors.
+ *
+ * Queries uaiRequestContextContributor extensions and uses
+ * `loadManifestApi` to load + instantiate each API (same pattern
+ * as UaiFrontendToolManager).
+ *
+ * API instances are cached for the lifetime of the collector.
  */
-export declare interface UaiPropertyChangeResult {
-    /** Whether the change was applied successfully */
-    success: boolean;
-    /** Human-readable error message if failed */
-    error?: string;
+export declare class UaiRequestContextCollector extends UmbControllerBase {
+    #private;
+    constructor(host: UmbControllerHost);
+    /**
+     * Collect request context items from all resolved contributors.
+     * Creates a mutable UaiRequestContext, passes it through each
+     * contributor (mirroring the backend Contribute pattern), and
+     * returns the accumulated items.
+     *
+     * @returns Aggregated request context items from all contributors.
+     */
+    collect(): Promise<UaiRequestContextItem[]>;
+}
+
+/**
+ * API interface for request context contributors.
+ * Implement this to contribute context items to AI requests.
+ *
+ * Frontend counterpart of the backend IAIRuntimeContextContributor.
+ * While the backend contributors *process* request context items into
+ * runtime context, frontend contributors *produce* the request context
+ * items that get sent in the request.
+ *
+ * Mirrors the backend signature: `void Contribute(AIRuntimeContext context)`
+ */
+export declare interface UaiRequestContextContributorApi extends UmbApi {
+    /**
+     * Contribute context items to the request context.
+     * Called once per message send / prompt execution.
+     * Add items via `context.add(item)`. No-op to contribute nothing.
+     *
+     * @param context The mutable request context to contribute to.
+     * @param meta Optional manifest meta – passed from the manifest's `meta`
+     *             property so kind-based contributors can read configuration
+     *             without hardcoding values.
+     */
+    contribute(context: UaiRequestContext, meta?: Record<string, unknown>): Promise<void>;
 }
 
 /**
@@ -842,7 +1007,7 @@ export declare interface UaiRollbackModalData {
     /** The target version being compared (usually the current version). */
     toVersion: number;
     /** The list of property changes between the versions. */
-    changes: UaiVersionPropertyChange[];
+    changes: UaiVersionValueChange[];
 }
 
 /**
@@ -866,19 +1031,45 @@ export declare class UaiSelectedEvent extends Event {
 
 /**
  * Serialized representation of an entity for LLM context.
+ * Adapters decide the structure of the data field based on entity type.
  */
 export declare interface UaiSerializedEntity {
     entityType: string;
     unique: string;
     name: string;
-    contentType?: string;
     /** Parent unique when creating a new entity. Undefined for existing entities. */
     parentUnique?: string | null;
-    properties: UaiSerializedProperty[];
+    /**
+     * Free-form entity data as JSON object.
+     * Adapters decide the structure based on entity type.
+     *
+     * For CMS entities, typically contains:
+     * ```typescript
+     * {
+     *   contentType: "blogPost",
+     *   properties: [
+     *     { alias: "title", label: "Title", editorAlias: "Umbraco.TextBox", value: "Hello" }
+     *   ]
+     * }
+     * ```
+     *
+     * For third-party entities, can be any domain-appropriate structure:
+     * ```typescript
+     * {
+     *   sku: "12345",
+     *   price: { amount: 29.99, currency: "USD" },
+     *   variants: [{ color: "red", size: "large" }]
+     * }
+     * ```
+     */
+    data: Record<string, unknown>;
 }
 
 /**
  * Serialized property for LLM context.
+ * @deprecated Entity data is now stored in UaiSerializedEntity.data as free-form JSON.
+ * For CMS entities, properties are nested inside the data field.
+ * This interface is kept for reference only.
  */
 export declare interface UaiSerializedProperty {
     alias: string;
@@ -988,6 +1179,319 @@ export declare class UaiTagsInputElement extends UaiTagsInputElement_base {
 
 declare const UaiTagsInputElement_base: (new (...args: any[]) => UUIFormControlMixinElement<FormData | FormDataEntryValue>) & typeof UmbLitElement;
 
+/**
+ * Tool with permission state.
+ */
+export declare interface UaiToolPermission {
+    toolId: string;
+    state: UaiToolPermissionState;
+}
+
+/**
+ * Component for managing individual tool permission overrides.
+ * Displays inherited tools with "Deny" buttons and allows adding new tools with "Allow" permission.
+ *
+ * @fires change - Fires when permissions change
+ *
+ * @public
+ */
+export declare class UaiToolPermissionsOverrideElement extends UmbLitElement {
+    #private;
+    /**
+     * Map of tool ID to full tool data.
+     */
+    private _toolDataMap;
+    /**
+     * Inherited tool IDs from agent defaults.
+     */
+    inheritedToolIds: string[];
+    /**
+     * Tool IDs that are explicitly allowed (additive).
+     */
+    allowedToolIds: string[];
+    /**
+     * Tool IDs that are explicitly denied (subtractive).
+     */
+    deniedToolIds: string[];
+    /**
+     * Whether the component is in readonly mode.
+     */
+    readonly: boolean;
+    connectedCallback(): void;
+    updated(changedProperties: Map<string, unknown>): void;
+    /**
+     * Load full tool data for all tools.
+     */
+    private _loadToolData;
+    /**
+     * Computed list of all tools with their permission states.
+     */
+    private get _allTools();
+    /**
+     * Add a new allowed tool.
+     */
+    private _addAllowedTool;
+    /**
+     * Fetch available tools for the picker modal.
+     */
+    private _fetchAvailableTools;
+    /**
+     * Deny a tool (move to denied list).
+     */
+    private _denyTool;
+    /**
+     * Remove a tool from denied list (allow it again).
+     */
+    private _allowTool;
+    /**
+     * Remove an explicitly allowed tool.
+     */
+    private _removeAllowedTool;
+    /**
+     * Dispatch change event.
+     */
+    private _dispatchChangeEvent;
+    /**
+     * Render a tool permission item.
+     */
+    private _renderToolItem;
+    render(): TemplateResult<1>;
+    static styles: CSSResult[];
+}
+
+/**
+ * Permission state for a tool override.
+ */
+export declare type UaiToolPermissionState = "inherited" | "allowed" | "denied";
+
+/**
+ * Tool picker component that allows selecting one or more AI tools.
+ *
+ * @fires change - Fires when the selection changes (UmbChangeEvent).
+ *
+ * @example
+ * Multiple selection (default):
+ * ```html
+ * <uai-tool-picker
+ *   .value=${["tool-id-1", "tool-id-2"]}
+ *   @change=${(e) => console.log(e.target.value)}
+ * ></uai-tool-picker>
+ * ```
+ * @public
+ */
+export declare class UaiToolPickerElement extends UaiToolPickerElement_base {
+    #private;
+    /**
+     * Readonly mode - cannot add or remove.
+     */
+    readonly: boolean;
+    /**
+     * Optional frontend tools to include alongside server-fetched tools.
+     * These tools will be combined with the backend tools when displaying the picker.
+     */
+    frontendTools?: UaiFrontendToolData[];
+    /**
+     * The selected tool ID(s).
+     */
+    set value(val: string[] | undefined);
+    get value(): string[] | undefined;
+    private _selection;
+    private _items;
+    private _loading;
+    updated(changedProperties: Map<PropertyKey, unknown>): void;
+    render(): TemplateResult<1>;
+    static styles: CSSResult[];
+}
+
+declare const UaiToolPickerElement_base: HTMLElementConstructor<UmbFormControlMixinElement<string[] | undefined>> & typeof UmbLitElement;
+
+/**
+ * Repository for tool operations.
+ */
+export declare class UaiToolRepository extends UmbControllerBase {
+    #private;
+    constructor(host: UmbControllerHost);
+    /**
+     * Gets all registered tool scopes.
+     */
+    getToolScopes(): Promise<{
+        data?: Array<ToolScopeItemResponseModel>;
+        error?: unknown;
+    }>;
+    /**
+     * Gets all registered tools.
+     */
+    getTools(): Promise<{
+        data?: Array<ToolItemResponseModel>;
+        error?: unknown;
+    }>;
+}
+
+/**
+ * Tool scope with permission state.
+ */
+export declare interface UaiToolScopePermission {
+    scopeId: string;
+    state: UaiToolScopePermissionState;
+}
+
+export declare class UaiToolScopePermissionsElement extends UaiToolScopePermissionsElement_base {
+    #private;
+    /**
+     * Readonly mode - cannot toggle permissions.
+     */
+    readonly: boolean;
+    /**
+     * Hide scopes that have no tools.
+     */
+    hideEmptyScopes: boolean;
+    /**
+     * The selected tool scope IDs.
+     */
+    set value(val: string[] | undefined);
+    get value(): string[] | undefined;
+    private _selection;
+    private _groups;
+    private _loading;
+    private _toolCounts;
+    connectedCallback(): void;
+    updated(changedProperties: Map<string, unknown>): void;
+    render(): TemplateResult<1>;
+    static styles: CSSResult[];
+}
+
+declare const UaiToolScopePermissionsElement_base: HTMLElementConstructor<UmbFormControlMixinElement<string[] | undefined>> & typeof UmbLitElement;
+
+/**
+ * Component for managing tool scope permission overrides.
+ * Displays inherited scopes with "Deny" buttons and allows adding new scopes with "Allow" permission.
+ *
+ * @fires change - Fires when permissions change
+ *
+ * @public
+ */
+export declare class UaiToolScopePermissionsOverrideElement extends UmbLitElement {
+    #private;
+    /**
+     * Map of scope ID to full scope data.
+     */
+    private _scopeDataMap;
+    /**
+     * Tool counts by scope ID.
+     */
+    private _toolCounts;
+    /**
+     * Inherited scope IDs from agent defaults.
+     */
+    inheritedScopeIds: string[];
+    /**
+     * Scope IDs that are explicitly allowed (additive).
+     */
+    allowedScopeIds: string[];
+    /**
+     * Scope IDs that are explicitly denied (subtractive).
+     */
+    deniedScopeIds: string[];
+    /**
+     * Whether the component is in readonly mode.
+     */
+    readonly: boolean;
+    /**
+     * Hide scopes that have no tools.
+     */
+    hideEmptyScopes: boolean;
+    connectedCallback(): void;
+    updated(changedProperties: Map<string, unknown>): void;
+    /**
+     * Load full scope data for all scopes.
+     */
+    private _loadScopeData;
+    /**
+     * Load tool counts for all scopes.
+     */
+    private _loadToolCounts;
+    /**
+     * Computed list of all scopes with their permission states.
+     */
+    private get _allScopes();
+    /**
+     * Add a new allowed scope.
+     */
+    private _addAllowedScope;
+    /**
+     * Fetch available tool scopes for the picker modal.
+     */
+    private _fetchAvailableScopes;
+    /**
+     * Deny a scope (move to denied list).
+     */
+    private _denyScope;
+    /**
+     * Remove a scope from denied list (allow it again).
+     */
+    private _allowScope;
+    /**
+     * Remove an explicitly allowed scope.
+     */
+    private _removeAllowedScope;
+    /**
+     * Dispatch change event.
+     */
+    private _dispatchChangeEvent;
+    /**
+     * Render a scope permission item.
+     */
+    private _renderScopeItem;
+    render(): TemplateResult<1>;
+    static styles: CSSResult[];
+}
+
+/**
+ * Permission state for a tool scope override.
+ */
+export declare type UaiToolScopePermissionState = "inherited" | "allowed" | "denied";
+
+/**
+ * Tool scope picker component that allows selecting one or more tool scopes.
+ *
+ * @fires change - Fires when the selection changes (UmbChangeEvent).
+ *
+ * @example
+ * Multiple selection:
+ * ```html
+ * <uai-tool-scope-picker
+ *   .value=${["content-read", "media-write"]}
+ *   @change=${(e) => console.log(e.target.value)}
+ * ></uai-tool-scope-picker>
+ * ```
+ * @public
+ */
+export declare class UaiToolScopePickerElement extends UaiToolScopePickerElement_base {
+    #private;
+    /**
+     * Readonly mode - cannot add or remove.
+     */
+    readonly: boolean;
+    /**
+     * Hide scopes that have no tools.
+     */
+    hideEmptyScopes: boolean;
+    /**
+     * The selected tool scope ID(s).
+     */
+    set value(val: string[] | undefined);
+    get value(): string[] | undefined;
+    private _selection;
+    private _items;
+    private _loading;
+    private _toolCounts;
+    connectedCallback(): Promise<void>;
+    render(): TemplateResult<1>;
+    static styles: CSSResult[];
+}
+
+declare const UaiToolScopePickerElement_base: HTMLElementConstructor<UmbFormControlMixinElement<string[] | undefined>> & typeof UmbLitElement;
+
 /**
  * Unified repository for version history operations across all entity types.
  * Uses the unified versioning API endpoint instead of entity-specific endpoints.
@@ -1023,6 +1527,149 @@ export declare class UaiUnifiedVersionHistoryRepository {
     rollback(entityType: string, entityId: string, version: number): Promise<boolean>;
 }
 
+/**
+ * Configuration for the user group settings list component.
+ * @template TSettings - The type of settings managed for each user group
+ * @public
+ */
+export declare interface UaiUserGroupSettingsConfig<TSettings> {
+    /** Modal configuration for editing settings */
+    editorModal: {
+        /** Modal token to open for editing */
+        token: UmbModalToken<any, any>;
+        /** Factory to create modal data */
+        createData: (userGroupId: string, userGroupName: string, existingSettings?: TSettings) => any;
+        /** Extract settings from modal result */
+        extractValue: (modalResult: any) => TSettings;
+    };
+    /** Display configuration */
+    display: {
+        /** Render summary text/content for list item detail */
+        renderSummary: (settings: TSettings) => TemplateResult_2 | string;
+        /** Optional: Render tags/badges in list item */
+        renderTags?: (settings: TSettings) => TemplateResult_2;
+    };
+    /** Localization (all optional with sensible defaults) */
+    labels?: {
+        /** Box headline (default: "User Group Overrides") */
+        headline?: string;
+        /** Add button label (default: "Add User Group Override") */
+        addButton?: string;
+    };
+}
+
+/**
+ * Generic reusable component for managing user-group-specific settings for any feature.
+ * Handles list display, add/edit/remove workflows, and user group picker integration.
+ *
+ * @fires change - Fires when the value changes
+ *
+ * @example
+ * ```typescript
+ * const config: UaiUserGroupSettingsConfig<MySettings> = {
+ *   editorModal: {
+ *     token: MY_EDITOR_MODAL_TOKEN,
+ *     createData: (id, name, existing) => ({ userGroupId: id, userGroupName: name, settings: existing }),
+ *     extractValue: (result) => result.settings,
+ *   },
+ *   display: {
+ *     renderSummary: (settings) => `${settings.count} items configured`,
+ *     renderTags: (settings) => html`<uui-tag>Active</uui-tag>`,
+ *   },
+ *   labels: {
+ *     headline: 'Custom Settings',
+ *     addButton: 'Add Custom Setting',
+ *   },
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare class UaiUserGroupSettingsListElement<TSettings> extends UmbLitElement {
+    #private;
+    /**
+     * Map of user group IDs to their settings.
+     * Dictionary key is the user group ID (GUID as string).
+     */
+    value: Record<string, TSettings>;
+    /**
+     * Configuration for the component (modal, display, labels).
+     */
+    config: UaiUserGroupSettingsConfig<TSettings>;
+    /**
+     * Whether the component is in readonly mode.
+     */
+    readonly: boolean;
+    /**
+     * Internal state for resolved user group names.
+     */
+    private _userGroupNames;
+    /**
+     * Computed labels with defaults.
+     */
+    private get _labels();
+    /**
+     * Check if there are any user groups configured.
+     */
+    private get _hasUserGroups();
+    /**
+     * Get user group entries as array for rendering.
+     */
+    private get _userGroupEntries();
+    connectedCallback(): void;
+    /**
+     * Load user group names for all configured user groups.
+     */
+    private _loadUserGroupNames;
+    /**
+     * Get user group name by ID.
+     */
+    private _getUserGroupName;
+    /**
+     * Add a new user group override.
+     */
+    private _addUserGroup;
+    /**
+     * Edit an existing user group override.
+     */
+    private _editUserGroup;
+    /**
+     * Remove a user group override.
+     */
+    private _removeUserGroup;
+    /**
+     * Dispatch change event.
+     */
+    private _dispatchChangeEvent;
+    render(): TemplateResult_2<1>;
+    static styles: CSSResult[];
+}
+
+/**
+ * Request to change a value at a JSON path in the entity data.
+ * Changes are staged in the workspace - user must save to persist.
+ */
+export declare interface UaiValueChange {
+    /** JSON path to the value (e.g., "title", "price.amount", "inventory.quantity") */
+    path: string;
+    /** New value to set */
+    value: unknown;
+    /** Culture for variant content (undefined = invariant) */
+    culture?: string;
+    /** Segment for segmented content (undefined = no segment) */
+    segment?: string;
+}
+
+/**
+ * Result of a value change operation.
+ */
+export declare interface UaiValueChangeResult {
+    /** Whether the change was applied successfully */
+    success: boolean;
+    /** Human-readable error message if failed */
+    error?: string;
+}
+
 /**
  * Response model for version comparison.
  */
@@ -1031,8 +1678,8 @@ export declare interface UaiVersionComparisonResponse {
     fromVersion: number;
     /** The target version number. */
     toVersion: number;
-    /** The list of property changes. */
-    changes: UaiVersionPropertyChange[];
+    /** The list of value changes. */
+    changes: UaiVersionValueChange[];
 }
 
 /**
@@ -1073,11 +1720,11 @@ export declare const UaiVersionHistoryTypeMapper: {
 };
 
 /**
- * Represents a property change between two versions.
+ * Represents a value change between two versions.
  */
-export declare interface UaiVersionPropertyChange {
-    /** The name of the property that changed. */
-    propertyName: string;
+export declare interface UaiVersionValueChange {
+    /** The path of the value that changed. */
+    path: string;
     /** The old value (from the source version). */
     oldValue?: string | null;
     /** The new value (from the target version). */
@@ -1104,6 +1751,12 @@ export declare class UaiWorkspaceRegistryContext extends UmbControllerBase {
     /* Excluded from this release type: _unregister */
 }
 
+declare type ValueChangeModel = {
+    path: string;
+    oldValue?: string | null;
+    newValue?: string | null;
+};
+
 /**
  * Event emitted when workspace registration changes
  */