@umbraco-ai/core 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umbraco-ai/core",
-  "version": "1.1.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,11 +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 { TemplateResult as TemplateResult_2 } from '@umbraco-cms/backoffice/external/lit';
-import type { UmbApi } from '@umbraco-cms/backoffice/extension-api';
+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';
@@ -19,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.
  */
@@ -42,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 = {
@@ -84,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.
@@ -137,6 +173,12 @@ export declare type ToolScopeItemResponseModel = {
     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
@@ -150,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.
@@ -429,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;
 }
 
 /**
@@ -448,6 +503,7 @@ export declare interface UaiEditableModelFieldModel {
     defaultValue?: unknown;
     sortOrder: number;
     isRequired: boolean;
+    group?: string;
 }
 
 /**
@@ -540,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.
@@ -575,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>;
 }
 
 /**
@@ -618,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.
@@ -757,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;
@@ -847,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>;
 }
 
 /**
@@ -897,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[];
 }
 
 /**
@@ -921,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;
@@ -1205,6 +1341,10 @@ export declare class UaiToolScopePermissionsElement extends UaiToolScopePermissi
      * Readonly mode - cannot toggle permissions.
      */
     readonly: boolean;
+    /**
+     * Hide scopes that have no tools.
+     */
+    hideEmptyScopes: boolean;
     /**
      * The selected tool scope IDs.
      */
@@ -1213,7 +1353,9 @@ export declare class UaiToolScopePermissionsElement extends UaiToolScopePermissi
     private _selection;
     private _groups;
     private _loading;
+    private _toolCounts;
     connectedCallback(): void;
+    updated(changedProperties: Map<string, unknown>): void;
     render(): TemplateResult<1>;
     static styles: CSSResult[];
 }
@@ -1234,6 +1376,10 @@ export declare class UaiToolScopePermissionsOverrideElement extends UmbLitElemen
      * Map of scope ID to full scope data.
      */
     private _scopeDataMap;
+    /**
+     * Tool counts by scope ID.
+     */
+    private _toolCounts;
     /**
      * Inherited scope IDs from agent defaults.
      */
@@ -1250,12 +1396,20 @@ export declare class UaiToolScopePermissionsOverrideElement extends UmbLitElemen
      * 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.
      */
@@ -1318,6 +1472,10 @@ export declare class UaiToolScopePickerElement extends UaiToolScopePickerElement
      * Readonly mode - cannot add or remove.
      */
     readonly: boolean;
+    /**
+     * Hide scopes that have no tools.
+     */
+    hideEmptyScopes: boolean;
     /**
      * The selected tool scope ID(s).
      */
@@ -1326,6 +1484,8 @@ export declare class UaiToolScopePickerElement extends UaiToolScopePickerElement
     private _selection;
     private _items;
     private _loading;
+    private _toolCounts;
+    connectedCallback(): Promise<void>;
     render(): TemplateResult<1>;
     static styles: CSSResult[];
 }
@@ -1485,6 +1645,31 @@ export declare class UaiUserGroupSettingsListElement<TSettings> extends UmbLitEl
     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.
  */
@@ -1493,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[];
 }
 
 /**
@@ -1535,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). */
@@ -1566,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
  */