@agent-native/core 0.77.24 → 0.78.1

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1933
-- template files: 4312
+- core files: 1937
+- template files: 4351

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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
+
+- 368e2a7: Add core session replay client primitives and private blob storage abstractions for Agent Native Analytics.
+
+### Patch Changes
+
+- 368e2a7: Support CID inline attachments in the core email transport.
+- 368e2a7: Keep agent sidebar contents at their full open width while desktop sidebars animate in and out, avoiding text reflow during the transition, and hide the page-level New chat action until a chat has actually started.
+
 ## 0.77.24
 
 ### Patch Changes

package/corpus/core/docs/content/template-analytics.md

@@ -91,6 +91,11 @@ pnpm install
 pnpm dev
 ```
 
+The Analytics template's dev script pins `DATABASE_URL` to the local SQLite
+file at `./data/app.db`, so a production `DATABASE_URL` in `.env` will not be
+used during local development. To intentionally point local dev at another
+database, run `ANALYTICS_DATABASE_URL=<your dev database url> pnpm dev`.
+
 The CLI prints the local dev URL. Sign in with Google, then open the **Data Sources** page to connect BigQuery, GA4, first-party tracking, HubSpot, Jira, and the rest.
 
 ### Key features

package/corpus/core/docs/content/tracking.md

@@ -132,6 +132,51 @@ Key differences from the [server `track()`](#track):
 
 This is distinct from the framework's internal browser telemetry (`trackEvent()` / automatic pageviews — see [Browser defaults](#browser-defaults) below), which powers Agent Native's own product analytics. Use `track()` for your app's own analytics events that should reach your configured providers.
 
+## Session replay {#session-replay}
+
+Agent Native apps can opt into first-party browser session replay without adding a second analytics SDK. Call `configureTracking()` once in the browser root and pass the Analytics public key plus collector endpoint:
+
+```ts
+import { configureTracking } from "@agent-native/core/client";
+
+configureTracking({
+  key: "anpk_...",
+  endpoint: "https://analytics.example.com/api/analytics/track",
+  sessionReplay: {
+    enabled: true,
+    sampleRate: 1,
+  },
+  getDefaultProps: (_event, props) => ({
+    ...props,
+    app: "my-app",
+    template: "my-template",
+  }),
+});
+```
+
+When `sessionReplay.enabled` is truthy, the client dynamically imports `@rrweb/record` after startup and posts replay chunks to the replay endpoint. If `endpoint` ends in `/api/analytics/track` or `/track`, the replay endpoint is derived automatically as `/api/analytics/replay`. Override it explicitly with `sessionReplay.endpoint` when the replay collector lives somewhere else.
+
+Agent Native template roots already call `configureTracking()`, so hosted template deployments can use Vite/Netlify environment variables instead of editing code:
+
+```bash
+VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY=anpk_...
+VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT=https://analytics.example.com/api/analytics/track
+VITE_AGENT_NATIVE_SESSION_REPLAY_ENABLED=true
+VITE_AGENT_NATIVE_SESSION_REPLAY_SAMPLE_RATE=1
+```
+
+Privacy defaults are intentionally conservative but still useful for playback:
+
+- Inputs are masked by default (`maskAllInputs: true`).
+- Page text remains visible unless an element is marked with `.an-mask` or `data-an-mask`.
+- Sensitive zones are blocked with selectors such as `[data-sensitive]`, `.an-block`, `.an-private`, `data-an-block`, `data-an-private`, and credit-card/password/SSN-like fields.
+- URLs are scrubbed with the same `scrubUrl()` helper used by browser analytics.
+- Replay capture is web-only and opt-in; it does not record native desktop screens.
+
+The Analytics template stores replay metadata in SQL (`session_recordings`) and stores chunks through private blob refs (`session_replay_chunks`). Browsers and agents never receive provider URLs. Playback goes through scoped server routes and the default agent tools return summaries or bounded replay events, not raw chunk table access.
+
+For local development only, Analytics can fall back to capped SQL inline chunks when private blob storage is unavailable. Production deployments should configure private or encrypted blob storage rather than relying on Postgres for replay payloads.
+
 ## Advanced: custom providers & internals {#advanced}
 
 Most apps only need `track()` / `identify()` and a built-in provider. The rest of the surface — registering custom providers, the `TrackingProvider` interface, batching internals, and the framework's own browser telemetry — is below.

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.77.24",
+  "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": {
@@ -101,6 +101,7 @@
     "./tools/url-safety": "./dist/extensions/url-safety.js",
     "./file-upload": "./dist/file-upload/index.js",
     "./file-upload/actions/upload-image": "./dist/file-upload/actions/upload-image.js",
+    "./private-blob": "./dist/private-blob/index.js",
     "./agent/context-xray/actions/context-manifest-get": "./dist/agent/context-xray/actions/context-manifest-get.js",
     "./agent/context-xray/actions/context-pin": "./dist/agent/context-xray/actions/context-pin.js",
     "./agent/context-xray/actions/context-evict": "./dist/agent/context-xray/actions/context-evict.js",
@@ -211,6 +212,7 @@
     "@react-router/dev": "^8.0.1",
     "@react-router/fs-routes": "^8.0.1",
     "@resvg/resvg-js": "^2.6.2",
+    "@rrweb/record": "2.0.1",
     "@sentry/browser": "10.60.0",
     "@sentry/node": "10.60.0",
     "@standard-schema/spec": "^1.1.0",

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

@@ -179,6 +179,7 @@ const AGENT_PANEL_ROOT_STYLE = {
 } satisfies React.CSSProperties;
 type AgentPanelStyle = React.CSSProperties & {
   "--agent-sidebar-closed-transform"?: string;
+  "--agent-sidebar-inner-closed-transform"?: string;
   "--agent-sidebar-width"?: string;
 };
 const AGENT_PANEL_HEADER_CLASS =
@@ -383,11 +384,15 @@ export function shouldShowAgentPanelChatTabBar(
 }
 
 export function shouldShowAgentPanelPageNewChatButton(
-  _tabs: MultiTabAssistantChatHeaderProps["tabs"],
+  tabs: MultiTabAssistantChatHeaderProps["tabs"],
   activeTabId: string,
-  _activeTabMessageCount: number,
+  activeTabMessageCount: number,
 ) {
-  return Boolean(activeTabId);
+  if (!activeTabId) return false;
+  if (activeTabMessageCount > 0) return true;
+
+  const activeTab = tabs.find((tab) => tab.id === activeTabId);
+  return activeTab?.status === "running" || activeTab?.status === "completed";
 }
 
 export function shouldShowAgentPanelCliTabBar(cliTabs: string[]) {
@@ -2333,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;
@@ -2379,6 +2388,8 @@ export function AgentSidebar({
   emptyStateText = "How can I help you?",
   suggestions,
   dynamicSuggestions,
+  composerToolbarSlot,
+  threadFooterSlot,
   defaultSidebarWidth,
   sidebarWidth,
   position = "right",
@@ -2849,6 +2860,7 @@ export function AgentSidebar({
     panelStyle = {
       ...AGENT_PANEL_ROOT_STYLE,
       "--agent-sidebar-width": `${width}px`,
+      "--agent-sidebar-inner-closed-transform": `translateX(${isLeft ? "-" : ""}100%)`,
       width: desktopAnimationEnabled ? undefined : width,
       maxHeight: "100vh",
       borderLeft:
@@ -2894,21 +2906,25 @@ export function AgentSidebar({
         inert={sidebarAnimationEnabled && !panelOpen ? true : undefined}
         aria-hidden={sidebarAnimationEnabled && !panelOpen ? true : undefined}
       >
-        <AgentPanel
-          emptyStateText={emptyStateText}
-          suggestions={suggestions}
-          dynamicSuggestions={dynamicSuggestions}
-          missingApiKeySetupLayout="sidebar"
-          onCollapse={() => setOpenPersisted(false)}
-          isFullscreen={effectiveFullscreen}
-          onToggleFullscreen={
-            isMobile ? undefined : (onFullscreenRequest ?? toggleFullscreen)
-          }
-          storageKey={storageKey}
-          scope={scope}
-          browserTabId={browserTabId}
-          threadUrlSync={threadUrlSync}
-        />
+        <div className="agent-sidebar-panel-inner flex min-h-0 flex-1 flex-col">
+          <AgentPanel
+            emptyStateText={emptyStateText}
+            suggestions={suggestions}
+            dynamicSuggestions={dynamicSuggestions}
+            composerToolbarSlot={composerToolbarSlot}
+            threadFooterSlot={threadFooterSlot}
+            missingApiKeySetupLayout="sidebar"
+            onCollapse={() => setOpenPersisted(false)}
+            isFullscreen={effectiveFullscreen}
+            onToggleFullscreen={
+              isMobile ? undefined : (onFullscreenRequest ?? toggleFullscreen)
+            }
+            storageKey={storageKey}
+            scope={scope}
+            browserTabId={browserTabId}
+            threadUrlSync={threadUrlSync}
+          />
+        </div>
       </div>
       {showResizeHandle && isLeft && (
         <ResizeHandle position={position} onDrag={handleDrag} />

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 {