glirastes 0.3.2 → 0.5.0

package/dist/cjs/react/index.js

@@ -20,10 +20,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createApprovalDescriptionGenerator = exports.createToolResultHandler = exports.normalizeMentionSlug = exports.inferMentionPrefix = exports.serializeMentionsForSend = exports.parseMentionSegments = exports.stripContextBlocks = exports.sanitizeStoredMessages = exports.mergePipelineSteps = exports.DEFAULT_THEME_PRESET = exports.CHAT_THEME_PRESETS = exports.getThemeVars = exports.createRestSessionBridge = exports.SessionSwitcher = exports.AiTriggerButton = exports.RecordingBar = exports.VoiceInputButton = exports.MentionChipList = exports.MentionChip = exports.SuggestionBar = exports.SuggestionChip = exports.PipelineTimeline = exports.BulkApprovalCard = exports.ApprovalCard = exports.ChatWindow = exports.RichMentionInput = exports.MentionInput = exports.ChatInput = exports.MessageBubble = exports.MessageList = exports.FloatingChatUI = exports.AiChatPanel = exports.useKeyboardShortcut = exports.useDraggablePosition = exports.useDragResizePanel = exports.useDeepgramTranscription = exports.useSuggestions = exports.useMentions = exports.useApprovals = exports.useAiChat = exports.useChatContext = exports.AiChatProvider = void 0;
+exports.ApprovalCard = exports.ChatWindow = exports.RichMentionInput = exports.MentionInput = exports.ChatInput = exports.MessageBubble = exports.MessageList = exports.FloatingChatUI = exports.AiChatPanel = exports.AssistantWorkspace = exports.DE_ASSISTANT_SHORTCUT_LABELS = exports.DEFAULT_ASSISTANT_SHORTCUT_LABELS = exports.assistantShortcutList = exports.DE_ASSISTANT_SHELL_LABELS = exports.DEFAULT_ASSISTANT_SHELL_LABELS = exports.DEFAULT_ASSISTANT_SHELL_ICONS = exports.AssistantToggle = exports.AssistantShell = exports.DEFAULT_ASSISTANT_LAYOUT_LIMITS = exports.DEFAULT_ASSISTANT_LAYOUT_KEY = exports.clampAssistantWidth = exports.defaultAssistantLayout = exports.parseAssistantLayout = exports.useAssistantLayout = exports.AssistantLayoutProvider = exports.usePushToTalkHotkey = exports.DEFAULT_PUSH_TO_TALK_HOTKEY = exports.useChatShortcuts = exports.resolveChatShortcuts = exports.matchesShortcut = exports.formatShortcut = exports.DEFAULT_CHAT_SHORTCUTS = exports.useFloatingPanel = exports.useKeyboardShortcut = exports.useDraggablePosition = exports.useDragResizePanel = exports.createDeepgramSegmentParser = exports.DeepgramSttAdapter = exports.encodeWav = exports.RecordedSttAdapter = exports.SttSessionController = exports.useStt = exports.useDeepgramTranscription = exports.useSuggestions = exports.useMentions = exports.useApprovals = exports.useAiChat = exports.useChatContext = exports.deChatLocale = exports.AiChatProvider = void 0;
+exports.stripClarificationMarkers = exports.formatClarificationAnswer = exports.readClarificationPart = exports.findOpenClarification = exports.createApprovalDescriptionGenerator = exports.createToolResultHandler = exports.normalizeMentionSlug = exports.inferMentionPrefix = exports.serializeMentionsForSend = exports.parseMentionSegments = exports.stripContextBlocks = exports.createLocalSessionStore = exports.sanitizeStoredMessages = exports.readLatestPlan = exports.readActivitySteps = exports.mergePipelineSteps = exports.DEFAULT_THEME_PRESET = exports.CHAT_THEME_PRESETS = exports.getThemeVars = exports.createRestSessionBridge = exports.parseChatInteractions = exports.parseChatInteractionOverrides = exports.mergeChatInteractions = exports.chatText = exports.stripChatCommandMarkers = exports.parseChatCommandMessage = exports.formatChatCommandMessage = exports.useChatInteractionsData = exports.createChatInteractionRegistry = exports.entitiesFromData = exports.defineChatEntity = exports.defineChatCommand = exports.CommandArgumentsForm = exports.createUiToolCommandProvider = exports.createCompletionSearch = exports.defineToolResultRenderer = exports.createToolResultRendererRegistry = exports.ClarificationCard = exports.SessionSwitcher = exports.AiTriggerButton = exports.RecordingBar = exports.VoiceInputButton = exports.MentionChipList = exports.MentionChip = exports.SuggestionBar = exports.SuggestionChip = exports.PlanChecklist = exports.ActivityLog = exports.PipelineTimeline = exports.BulkApprovalCard = void 0;
 // Provider
 var ai_chat_provider_js_1 = require("./provider/ai-chat-provider.js");
 Object.defineProperty(exports, "AiChatProvider", { enumerable: true, get: function () { return ai_chat_provider_js_1.AiChatProvider; } });
+var locale_de_js_1 = require("./locale-de.js");
+Object.defineProperty(exports, "deChatLocale", { enumerable: true, get: function () { return locale_de_js_1.deChatLocale; } });
 // Context (for advanced use cases)
 var chat_context_js_1 = require("./provider/chat-context.js");
 Object.defineProperty(exports, "useChatContext", { enumerable: true, get: function () { return chat_context_js_1.useChatContext; } });
@@ -38,13 +41,54 @@ var use_suggestions_js_1 = require("./hooks/use-suggestions.js");
 Object.defineProperty(exports, "useSuggestions", { enumerable: true, get: function () { return use_suggestions_js_1.useSuggestions; } });
 var use_deepgram_transcription_js_1 = require("./hooks/use-deepgram-transcription.js");
 Object.defineProperty(exports, "useDeepgramTranscription", { enumerable: true, get: function () { return use_deepgram_transcription_js_1.useDeepgramTranscription; } });
+var use_stt_js_1 = require("./stt/use-stt.js");
+Object.defineProperty(exports, "useStt", { enumerable: true, get: function () { return use_stt_js_1.useStt; } });
+var controller_js_1 = require("./stt/controller.js");
+Object.defineProperty(exports, "SttSessionController", { enumerable: true, get: function () { return controller_js_1.SttSessionController; } });
+var recorded_js_1 = require("./stt/recorded.js");
+Object.defineProperty(exports, "RecordedSttAdapter", { enumerable: true, get: function () { return recorded_js_1.RecordedSttAdapter; } });
+Object.defineProperty(exports, "encodeWav", { enumerable: true, get: function () { return recorded_js_1.encodeWav; } });
+var deepgram_js_1 = require("./stt/deepgram.js");
+Object.defineProperty(exports, "DeepgramSttAdapter", { enumerable: true, get: function () { return deepgram_js_1.DeepgramSttAdapter; } });
+Object.defineProperty(exports, "createDeepgramSegmentParser", { enumerable: true, get: function () { return deepgram_js_1.createDeepgramSegmentParser; } });
 var use_drag_resize_panel_js_1 = require("./hooks/use-drag-resize-panel.js");
 Object.defineProperty(exports, "useDragResizePanel", { enumerable: true, get: function () { return use_drag_resize_panel_js_1.useDragResizePanel; } });
 var use_draggable_position_js_1 = require("./hooks/use-draggable-position.js");
 Object.defineProperty(exports, "useDraggablePosition", { enumerable: true, get: function () { return use_draggable_position_js_1.useDraggablePosition; } });
 var use_keyboard_shortcut_js_1 = require("./hooks/use-keyboard-shortcut.js");
 Object.defineProperty(exports, "useKeyboardShortcut", { enumerable: true, get: function () { return use_keyboard_shortcut_js_1.useKeyboardShortcut; } });
+var use_floating_panel_js_1 = require("./hooks/use-floating-panel.js");
+Object.defineProperty(exports, "useFloatingPanel", { enumerable: true, get: function () { return use_floating_panel_js_1.useFloatingPanel; } });
+var use_chat_shortcuts_js_1 = require("./hooks/use-chat-shortcuts.js");
+Object.defineProperty(exports, "DEFAULT_CHAT_SHORTCUTS", { enumerable: true, get: function () { return use_chat_shortcuts_js_1.DEFAULT_CHAT_SHORTCUTS; } });
+Object.defineProperty(exports, "formatShortcut", { enumerable: true, get: function () { return use_chat_shortcuts_js_1.formatShortcut; } });
+Object.defineProperty(exports, "matchesShortcut", { enumerable: true, get: function () { return use_chat_shortcuts_js_1.matchesShortcut; } });
+Object.defineProperty(exports, "resolveChatShortcuts", { enumerable: true, get: function () { return use_chat_shortcuts_js_1.resolveChatShortcuts; } });
+Object.defineProperty(exports, "useChatShortcuts", { enumerable: true, get: function () { return use_chat_shortcuts_js_1.useChatShortcuts; } });
+var use_push_to_talk_hotkey_js_1 = require("./hooks/use-push-to-talk-hotkey.js");
+Object.defineProperty(exports, "DEFAULT_PUSH_TO_TALK_HOTKEY", { enumerable: true, get: function () { return use_push_to_talk_hotkey_js_1.DEFAULT_PUSH_TO_TALK_HOTKEY; } });
+Object.defineProperty(exports, "usePushToTalkHotkey", { enumerable: true, get: function () { return use_push_to_talk_hotkey_js_1.usePushToTalkHotkey; } });
 // Components
+var assistant_layout_js_1 = require("./assistant/assistant-layout.js");
+Object.defineProperty(exports, "AssistantLayoutProvider", { enumerable: true, get: function () { return assistant_layout_js_1.AssistantLayoutProvider; } });
+Object.defineProperty(exports, "useAssistantLayout", { enumerable: true, get: function () { return assistant_layout_js_1.useAssistantLayout; } });
+Object.defineProperty(exports, "parseAssistantLayout", { enumerable: true, get: function () { return assistant_layout_js_1.parseAssistantLayout; } });
+Object.defineProperty(exports, "defaultAssistantLayout", { enumerable: true, get: function () { return assistant_layout_js_1.defaultAssistantLayout; } });
+Object.defineProperty(exports, "clampAssistantWidth", { enumerable: true, get: function () { return assistant_layout_js_1.clampAssistantWidth; } });
+Object.defineProperty(exports, "DEFAULT_ASSISTANT_LAYOUT_KEY", { enumerable: true, get: function () { return assistant_layout_js_1.DEFAULT_ASSISTANT_LAYOUT_KEY; } });
+Object.defineProperty(exports, "DEFAULT_ASSISTANT_LAYOUT_LIMITS", { enumerable: true, get: function () { return assistant_layout_js_1.DEFAULT_ASSISTANT_LAYOUT_LIMITS; } });
+var assistant_shell_js_1 = require("./assistant/assistant-shell.js");
+Object.defineProperty(exports, "AssistantShell", { enumerable: true, get: function () { return assistant_shell_js_1.AssistantShell; } });
+Object.defineProperty(exports, "AssistantToggle", { enumerable: true, get: function () { return assistant_shell_js_1.AssistantToggle; } });
+Object.defineProperty(exports, "DEFAULT_ASSISTANT_SHELL_ICONS", { enumerable: true, get: function () { return assistant_shell_js_1.DEFAULT_ASSISTANT_SHELL_ICONS; } });
+Object.defineProperty(exports, "DEFAULT_ASSISTANT_SHELL_LABELS", { enumerable: true, get: function () { return assistant_shell_js_1.DEFAULT_ASSISTANT_SHELL_LABELS; } });
+Object.defineProperty(exports, "DE_ASSISTANT_SHELL_LABELS", { enumerable: true, get: function () { return assistant_shell_js_1.DE_ASSISTANT_SHELL_LABELS; } });
+var assistant_shortcut_list_js_1 = require("./assistant/assistant-shortcut-list.js");
+Object.defineProperty(exports, "assistantShortcutList", { enumerable: true, get: function () { return assistant_shortcut_list_js_1.assistantShortcutList; } });
+Object.defineProperty(exports, "DEFAULT_ASSISTANT_SHORTCUT_LABELS", { enumerable: true, get: function () { return assistant_shortcut_list_js_1.DEFAULT_ASSISTANT_SHORTCUT_LABELS; } });
+Object.defineProperty(exports, "DE_ASSISTANT_SHORTCUT_LABELS", { enumerable: true, get: function () { return assistant_shortcut_list_js_1.DE_ASSISTANT_SHORTCUT_LABELS; } });
+var assistant_workspace_js_1 = require("./assistant/assistant-workspace.js");
+Object.defineProperty(exports, "AssistantWorkspace", { enumerable: true, get: function () { return assistant_workspace_js_1.AssistantWorkspace; } });
 var ai_chat_panel_js_1 = require("./components/ai-chat-panel.js");
 Object.defineProperty(exports, "AiChatPanel", { enumerable: true, get: function () { return ai_chat_panel_js_1.AiChatPanel; } });
 var floating_chat_ui_js_1 = require("./components/floating-chat-ui.js");
@@ -67,6 +111,10 @@ var bulk_approval_card_js_1 = require("./components/bulk-approval-card.js");
 Object.defineProperty(exports, "BulkApprovalCard", { enumerable: true, get: function () { return bulk_approval_card_js_1.BulkApprovalCard; } });
 var pipeline_timeline_js_1 = require("./components/pipeline-timeline.js");
 Object.defineProperty(exports, "PipelineTimeline", { enumerable: true, get: function () { return pipeline_timeline_js_1.PipelineTimeline; } });
+var activity_log_js_1 = require("./components/activity-log.js");
+Object.defineProperty(exports, "ActivityLog", { enumerable: true, get: function () { return activity_log_js_1.ActivityLog; } });
+var plan_checklist_js_1 = require("./components/plan-checklist.js");
+Object.defineProperty(exports, "PlanChecklist", { enumerable: true, get: function () { return plan_checklist_js_1.PlanChecklist; } });
 var suggestion_chip_js_1 = require("./components/suggestion-chip.js");
 Object.defineProperty(exports, "SuggestionChip", { enumerable: true, get: function () { return suggestion_chip_js_1.SuggestionChip; } });
 var suggestion_bar_js_1 = require("./components/suggestion-bar.js");
@@ -82,6 +130,37 @@ var ai_trigger_button_js_1 = require("./components/ai-trigger-button.js");
 Object.defineProperty(exports, "AiTriggerButton", { enumerable: true, get: function () { return ai_trigger_button_js_1.AiTriggerButton; } });
 var session_switcher_js_1 = require("./components/session-switcher.js");
 Object.defineProperty(exports, "SessionSwitcher", { enumerable: true, get: function () { return session_switcher_js_1.SessionSwitcher; } });
+var clarification_card_js_1 = require("./components/clarification-card.js");
+Object.defineProperty(exports, "ClarificationCard", { enumerable: true, get: function () { return clarification_card_js_1.ClarificationCard; } });
+// Tool result renderers
+var registry_js_1 = require("./tool-renderers/registry.js");
+Object.defineProperty(exports, "createToolResultRendererRegistry", { enumerable: true, get: function () { return registry_js_1.createToolResultRendererRegistry; } });
+Object.defineProperty(exports, "defineToolResultRenderer", { enumerable: true, get: function () { return registry_js_1.defineToolResultRenderer; } });
+// Completion providers
+var completion_search_js_1 = require("./completions/completion-search.js");
+Object.defineProperty(exports, "createCompletionSearch", { enumerable: true, get: function () { return completion_search_js_1.createCompletionSearch; } });
+var ui_tool_command_provider_js_1 = require("./completions/ui-tool-command-provider.js");
+Object.defineProperty(exports, "createUiToolCommandProvider", { enumerable: true, get: function () { return ui_tool_command_provider_js_1.createUiToolCommandProvider; } });
+var command_arguments_form_js_1 = require("./components/command-arguments-form.js");
+Object.defineProperty(exports, "CommandArgumentsForm", { enumerable: true, get: function () { return command_arguments_form_js_1.CommandArgumentsForm; } });
+// Declarative chat interactions: `@` entities and `/` commands
+var definitions_js_1 = require("./interactions/definitions.js");
+Object.defineProperty(exports, "defineChatCommand", { enumerable: true, get: function () { return definitions_js_1.defineChatCommand; } });
+Object.defineProperty(exports, "defineChatEntity", { enumerable: true, get: function () { return definitions_js_1.defineChatEntity; } });
+Object.defineProperty(exports, "entitiesFromData", { enumerable: true, get: function () { return definitions_js_1.entitiesFromData; } });
+var registry_js_2 = require("./interactions/registry.js");
+Object.defineProperty(exports, "createChatInteractionRegistry", { enumerable: true, get: function () { return registry_js_2.createChatInteractionRegistry; } });
+var use_chat_interactions_data_js_1 = require("./interactions/use-chat-interactions-data.js");
+Object.defineProperty(exports, "useChatInteractionsData", { enumerable: true, get: function () { return use_chat_interactions_data_js_1.useChatInteractionsData; } });
+var chat_command_js_1 = require("../contracts/chat-command.js");
+Object.defineProperty(exports, "formatChatCommandMessage", { enumerable: true, get: function () { return chat_command_js_1.formatChatCommandMessage; } });
+Object.defineProperty(exports, "parseChatCommandMessage", { enumerable: true, get: function () { return chat_command_js_1.parseChatCommandMessage; } });
+Object.defineProperty(exports, "stripChatCommandMarkers", { enumerable: true, get: function () { return chat_command_js_1.stripChatCommandMarkers; } });
+var chat_interactions_js_1 = require("../contracts/chat-interactions.js");
+Object.defineProperty(exports, "chatText", { enumerable: true, get: function () { return chat_interactions_js_1.chatText; } });
+Object.defineProperty(exports, "mergeChatInteractions", { enumerable: true, get: function () { return chat_interactions_js_1.mergeChatInteractions; } });
+Object.defineProperty(exports, "parseChatInteractionOverrides", { enumerable: true, get: function () { return chat_interactions_js_1.parseChatInteractionOverrides; } });
+Object.defineProperty(exports, "parseChatInteractions", { enumerable: true, get: function () { return chat_interactions_js_1.parseChatInteractions; } });
 // Bridges
 var rest_session_bridge_js_1 = require("./bridges/rest-session-bridge.js");
 Object.defineProperty(exports, "createRestSessionBridge", { enumerable: true, get: function () { return rest_session_bridge_js_1.createRestSessionBridge; } });
@@ -93,8 +172,13 @@ Object.defineProperty(exports, "DEFAULT_THEME_PRESET", { enumerable: true, get:
 // Utilities
 var merge_pipeline_steps_js_1 = require("./utils/merge-pipeline-steps.js");
 Object.defineProperty(exports, "mergePipelineSteps", { enumerable: true, get: function () { return merge_pipeline_steps_js_1.mergePipelineSteps; } });
+var activity_js_1 = require("./utils/activity.js");
+Object.defineProperty(exports, "readActivitySteps", { enumerable: true, get: function () { return activity_js_1.readActivitySteps; } });
+Object.defineProperty(exports, "readLatestPlan", { enumerable: true, get: function () { return activity_js_1.readLatestPlan; } });
 var sanitize_stored_messages_js_1 = require("./utils/sanitize-stored-messages.js");
 Object.defineProperty(exports, "sanitizeStoredMessages", { enumerable: true, get: function () { return sanitize_stored_messages_js_1.sanitizeStoredMessages; } });
+var local_session_store_js_1 = require("./utils/local-session-store.js");
+Object.defineProperty(exports, "createLocalSessionStore", { enumerable: true, get: function () { return local_session_store_js_1.createLocalSessionStore; } });
 var mention_markup_js_1 = require("./utils/mention-markup.js");
 Object.defineProperty(exports, "stripContextBlocks", { enumerable: true, get: function () { return mention_markup_js_1.stripContextBlocks; } });
 Object.defineProperty(exports, "parseMentionSegments", { enumerable: true, get: function () { return mention_markup_js_1.parseMentionSegments; } });
@@ -105,6 +189,12 @@ var create_tool_result_handler_js_1 = require("./utils/create-tool-result-handle
 Object.defineProperty(exports, "createToolResultHandler", { enumerable: true, get: function () { return create_tool_result_handler_js_1.createToolResultHandler; } });
 var create_approval_description_js_1 = require("./utils/create-approval-description.js");
 Object.defineProperty(exports, "createApprovalDescriptionGenerator", { enumerable: true, get: function () { return create_approval_description_js_1.createApprovalDescriptionGenerator; } });
+var clarification_js_1 = require("./utils/clarification.js");
+Object.defineProperty(exports, "findOpenClarification", { enumerable: true, get: function () { return clarification_js_1.findOpenClarification; } });
+Object.defineProperty(exports, "readClarificationPart", { enumerable: true, get: function () { return clarification_js_1.readClarificationPart; } });
+var clarification_js_2 = require("../contracts/clarification.js");
+Object.defineProperty(exports, "formatClarificationAnswer", { enumerable: true, get: function () { return clarification_js_2.formatClarificationAnswer; } });
+Object.defineProperty(exports, "stripClarificationMarkers", { enumerable: true, get: function () { return clarification_js_2.stripClarificationMarkers; } });
 // UI action bus + hooks (client action dispatch)
 __exportStar(require("./ui.js"), exports);
 // Pre-styled template (Tailwind wrappers around the unstyled components)

package/dist/cjs/react/interactions/definitions.d.ts

@@ -0,0 +1,67 @@
+import { type ChatCommandRun, type ChatInteractionArg, type ChatInteractionsData, type ChatLocaleCode, type ChatText, type ChatToolRun } from '../../contracts/chat-interactions.js';
+import type { CompletionPermissionContext } from '../types.js';
+/** One search hit of an entity: the app's id and what the user sees. */
+export interface ChatEntityItem {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+}
+/** Framework-neutral preview of an entity in the `@` list. */
+export interface ChatEntityCard {
+    readonly title: string;
+    readonly subtitle?: string;
+}
+export interface ChatEntitySearchContext {
+    /** Aborted when a newer search starts; pass it to `fetch`. */
+    readonly signal: AbortSignal;
+    readonly limit: number;
+    readonly locale: ChatLocaleCode;
+    /** What the UI knows about the user; it only hides, the app authorizes. */
+    readonly context: CompletionPermissionContext;
+}
+export interface ChatEntityAction {
+    readonly id: string;
+    readonly label: ChatText;
+    /** Argument that receives the entity id (dotted path, e.g. `params.taskId`). */
+    readonly entityArg: string;
+    readonly args?: ReadonlyArray<ChatInteractionArg>;
+    readonly run: ChatToolRun;
+}
+/**
+ * An `@` entity: `search` runs in the browser with the user's session
+ * against the app's own endpoints; nothing goes to the Glirastes Platform.
+ */
+export interface ChatEntityDefinition {
+    readonly type: string;
+    readonly label: ChatText;
+    readonly icon?: string;
+    search(query: string, context: ChatEntitySearchContext): Promise<ReadonlyArray<ChatEntityItem>> | ReadonlyArray<ChatEntityItem>;
+    /** Looks one entity up by id, e.g. to pre-fill the composer (`mentionEntity`). */
+    resolve?(id: string): Promise<ChatEntityItem | undefined> | ChatEntityItem | undefined;
+    card?(item: ChatEntityItem): ChatEntityCard;
+    readonly actions?: ReadonlyArray<ChatEntityAction>;
+}
+/** A `/` command; `run` decides whether the model is involved (`prompt`) or not (`tool`, `ui`). */
+export interface ChatCommandDefinition {
+    readonly id: string;
+    readonly label: ChatText;
+    readonly description?: ChatText;
+    readonly keywords?: ReadonlyArray<string>;
+    readonly icon?: string;
+    readonly args?: ReadonlyArray<ChatInteractionArg>;
+    readonly run: ChatCommandRun;
+}
+/** Validates and freezes an entity definition; throws on anything the chat could not use safely. */
+export declare function defineChatEntity<T extends ChatEntityDefinition>(definition: T): T;
+/** Validates and freezes a command definition. */
+export declare function defineChatCommand<T extends ChatCommandDefinition>(definition: T): T;
+/** Keeps only well-formed hits: a non-empty id and label, bounded text. */
+export declare function toChatEntityItem(value: unknown): ChatEntityItem | undefined;
+export interface DerivedEntityOptions {
+    /** Defaults to the global `fetch`; the request carries the user's cookies (same origin). */
+    fetch?: typeof globalThis.fetch;
+    /** Prefix for the app's endpoints, e.g. a separate API origin. Default: same origin. */
+    baseUrl?: string;
+}
+/** Entity definitions for derived data: searches call the app endpoint with the user's session. */
+export declare function entitiesFromData(data: ChatInteractionsData, options?: DerivedEntityOptions): ChatEntityDefinition[];

package/dist/cjs/react/interactions/definitions.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineChatEntity = defineChatEntity;
+exports.defineChatCommand = defineChatCommand;
+exports.toChatEntityItem = toChatEntityItem;
+exports.entitiesFromData = entitiesFromData;
+const chat_interactions_js_1 = require("../../contracts/chat-interactions.js");
+const MAX_ITEM_TEXT = 200;
+/** Validates and freezes an entity definition; throws on anything the chat could not use safely. */
+function defineChatEntity(definition) {
+    if (typeof definition.search !== 'function')
+        throw new Error(`Chat entity ${String(definition.type)} needs a search function`);
+    const { search: _search, resolve: _resolve, card: _card, ...data } = definition;
+    (0, chat_interactions_js_1.parseChatInteractions)({ schemaVersion: 1, entities: [data], commands: [] });
+    return Object.freeze(definition);
+}
+/** Validates and freezes a command definition. */
+function defineChatCommand(definition) {
+    (0, chat_interactions_js_1.parseChatInteractions)({ schemaVersion: 1, entities: [], commands: [definition] });
+    return Object.freeze(definition);
+}
+/** Keeps only well-formed hits: a non-empty id and label, bounded text. */
+function toChatEntityItem(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const item = value;
+    const id = typeof item.id === 'number' && Number.isFinite(item.id) ? String(item.id) : item.id;
+    if (typeof id !== 'string' || !id || id.length > MAX_ITEM_TEXT || /[:}]/.test(id))
+        return undefined;
+    if (typeof item.label !== 'string' || !item.label.trim())
+        return undefined;
+    const description = typeof item.description === 'string' && item.description.trim()
+        ? item.description.trim().slice(0, MAX_ITEM_TEXT)
+        : undefined;
+    return { id, label: item.label.trim().slice(0, MAX_ITEM_TEXT), ...(description ? { description } : {}) };
+}
+function at(value, path) {
+    let current = value;
+    for (const key of path) {
+        if (typeof current !== 'object' || current === null || Array.isArray(current))
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/** Entity definitions for derived data: searches call the app endpoint with the user's session. */
+function entitiesFromData(data, options = {}) {
+    return data.entities.map((entity) => {
+        const search = entity.search;
+        return {
+            type: entity.type,
+            label: entity.label,
+            ...(entity.icon ? { icon: entity.icon } : {}),
+            ...(entity.actions ? { actions: entity.actions } : {}),
+            async search(query, context) {
+                if (!search)
+                    return [];
+                const params = new URLSearchParams({ [search.queryParam]: query });
+                if (search.limitParam)
+                    params.set(search.limitParam, String(context.limit));
+                const fetcher = options.fetch ?? globalThis.fetch;
+                const response = await fetcher(`${options.baseUrl ?? ''}${search.path}?${params}`, {
+                    signal: context.signal,
+                    credentials: options.baseUrl ? 'include' : 'same-origin',
+                    headers: { accept: 'application/json' },
+                });
+                if (!response.ok)
+                    return [];
+                const list = at(await response.json(), search.itemsPath);
+                if (!Array.isArray(list))
+                    return [];
+                return list
+                    .map((item) => toChatEntityItem({
+                    id: at(item, [search.idField]),
+                    label: at(item, [search.labelField]),
+                    ...(search.descriptionField ? { description: at(item, [search.descriptionField]) } : {}),
+                }))
+                    .filter((item) => item !== undefined)
+                    .slice(0, context.limit);
+            },
+        };
+    });
+}

package/dist/cjs/react/interactions/registry.d.ts

@@ -0,0 +1,74 @@
+import { type ChatInteractionArg, type ChatInteractionsData, type ChatLocaleCode } from '../../contracts/chat-interactions.js';
+import type { ChatCompletionProvider, CompletionPermissionContext, MentionData } from '../types.js';
+import { type ChatCommandDefinition, type ChatEntityDefinition, type ChatEntityItem, type DerivedEntityOptions } from './definitions.js';
+export interface ChatInteractionsConfig extends DerivedEntityOptions {
+    /** Derived interactions: `useChatInteractionsData(endpoint)` or the generated module's `chatInteractions`. */
+    readonly data?: ChatInteractionsData;
+    /** App-defined entities; one with the type of a derived entity replaces it. */
+    readonly entities?: ReadonlyArray<ChatEntityDefinition>;
+    /** App-defined commands; one with the id of a derived command replaces it. */
+    readonly commands?: ReadonlyArray<ChatCommandDefinition>;
+    /** Language of labels and default texts. Default `en`. */
+    readonly locale?: ChatLocaleCode;
+    /** Passed to entity searches; set by the provider from `completionContext`. */
+    readonly context?: CompletionPermissionContext;
+}
+/** A command or entity action that still needs arguments from the user. */
+export interface PendingChatCommand {
+    readonly commandId: string;
+    readonly tool: string;
+    /** The visible name, e.g. `Assign` or `Filter Tasks`. */
+    readonly label: string;
+    readonly fixedArgs: Readonly<Record<string, unknown>>;
+    /** Arguments the form asks for. */
+    readonly args: ReadonlyArray<ChatInteractionArg>;
+    /** Values already known (entity ids, picked mentions), by argument name. */
+    readonly values: Readonly<Record<string, string>>;
+    /** Display labels for entity values, by argument name. */
+    readonly valueLabels: Readonly<Record<string, string>>;
+    /** Set when the last attempt was refused, e.g. values too long. */
+    readonly error?: 'invalid';
+}
+export type ChatSendPlan = 
+/** A direct command message, ready for the transport. */
+{
+    readonly status: 'send';
+    readonly text: string;
+}
+/** A prompt command: the text the model receives instead of the command token. */
+ | {
+    readonly status: 'prompt';
+    readonly text: string;
+}
+/** The command needs arguments first; show `PendingChatCommand` as a form. */
+ | {
+    readonly status: 'needs-args';
+    readonly request: PendingChatCommand;
+};
+export interface ChatInteractionRegistry {
+    readonly locale: ChatLocaleCode;
+    /** `/` commands and `@` entities for `createCompletionSearch`. */
+    readonly providers: ReadonlyArray<ChatCompletionProvider>;
+    command(id: string): ChatCommandDefinition | undefined;
+    entity(type: string): ChatEntityDefinition | undefined;
+    /** Searches one entity type, e.g. for an argument field; failures yield no hits. */
+    searchEntity(type: string, query: string, signal: AbortSignal): Promise<ChatEntityItem[]>;
+    /**
+     * How to send a composed message: `undefined` for a normal model message
+     * (no command, several commands, or a command mixed with free text).
+     */
+    planMessage(text: string, mentions: ReadonlyArray<MentionData>): ChatSendPlan | undefined;
+    /** An entity action picked from the `@` list. */
+    planAction(entity: {
+        type: string;
+        id: string;
+        label: string;
+    }, actionId: string): ChatSendPlan | undefined;
+    /** Sends a pending command with the values (and entity labels) from its form, or asks again. */
+    completeCommand(pending: PendingChatCommand, values: Readonly<Record<string, string>>, valueLabels?: Readonly<Record<string, string>>): ChatSendPlan;
+}
+/**
+ * Turns declarative entities and commands into completion providers and
+ * send plans. App definitions replace derived ones of the same id or type.
+ */
+export declare function createChatInteractionRegistry(config: ChatInteractionsConfig): ChatInteractionRegistry;

package/dist/cjs/react/interactions/registry.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChatInteractionRegistry = createChatInteractionRegistry;
+const chat_command_js_1 = require("../../contracts/chat-command.js");
+const chat_interactions_js_1 = require("../../contracts/chat-interactions.js");
+const mention_markup_js_1 = require("../utils/mention-markup.js");
+const definitions_js_1 = require("./definitions.js");
+function fold(value) {
+    return value.normalize('NFKD').replace(/\p{M}+/gu, '').toLowerCase().trim();
+}
+function rank(label, command, needle) {
+    if (!needle)
+        return 0;
+    const folded = fold(label);
+    if (folded.startsWith(needle))
+        return 0;
+    if (folded.split(/[^\p{L}\p{N}]+/u).some((word) => word.startsWith(needle)))
+        return 1;
+    if (folded.includes(needle) || fold((0, mention_markup_js_1.normalizeMentionSlug)(label)).includes(needle))
+        return 2;
+    if (fold(command.id).includes(needle))
+        return 3;
+    if ((command.keywords ?? []).some((keyword) => fold(keyword).includes(needle)))
+        return 4;
+    return undefined;
+}
+function setPath(target, path, value) {
+    const segments = path.split('.');
+    let current = target;
+    for (const segment of segments.slice(0, -1)) {
+        const next = current[segment];
+        if (typeof next !== 'object' || next === null || Array.isArray(next))
+            current[segment] = {};
+        current = current[segment];
+    }
+    current[segments.at(-1)] = value;
+}
+function tokenOf(mention) {
+    return typeof mention.prefix === 'string' && typeof mention.slug === 'string'
+        ? `${mention.prefix}${mention.slug}`
+        : undefined;
+}
+function withoutToken(text, token) {
+    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`(^|\\s)${escaped}(?=\\s|$)`);
+    return pattern.test(text) ? { text: text.replace(pattern, '$1'), found: true } : { text, found: false };
+}
+/**
+ * Turns declarative entities and commands into completion providers and
+ * send plans. App definitions replace derived ones of the same id or type.
+ */
+function createChatInteractionRegistry(config) {
+    const locale = config.locale ?? 'en';
+    const entities = new Map();
+    for (const entity of config.data ? (0, definitions_js_1.entitiesFromData)(config.data, config) : [])
+        entities.set(entity.type, entity);
+    for (const entity of config.entities ?? [])
+        entities.set(entity.type, entity);
+    const commands = new Map();
+    for (const command of config.data?.commands ?? [])
+        commands.set(command.id, command);
+    for (const command of config.commands ?? [])
+        commands.set(command.id, command);
+    const commandProvider = {
+        id: 'chat-commands',
+        trigger: '/',
+        search({ query, limit }) {
+            const needle = fold(query);
+            return [...commands.values()]
+                .map((command) => {
+                const label = (0, chat_interactions_js_1.chatText)(command.label, locale);
+                return { command, label, rank: rank(label, command, needle) };
+            })
+                .filter((entry) => entry.rank !== undefined)
+                .sort((left, right) => left.rank - right.rank || left.label.localeCompare(right.label))
+                .slice(0, limit)
+                .map(({ command, label }) => {
+                const description = (0, chat_interactions_js_1.chatText)(command.description, locale);
+                const run = command.run;
+                return {
+                    id: command.id,
+                    type: 'command',
+                    label,
+                    ...(description ? { description } : {}),
+                    // A command mixed with free text goes to the model with its tool reference.
+                    ...(run.kind !== 'prompt' ? { definitionId: run.tool, ...(run.args ? { args: run.args } : {}) } : {}),
+                };
+            });
+        },
+    };
+    const entityProvider = {
+        id: 'chat-entities',
+        trigger: '@',
+        async search({ query, signal, limit, context }) {
+            const settled = await Promise.allSettled([...entities.values()].map(async (entity) => {
+                const items = await entity.search(query, { signal, limit, locale, context });
+                return (Array.isArray(items) ? items : []).slice(0, limit).map((item) => {
+                    const card = entity.card?.(item);
+                    const description = card?.subtitle ?? item.description;
+                    return {
+                        id: item.id,
+                        type: entity.type,
+                        label: card?.title ?? item.label,
+                        ...(description ? { description } : {}),
+                        ...(entity.actions?.length
+                            ? { actions: entity.actions.map((action) => ({ id: action.id, label: (0, chat_interactions_js_1.chatText)(action.label, locale) })) }
+                            : {}),
+                    };
+                });
+            }));
+            // One entity type must not fill the whole per-provider cap: take one hit per type in turn.
+            const lists = settled.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));
+            const interleaved = [];
+            for (let index = 0; index < limit; index += 1) {
+                for (const list of lists) {
+                    const item = list[index];
+                    if (item)
+                        interleaved.push(item);
+                }
+            }
+            return interleaved;
+        },
+    };
+    const complete = (pending, values, labels = {}) => {
+        const valueLabels = { ...pending.valueLabels, ...labels };
+        const merged = { ...pending.values };
+        for (const [name, value] of Object.entries(values)) {
+            if (typeof value === 'string' && value.trim())
+                merged[name] = value.trim();
+            else
+                delete merged[name];
+        }
+        const missing = pending.args.some((arg) => arg.required && !merged[arg.name]);
+        if (missing)
+            return { status: 'needs-args', request: { ...pending, values: merged, valueLabels } };
+        const args = structuredClone({ ...pending.fixedArgs });
+        for (const [name, value] of Object.entries(merged)) {
+            if ((0, chat_interactions_js_1.isChatArgumentPath)(name))
+                setPath(args, name, value);
+        }
+        if ((0, chat_command_js_1.serializeChatCommandArgs)(args) === undefined) {
+            return { status: 'needs-args', request: { ...pending, values: merged, valueLabels, error: 'invalid' } };
+        }
+        const shown = pending.args
+            .filter((arg) => merged[arg.name])
+            .map((arg) => (arg.entity ? `@${valueLabels[arg.name] || merged[arg.name]}` : merged[arg.name]));
+        const entityLabels = Object.entries(valueLabels)
+            .filter(([name]) => !pending.args.some((arg) => arg.name === name))
+            .map(([, label]) => `@${label}`);
+        return {
+            status: 'send',
+            text: (0, chat_command_js_1.formatChatCommandMessage)({
+                commandId: pending.commandId,
+                tool: pending.tool,
+                args,
+                label: [`/${pending.label}`, ...entityLabels, ...shown].join(' '),
+            }),
+        };
+    };
+    /** Ask once when a command has arguments and none were given; otherwise send when nothing required is missing. */
+    const plan = (pending, given) => (pending.args.length > 0 && given === 0
+        ? { status: 'needs-args', request: pending }
+        : complete(pending, {}));
+    return {
+        locale,
+        providers: [commandProvider, entityProvider],
+        command: (id) => commands.get(id),
+        entity: (type) => entities.get(type),
+        completeCommand: complete,
+        async searchEntity(type, query, signal) {
+            const entity = entities.get(type);
+            if (!entity)
+                return [];
+            try {
+                const items = await entity.search(query, { signal, limit: 8, locale, context: config.context ?? {} });
+                return (Array.isArray(items) ? items : [])
+                    .map(definitions_js_1.toChatEntityItem)
+                    .filter((item) => item !== undefined)
+                    .slice(0, 8);
+            }
+            catch {
+                return [];
+            }
+        },
+        planMessage(text, mentions) {
+            const picked = mentions.filter((mention) => mention.type === 'command' && commands.has(String(mention.id)));
+            if (picked.length !== 1)
+                return undefined;
+            const mention = picked[0];
+            const command = commands.get(String(mention.id));
+            const token = tokenOf(mention);
+            if (!token)
+                return undefined;
+            const rest = withoutToken(text, token);
+            if (!rest.found)
+                return undefined;
+            if (command.run.kind === 'prompt') {
+                const prompt = `${(0, chat_interactions_js_1.chatText)(command.run.prompt, locale)} `;
+                // A function replacer: the prompt is the app's text, `$&` and `$$` in it stay as written.
+                return { status: 'prompt', text: rest.text.replace(/^\s*/, () => prompt).trim() };
+            }
+            const values = {};
+            const valueLabels = {};
+            let remaining = rest.text;
+            const entityMentions = mentions.filter((entry) => entry !== mention && entry.type !== 'command');
+            const used = new Set();
+            for (const arg of command.args ?? []) {
+                if (!arg.entity)
+                    continue;
+                const match = entityMentions.find((entry) => entry.type === arg.entity && !used.has(entry));
+                if (!match)
+                    continue;
+                used.add(match);
+                values[arg.name] = String(match.id);
+                valueLabels[arg.name] = typeof match.label === 'string' ? match.label : String(match.id);
+            }
+            for (const entry of used) {
+                const entryToken = tokenOf(entry);
+                if (entryToken)
+                    remaining = withoutToken(remaining, entryToken).text;
+            }
+            // Free text or unused references: the model decides, with the command as a tool reference.
+            if (remaining.trim() || used.size !== entityMentions.length)
+                return undefined;
+            return plan({
+                commandId: command.id,
+                tool: command.run.tool,
+                label: (0, chat_interactions_js_1.chatText)(command.label, locale),
+                fixedArgs: command.run.args ?? {},
+                args: command.args ?? [],
+                values,
+                valueLabels,
+            }, used.size);
+        },
+        planAction(target, actionId) {
+            const action = entities.get(target.type)?.actions?.find((entry) => entry.id === actionId);
+            if (!action)
+                return undefined;
+            return plan({
+                commandId: action.id,
+                tool: action.run.tool,
+                label: (0, chat_interactions_js_1.chatText)(action.label, locale),
+                fixedArgs: action.run.args ?? {},
+                args: action.args ?? [],
+                values: { [action.entityArg]: target.id },
+                valueLabels: { [action.entityArg]: target.label },
+            }, 0);
+        },
+    };
+}

package/dist/cjs/react/interactions/use-chat-interactions-data.d.ts

@@ -0,0 +1,15 @@
+import { type ChatInteractionsData } from '../../contracts/chat-interactions.js';
+export interface UseChatInteractionsDataOptions {
+    headers?: Record<string, string>;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** A failed request or invalid data; the chat then runs without interactions. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Loads the chat's `@` entities and `/` commands from the GET handler of
+ * `createChatInteractionsHandler` (usually the chat endpoint itself), once
+ * per endpoint and with the user's session. `undefined` until loaded or when
+ * the request fails.
+ */
+export declare function useChatInteractionsData(endpoint: string | undefined, options?: UseChatInteractionsDataOptions): ChatInteractionsData | undefined;