@agent-native/core 0.78.0 → 0.78.1

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 1937
-- template files: 4348
+- template files: 4351

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @agent-native/core
 
+## 0.78.1
+
+### Patch Changes
+
+- 71849f1: Add structured composer reference chips that can be inserted programmatically
+  and constrained to one visible value per app-defined slot.
+- 71849f1: Forward chat thread footer slots through AgentSidebar so apps can keep live run
+  results attached to chat threads.
+
 ## 0.78.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.78.0",
+  "version": "0.78.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/agent/types.ts

@@ -74,6 +74,9 @@ export interface AgentChatReference {
   source: string;
   refType?: string;
   refId?: string;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
 }
 
 export interface MentionProviderItem {
@@ -84,6 +87,25 @@ export interface MentionProviderItem {
   refType: string;
   refId?: string;
   refPath?: string;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+  clearsSlots?: string[];
+  relatedReferences?: MentionProviderReference[];
+}
+
+export interface MentionProviderReference {
+  label: string;
+  icon?: string;
+  source?: string;
+  refType: string;
+  refId?: string | null;
+  refPath?: string | null;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+  clearsSlots?: string[];
+  relatedReferences?: MentionProviderReference[];
 }
 
 export interface MentionProvider {

package/corpus/core/src/client/AgentPanel.tsx

@@ -2338,6 +2338,10 @@ export interface AgentSidebarProps {
   suggestions?: string[];
   /** Context-aware suggestions merged with `suggestions`. Enabled by default. */
   dynamicSuggestions?: AssistantChatProps["dynamicSuggestions"];
+  /** Optional controls rendered in the chat composer toolbar. */
+  composerToolbarSlot?: AssistantChatProps["composerToolbarSlot"];
+  /** Optional content rendered at the bottom of the chat thread. */
+  threadFooterSlot?: AssistantChatProps["threadFooterSlot"];
   /** Initial sidebar width in pixels. Mount-only; user resize and a saved
    *  localStorage value override this. Default: 380 */
   defaultSidebarWidth?: number;
@@ -2384,6 +2388,8 @@ export function AgentSidebar({
   emptyStateText = "How can I help you?",
   suggestions,
   dynamicSuggestions,
+  composerToolbarSlot,
+  threadFooterSlot,
   defaultSidebarWidth,
   sidebarWidth,
   position = "right",
@@ -2905,6 +2911,8 @@ export function AgentSidebar({
             emptyStateText={emptyStateText}
             suggestions={suggestions}
             dynamicSuggestions={dynamicSuggestions}
+            composerToolbarSlot={composerToolbarSlot}
+            threadFooterSlot={threadFooterSlot}
             missingApiKeySetupLayout="sidebar"
             onCollapse={() => setOpenPersisted(false)}
             isFullscreen={effectiveFullscreen}

package/corpus/core/src/client/AssistantChat.tsx

@@ -601,6 +601,13 @@ export interface AssistantChatHandle {
   exportThreadSnapshot(): ChatThreadSnapshot | null;
 }
 
+export type AssistantChatThreadFooterSlot =
+  | React.ReactNode
+  | ((context: {
+      threadId: string | null;
+      tabId: string | null;
+    }) => React.ReactNode);
+
 export interface AssistantChatAdapterContext {
   apiUrl: string;
   tabId?: string;
@@ -638,6 +645,8 @@ export interface AssistantChatProps {
   suggestions?: string[];
   /** Context-aware suggestions merged with `suggestions`. Enabled by default. */
   dynamicSuggestions?: AgentDynamicSuggestionsOption;
+  /** Optional content rendered at the bottom of the scrollable thread, after messages. */
+  threadFooterSlot?: AssistantChatThreadFooterSlot;
   /** Optional content rendered in the empty state, above the suggestion buttons. */
   emptyStateAddon?: React.ReactNode;
   /** Whether to show the header bar. Default: true */
@@ -952,6 +961,7 @@ const AssistantChatInner = forwardRef<
     emptyStateText,
     suggestions,
     dynamicSuggestions,
+    threadFooterSlot,
     emptyStateAddon,
     showHeader = true,
     onSwitchToCli,
@@ -2870,6 +2880,14 @@ const AssistantChatInner = forwardRef<
     isAutoResuming ||
     queuedMessages.length > 0 ||
     reconnectContent.length > 0;
+  const resolvedThreadFooterSlot =
+    typeof threadFooterSlot === "function"
+      ? threadFooterSlot({
+          threadId: threadId ?? null,
+          tabId: tabId ?? null,
+        })
+      : threadFooterSlot;
+  const hasThreadFooterSlot = Boolean(resolvedThreadFooterSlot);
   const isFreshEmptyChat =
     messages.length === 0 &&
     !hasActiveChatWork &&
@@ -2887,6 +2905,13 @@ const AssistantChatInner = forwardRef<
     centerComposerWhenEmpty && (isFreshEmptyChat || centeredRestoringState);
   const showEmptyState =
     messages.length === 0 && !isReconnecting && !hasActiveChatWork;
+  const showInlineEmptyThreadFooterSlot =
+    showEmptyState &&
+    !centeredEmptyState &&
+    !isRestoring &&
+    hasThreadFooterSlot;
+  const showCenteredEmptyThreadFooterSlot =
+    centeredEmptyState && !isRestoring && hasThreadFooterSlot;
   const showComposerSlot =
     Boolean(composerSlot) && (!centerComposerWhenEmpty || centeredEmptyState);
 
@@ -3139,6 +3164,11 @@ const AssistantChatInner = forwardRef<
                           ))}
                         </div>
                       ) : null}
+                      {showInlineEmptyThreadFooterSlot ? (
+                        <div className="agent-thread-footer-slot agent-thread-footer-slot--empty">
+                          {resolvedThreadFooterSlot}
+                        </div>
+                      ) : null}
                     </div>
                   ) : (
                     <div className="agent-thread-content flex flex-col gap-4 px-4 py-4">
@@ -3266,6 +3296,11 @@ const AssistantChatInner = forwardRef<
                           </div>
                         );
                       })}
+                      {resolvedThreadFooterSlot ? (
+                        <div className="agent-thread-footer-slot">
+                          {resolvedThreadFooterSlot}
+                        </div>
+                      ) : null}
                     </div>
                   )}
                 </div>
@@ -3285,6 +3320,11 @@ const AssistantChatInner = forwardRef<
                 )}
 
                 {showComposerSlot ? composerSlot : null}
+                {showCenteredEmptyThreadFooterSlot ? (
+                  <div className="agent-thread-footer-slot agent-thread-footer-slot--centered-empty">
+                    {resolvedThreadFooterSlot}
+                  </div>
+                ) : null}
                 {guidedQuestions && guidedQuestions.length > 0 && (
                   <div className="shrink-0 px-3 pb-2 pt-1">
                     <div className="rounded-lg border border-border bg-card/60 shadow-sm">

package/corpus/core/src/client/agent-chat.ts

@@ -117,6 +117,37 @@ export interface AgentChatContextState {
   updatedAt: number;
 }
 
+export interface AgentComposerReference {
+  label: string;
+  icon?: string;
+  source?: string;
+  refType: string;
+  refId?: string | null;
+  refPath?: string | null;
+  /** Stable composer slot this reference occupies. Slot references replace older values. */
+  slotKey?: string;
+  /** Short label shown before the selected value in the composer chip. */
+  slotLabel?: string;
+  /** Additional app-defined data used by the client for filtering and grouping. */
+  metadata?: Record<string, unknown>;
+  /** Slots to remove when this reference is inserted or removed. */
+  clearsSlots?: string[];
+  /** Additional references to insert before this one. */
+  relatedReferences?: AgentComposerReference[];
+}
+
+export interface AgentComposerReferenceInsertOptions {
+  /**
+   * Whether to open the agent sidebar before inserting the reference.
+   * Defaults to false so contextual auto-tags can stay quiet.
+   */
+  openSidebar?: boolean;
+}
+
+export interface AgentComposerReferenceInsertPayload extends AgentComposerReference {
+  insertMessageId: string;
+}
+
 export interface AgentChatContextMutationOptions {
   /**
    * Whether to open the agent sidebar if it's currently hidden.
@@ -140,6 +171,10 @@ export const AGENT_CHAT_REMOVE_CONTEXT_MESSAGE_TYPE =
   "agentNative.removeChatContext";
 export const AGENT_CHAT_CLEAR_CONTEXT_MESSAGE_TYPE =
   "agentNative.clearChatContext";
+export const AGENT_CHAT_INSERT_REFERENCE_MESSAGE_TYPE =
+  "agentNative.insertComposerReference";
+export const AGENT_CHAT_INSERT_REFERENCE_EVENT =
+  "agentNative:insert-composer-reference";
 const AGENT_PANEL_PREPARE_EVENT = "agent-panel:prepare";
 
 let agentChatContextState: AgentChatContextState = {
@@ -406,6 +441,82 @@ export function appendAgentChatContextToMessage(
   return `${message.trim()}\n\n<context>\n${trimmedContext}\n</context>`;
 }
 
+function normalizeStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const normalized = value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function normalizeMetadata(
+  value: unknown,
+): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+function normalizeAgentComposerReferenceInternal(
+  value: unknown,
+  depth: number,
+): AgentComposerReference | null {
+  if (typeof value !== "object" || value === null) return null;
+  const candidate = value as Partial<AgentComposerReference>;
+  const label =
+    typeof candidate.label === "string" ? candidate.label.trim() : "";
+  const refType =
+    typeof candidate.refType === "string" ? candidate.refType.trim() : "";
+  if (!label || !refType) return null;
+  const normalized: AgentComposerReference = {
+    label,
+    icon:
+      typeof candidate.icon === "string" && candidate.icon.trim()
+        ? candidate.icon.trim()
+        : undefined,
+    source:
+      typeof candidate.source === "string" && candidate.source.trim()
+        ? candidate.source.trim()
+        : undefined,
+    refType,
+    refId:
+      typeof candidate.refId === "string" && candidate.refId.trim()
+        ? candidate.refId.trim()
+        : null,
+    refPath:
+      typeof candidate.refPath === "string" && candidate.refPath.trim()
+        ? candidate.refPath.trim()
+        : null,
+  };
+  const slotKey =
+    typeof candidate.slotKey === "string" ? candidate.slotKey.trim() : "";
+  if (slotKey) normalized.slotKey = slotKey;
+  const slotLabel =
+    typeof candidate.slotLabel === "string" ? candidate.slotLabel.trim() : "";
+  if (slotLabel) normalized.slotLabel = slotLabel;
+  const metadata = normalizeMetadata(candidate.metadata);
+  if (metadata) normalized.metadata = metadata;
+  const clearsSlots = normalizeStringArray(candidate.clearsSlots);
+  if (clearsSlots) normalized.clearsSlots = clearsSlots;
+  if (depth < 3 && Array.isArray(candidate.relatedReferences)) {
+    const relatedReferences = candidate.relatedReferences
+      .map((item) => normalizeAgentComposerReferenceInternal(item, depth + 1))
+      .filter((item): item is AgentComposerReference => item !== null);
+    if (relatedReferences.length > 0) {
+      normalized.relatedReferences = relatedReferences;
+    }
+  }
+  return normalized;
+}
+
+export function normalizeAgentComposerReference(
+  value: unknown,
+): AgentComposerReference | null {
+  return normalizeAgentComposerReferenceInternal(value, 0);
+}
+
 function postAgentChatContextMessage(
   type:
     | typeof AGENT_CHAT_SET_CONTEXT_MESSAGE_TYPE
@@ -446,6 +557,51 @@ function postAgentChatContextMessage(
   }
 }
 
+function postAgentChatReferenceMessage(
+  payload: AgentComposerReferenceInsertPayload,
+  options: { openSidebar: boolean },
+): void {
+  if (typeof window === "undefined") return;
+
+  const message = {
+    type: AGENT_CHAT_INSERT_REFERENCE_MESSAGE_TYPE,
+    data: payload,
+  };
+  const targetSelf = isInBuilderFrame() || isDirectMcpAppEmbedSession();
+  const target = targetSelf
+    ? window
+    : window.parent !== window
+      ? window.parent
+      : window;
+  const targetOrigin = targetSelf
+    ? window.location.origin
+    : getFramePostMessageTargetOrigin() || window.location.origin;
+
+  if (options.openSidebar) {
+    window.dispatchEvent(
+      new CustomEvent("agent-panel:set-mode", {
+        detail: { mode: "chat" },
+      }),
+    );
+    window.dispatchEvent(new CustomEvent("agent-panel:open"));
+  } else {
+    window.dispatchEvent(new CustomEvent(AGENT_PANEL_PREPARE_EVENT));
+  }
+
+  window.dispatchEvent(
+    new CustomEvent(AGENT_CHAT_INSERT_REFERENCE_EVENT, {
+      detail: payload,
+    }),
+  );
+
+  const postToTarget = () => target.postMessage(message, targetOrigin);
+  if (target === window) {
+    setTimeout(postToTarget, 0);
+  } else {
+    postToTarget();
+  }
+}
+
 function isMcpAppChatBridgeEnabled(): boolean {
   if (typeof window === "undefined" || window.parent === window) return false;
   if (readEmbedMcpChatBridgeFlagFromUrl()) markEmbedMcpChatBridgeActive();
@@ -685,6 +841,23 @@ export const setContextToAgentChat = setAgentChatContextItem;
 /** @deprecated Use `setAgentChatContextItem` instead. */
 export const addContextToAgentChat = setAgentChatContextItem;
 
+export function insertAgentComposerReference(
+  ref: AgentComposerReference,
+  options: AgentComposerReferenceInsertOptions = {},
+): void {
+  const normalized = normalizeAgentComposerReference(ref);
+  if (!normalized || typeof window === "undefined") return;
+  postAgentChatReferenceMessage(
+    {
+      ...normalized,
+      insertMessageId: `reference-${Date.now()}-${Math.random()
+        .toString(36)
+        .slice(2, 8)}`,
+    },
+    { openSidebar: options.openSidebar === true },
+  );
+}
+
 export function removeAgentChatContextItem(
   keyOrOpts: string | AgentChatContextRemoveOptions,
 ): void {