@agentforge-io/chat-sdk 2.0.25 → 2.1.1

package/dist/entities.d.ts

@@ -71,12 +71,43 @@ export interface ChatMessage {
      *  errors, …). View layers should branch on `metadata.kind` before
      *  falling back to `content`. */
     metadata?: ChatMessageMetadata;
+    /** When set, this assistant bubble was produced by a delegated member
+     *  agent (not the primary session agent). View layers resolve the
+     *  member's avatar/name via the session's `members` roster. Absent
+     *  on user messages and on bubbles spoken by the primary agent
+     *  (the orchestrator itself, or any non-team agent). */
+    actingAgentId?: string;
 }
 export interface ChatAgentSummary {
     slug: string;
     name: string;
     description?: string;
 }
+/**
+ * One entry in a Team session's member roster. The orchestrator delegates
+ * to these members; the SDK uses the roster to resolve `actingAgentId`
+ * → avatar/name when rendering per-bubble identity.
+ *
+ * For non-team sessions (a single agent), `members` is empty/undefined
+ * and the SDK falls back to the primary agent's identity on every
+ * assistant bubble — the legacy behaviour.
+ */
+export interface ChatTeamMember {
+    /** Agent id — matches `actingAgentId` on stream chunks and on
+     *  rehydrated `ChatMessage.actingAgentId`. */
+    id: string;
+    name: string;
+    /** Optional avatar URL. When absent, view layers fall back to a
+     *  gradient-with-initial placeholder. */
+    avatarUrl?: string;
+    /** Optional short description ("Handles billing and refunds"). Used
+     *  for tooltip / member-strip rendering on the team channel page. */
+    description?: string;
+    /** Optional per-member routing hint inherited from the team config.
+     *  Surfaced in tooltips so visitors understand the routing policy
+     *  without opening the admin view. */
+    roleHint?: string;
+}
 /**
  * Visual theme returned alongside the agent. Pure data — the SDK doesn't
  * apply it; it just surfaces it so any View layer (widget renderer, React
@@ -110,6 +141,21 @@ export type ChatEvent = {
 } | {
     type: 'message_removed';
     messageId: string;
+}
+/**
+ * Emitted when a Team orchestrator delegates a turn to one of its
+ * members. Carries the member identity so the View layer can render
+ * a subtle "Routing to <member>…" hint (typically as a low-contrast
+ * line between the orchestrator's wrapper bubble and the member's
+ * answer). Pure UX signal — the actual member output arrives via
+ * regular `message_added` / `message_updated` events with the
+ * matching `actingAgentId`.
+ */
+ | {
+    type: 'delegation_routed';
+    memberId: string;
+    memberName?: string;
+    memberAvatarUrl?: string;
 } | {
     type: 'error';
     message: string;

package/dist/react.d.ts

@@ -16,7 +16,7 @@
  * runtime error.
  */
 import { type CSSProperties } from 'react';
-import type { ChatTheme } from './entities';
+import type { ChatTeamMember, ChatTheme } from './entities';
 /**
  * Optional observer fired after the SDK resolves a tool-approval bubble.
  * The SDK owns the network call (it already has `apiBaseUrl` and the
@@ -141,6 +141,16 @@ export interface ChatWidgetProps {
      * Provide this hook to customise — e.g. send immediately, log the
      * click, or open an external link instead. */
     onShortcutClick?: (text: string, index: number) => void;
+    /**
+     * Team-member roster. When the chat is bound to a Team orchestrator,
+     * pass the team's members here so the SDK can render each delegated
+     * bubble with the right member's avatar / name. Each entry's `id`
+     * must match the `actingAgentId` the runtime emits on stream chunks
+     * and on rehydrated `ChatMessage`s. Empty/undefined ⇒ single-agent
+     * session, every bubble uses the primary agent identity (legacy
+     * behaviour).
+     */
+    members?: ChatTeamMember[];
     /**
      * Imperative handle. The widget fills this ref on mount with a
      * small command object the host can call to drive the session

package/dist/react.js

@@ -227,7 +227,17 @@ function fallbackCopy(ctx) {
  * SDK event. Consumers don't need to read `session.getState()` themselves.
  */
 function ChatWidget(props) {
-    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, stream, className, style, onApprovalDecision, readOnlyApprovals = false, variant = 'card', greeting, personaName, shortcuts, onShortcutClick, inputPlaceholder, } = props;
+    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, stream, className, style, onApprovalDecision, readOnlyApprovals = false, variant = 'card', greeting, personaName, shortcuts, onShortcutClick, inputPlaceholder, members, } = props;
+    // Build a lookup so MessageBubble can resolve actingAgentId → identity
+    // in O(1) per render without re-walking the members array. Stable
+    // identity per `members` prop change.
+    const membersById = (0, react_1.useMemo)(() => {
+        const m = new Map();
+        if (members)
+            for (const member of members)
+                m.set(member.id, member);
+        return m;
+    }, [members]);
     const bare = variant === 'bare';
     const [session, setSession] = (0, react_1.useState)(null);
     const [status, setStatus] = (0, react_1.useState)('idle');
@@ -238,7 +248,40 @@ function ChatWidget(props) {
     const [open, setOpen] = (0, react_1.useState)(inline);
     const [draft, setDraft] = (0, react_1.useState)('');
     const messagesRef = (0, react_1.useRef)(null);
+    const inputRef = (0, react_1.useRef)(null);
     const styleId = (0, react_1.useId)();
+    // Track whether the user has already engaged with the widget. We
+    // start at false (just landed on the page) and flip to true the
+    // moment `handleSend` fires. The auto-focus effect below uses this
+    // to decide whether the impending `status = 'ready'` is the first
+    // landing (skip focus on touch — opening the keyboard unprompted
+    // is hostile) or a return from a send-streaming cycle (re-focus
+    // ALWAYS — the user is mid-conversation, losing the cursor
+    // breaks the typing-rhythm).
+    const hasInteractedRef = (0, react_1.useRef)(false);
+    // Auto-focus the composer once the session is ready.
+    //
+    //   Landing (hasInteractedRef.current === false):
+    //     • pointer:fine → focus  (desktop user expects ready-to-type)
+    //     • pointer:coarse → skip (iOS/Android opening the keyboard
+    //                              before the visitor reads anything
+    //                              is jarring)
+    //
+    //   Returning from a send (hasInteractedRef.current === true):
+    //     • always focus, including touch — the user just hit Send,
+    //       they're in conversation mode, their next thought is the
+    //       next message, the keyboard should stay alive.
+    (0, react_1.useEffect)(() => {
+        if (status !== 'ready')
+            return;
+        if (typeof window === 'undefined')
+            return;
+        if (!hasInteractedRef.current &&
+            !window.matchMedia('(pointer: fine)').matches) {
+            return;
+        }
+        inputRef.current?.focus({ preventScroll: true });
+    }, [status]);
     // ── Session lifecycle. Recreate when token / apiBaseUrl changes. ──────
     (0, react_1.useEffect)(() => {
         let cancelled = false;
@@ -282,11 +325,26 @@ function ChatWidget(props) {
         };
     }, [token, apiBaseUrl, browserSessionId, resumeConversationId, stream]);
     // Auto-scroll on new tokens.
+    //
+    // We defer the scroll into a requestAnimationFrame so the DOM has
+    // actually grown by the time we read `scrollHeight`. Without that
+    // tick, a stream of small text_deltas can leave the scroll lagging
+    // 1–2 chunks behind because the effect runs synchronously after
+    // the React commit but BEFORE the browser paints the new rows.
+    // Result: the user sees the latest sentence half-cut at the bottom.
+    //
+    // `behavior: 'smooth'` doesn't help much during a fast stream (each
+    // rAF queues a new smooth-scroll that cancels the previous one) but
+    // it does make the FINAL settle look fluid — and that's the part
+    // the user notices when the stream stops.
     (0, react_1.useEffect)(() => {
         const el = messagesRef.current;
         if (!el)
             return;
-        el.scrollTop = el.scrollHeight;
+        const raf = requestAnimationFrame(() => {
+            el.scrollTo({ top: el.scrollHeight, behavior: 'smooth' });
+        });
+        return () => cancelAnimationFrame(raf);
     }, [messages]);
     // Inject the widget stylesheet exactly once per page. We key the <style>
     // tag by a fixed id so multiple widget mounts share it.
@@ -307,6 +365,11 @@ function ChatWidget(props) {
         const text = draft.trim();
         if (!text)
             return;
+        // Mark engagement BEFORE the status flip so the auto-focus
+        // effect (which watches `status`) sees the flag when it
+        // re-runs after `ready` returns. Subsequent renders will
+        // refocus the textarea on every send completion.
+        hasInteractedRef.current = true;
         setDraft('');
         void session.send(text);
     }, [session, draft]);
@@ -349,45 +412,60 @@ function ChatWidget(props) {
     };
     return ((0, jsx_runtime_1.jsxs)("div", { className: rootClass, style: rootStyle, "data-style-id": styleId, children: [!inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-toggle", "aria-label": open ? 'Close chat' : 'Open chat', "aria-expanded": open, onClick: () => setOpen((v) => !v), children: open ? (0, jsx_runtime_1.jsx)(CloseIcon, {}) : (0, jsx_runtime_1.jsx)(ChatIcon, {}) })), (0, jsx_runtime_1.jsxs)("div", { className: `af-panel ${open ? 'af-open' : ''}`, children: [!bare && ((0, jsx_runtime_1.jsxs)("div", { className: "af-header", children: [theme?.avatarUrl ? (
                             // eslint-disable-next-line @next/next/no-img-element
-                            (0, jsx_runtime_1.jsx)("img", { className: "af-header-avatar", src: theme.avatarUrl, alt: "" })) : null, (0, jsx_runtime_1.jsxs)("div", { className: "af-header-info", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-header-title", children: personaName ?? theme?.title ?? agent?.name ?? 'Chat' }), (0, jsx_runtime_1.jsx)("div", { className: "af-header-subtitle", children: status === 'loading' ? 'Loading…' : agent?.description ?? '' })] }), !inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-close", onClick: () => setOpen(false), "aria-label": "Close chat", children: (0, jsx_runtime_1.jsx)(CloseIcon, {}) }))] })), (0, jsx_runtime_1.jsxs)("div", { className: "af-messages", ref: messagesRef, children: [bare && greeting && messages.length === 0 && status !== 'loading' && ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg-row af-msg-row-assistant", children: [(0, jsx_runtime_1.jsx)(AssistantAvatar, { theme: theme, name: personaName ?? agent?.name, show: true }), (0, jsx_runtime_1.jsx)("div", { className: "af-msg af-msg-assistant af-msg-greeting", dangerouslySetInnerHTML: { __html: renderMarkdown(greeting) } })] })), messages.map((m, i) => {
-                                // Show the avatar only on the FIRST bubble in a run of
-                                // assistant messages. Consecutive assistant turns get a
-                                // transparent placeholder so the column stays aligned.
-                                // User/system bubbles never get an avatar.
-                                const prev = messages[i - 1];
-                                const isAssistant = m.role === 'assistant';
-                                const prevWasAssistant = prev?.role === 'assistant';
-                                const showAvatar = bare && isAssistant && !prevWasAssistant;
-                                return ((0, jsx_runtime_1.jsx)(MessageBubble, { message: m, session: session, readOnly: readOnlyApprovals, onDecision: onApprovalDecision, bare: bare, showAvatar: showAvatar, avatarTheme: theme, avatarName: personaName ?? agent?.name, onContinue: () => {
-                                        // After a successful Approve, kick the next turn so the
-                                        // gate's fast-path consumes the approval and the tool
-                                        // actually runs. `silent: true` keeps the literal
-                                        // "continue" prompt out of the visible transcript —
-                                        // the visitor just sees the assistant's next reply
-                                        // appearing under the "Approved" pill.
-                                        if (!session)
-                                            return;
-                                        setTimeout(() => {
-                                            void session.send('continue', { silent: true });
-                                        }, 250);
-                                    } }, m.id));
-                            })] }), lastError && status === 'error' && ((0, jsx_runtime_1.jsx)("div", { className: "af-error", children: lastError })), shortcuts && shortcuts.length > 0 && messages.length === 0 && ((0, jsx_runtime_1.jsx)("div", { className: "af-shortcut-row", children: shortcuts.map((text, i) => ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-shortcut", onClick: () => {
+                            (0, jsx_runtime_1.jsx)("img", { className: "af-header-avatar", src: theme.avatarUrl, alt: "" })) : null, (0, jsx_runtime_1.jsxs)("div", { className: "af-header-info", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-header-title", children: personaName ?? theme?.title ?? agent?.name ?? 'Chat' }), (0, jsx_runtime_1.jsx)("div", { className: "af-header-subtitle", children: status === 'loading' ? 'Loading…' : agent?.description ?? '' })] }), !inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-close", onClick: () => setOpen(false), "aria-label": "Close chat", children: (0, jsx_runtime_1.jsx)(CloseIcon, {}) }))] })), (0, jsx_runtime_1.jsx)("div", { className: "af-messages", ref: messagesRef, children: messages.map((m, i) => {
+                            // Show the avatar only on the FIRST bubble in a run of
+                            // assistant messages BY THE SAME speaker. A delegation
+                            // boundary (orchestrator → member, or member → next
+                            // member) counts as a new run so each speaker gets their
+                            // avatar surfaced. User/system bubbles never get an avatar.
+                            const prev = messages[i - 1];
+                            const isAssistant = m.role === 'assistant';
+                            const sameAssistantRun = prev?.role === 'assistant' &&
+                                (prev?.actingAgentId ?? null) === (m.actingAgentId ?? null);
+                            const showAvatar = bare && isAssistant && !sameAssistantRun;
+                            // Per-bubble identity resolution. When the chunk carried
+                            // an `actingAgentId` (orchestrator delegated to a member),
+                            // we render the member's avatar/name instead of the
+                            // primary agent's. Falling back to the primary identity
+                            // keeps non-team sessions and orchestrator-self turns
+                            // looking the same as before.
+                            const member = m.actingAgentId
+                                ? membersById.get(m.actingAgentId)
+                                : undefined;
+                            const bubbleAvatarTheme = member
+                                ? { ...theme, avatarUrl: member.avatarUrl }
+                                : theme;
+                            const bubbleAvatarName = member?.name ?? personaName ?? agent?.name;
+                            return ((0, jsx_runtime_1.jsx)(MessageBubble, { message: m, session: session, readOnly: readOnlyApprovals, onDecision: onApprovalDecision, bare: bare, showAvatar: showAvatar, avatarTheme: bubbleAvatarTheme, avatarName: bubbleAvatarName, speakerLabel: member?.name, onContinue: () => {
+                                    // After a successful Approve, kick the next turn so the
+                                    // gate's fast-path consumes the approval and the tool
+                                    // actually runs. `silent: true` keeps the literal
+                                    // "continue" prompt out of the visible transcript —
+                                    // the visitor just sees the assistant's next reply
+                                    // appearing under the "Approved" pill.
+                                    if (!session)
+                                        return;
+                                    setTimeout(() => {
+                                        void session.send('continue', { silent: true });
+                                    }, 250);
+                                } }, m.id));
+                        }) }), lastError && status === 'error' && ((0, jsx_runtime_1.jsx)("div", { className: "af-error", children: lastError })), bare && greeting && messages.length === 0 && status !== 'loading' && ((0, jsx_runtime_1.jsx)("div", { className: "af-greeting-slot", children: (0, jsx_runtime_1.jsxs)("div", { className: "af-msg-row af-msg-row-assistant af-msg-row-greeting", children: [(0, jsx_runtime_1.jsx)(AssistantAvatar, { theme: theme, name: personaName ?? agent?.name, show: true }), (0, jsx_runtime_1.jsx)("div", { className: "af-msg af-msg-assistant af-msg-greeting", dangerouslySetInnerHTML: { __html: renderMarkdown(greeting) } })] }) })), shortcuts && shortcuts.length > 0 && messages.length === 0 && ((0, jsx_runtime_1.jsx)("div", { className: "af-shortcut-row", children: shortcuts.map((text, i) => ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-shortcut", onClick: () => {
                                 if (onShortcutClick)
                                     onShortcutClick(text, i);
                                 else
                                     setDraft(text);
-                            }, children: text }, `${i}-${text}`))) })), (0, jsx_runtime_1.jsxs)("div", { className: "af-input-row", children: [(0, jsx_runtime_1.jsx)("textarea", { className: "af-input", value: draft, onChange: (e) => setDraft(e.target.value), onKeyDown: onKeyDown, placeholder: inputPlaceholder ?? 'Type a message…', rows: 1, disabled: status === 'ended' || status === 'loading' || status === 'idle' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-send", onClick: handleSend, disabled: sendDisabled, "aria-label": "Send message", children: (0, jsx_runtime_1.jsx)(SendIcon, {}) })] }), !bare && (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
+                            }, children: text }, `${i}-${text}`))) })), (0, jsx_runtime_1.jsxs)("div", { className: "af-input-row", children: [(0, jsx_runtime_1.jsx)("textarea", { ref: inputRef, className: "af-input", value: draft, onChange: (e) => setDraft(e.target.value), onKeyDown: onKeyDown, placeholder: inputPlaceholder ?? 'Type a message…', rows: 1, disabled: status === 'ended' || status === 'loading' || status === 'idle' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-send", onClick: handleSend, disabled: sendDisabled, "aria-label": "Send message", children: (0, jsx_runtime_1.jsx)(SendIcon, {}) })] }), !bare && (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
 }
-function MessageBubble({ message, session, readOnly, onDecision, onContinue, bare = false, showAvatar = false, avatarTheme, avatarName, }) {
+function MessageBubble({ message, session, readOnly, onDecision, onContinue, bare = false, showAvatar = false, avatarTheme, avatarName, speakerLabel, }) {
     const kind = message.metadata?.kind;
     if (kind === 'awaiting_approval') {
         // Approval / blocked bubbles also count as "assistant-side" so we
         // wrap them in the same row geometry — keeps the conversation
         // aligned even when a tool dispatch interrupts the regular flow.
-        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)(ApprovalBubble, { message: message, session: session, readOnly: readOnly, onDecision: onDecision, onContinue: onContinue }));
+        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)(ApprovalBubble, { message: message, session: session, readOnly: readOnly, onDecision: onDecision, onContinue: onContinue }), speakerLabel);
     }
     if (kind === 'tool_blocked') {
-        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)(BlockedBubble, { message: message }));
+        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)(BlockedBubble, { message: message }), speakerLabel);
     }
     const cls = `af-msg af-msg-${message.role}${message.role === 'assistant' && message.isStreaming
         ? message.content
@@ -396,13 +474,13 @@ function MessageBubble({ message, session, readOnly, onDecision, onContinue, bar
         : ''}`;
     // Typing state (no content yet): render the three-dot indicator, no markdown.
     if (message.role === 'assistant' && message.isStreaming && !message.content) {
-        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)("div", { className: cls, children: (0, jsx_runtime_1.jsxs)("span", { className: "af-typing-dots", "aria-label": "Assistant is typing", children: [(0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {})] }) }));
+        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)("div", { className: cls, children: (0, jsx_runtime_1.jsxs)("span", { className: "af-typing-dots", "aria-label": "Assistant is typing", children: [(0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {})] }) }), speakerLabel);
     }
     if (message.role === 'assistant') {
         return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)("div", { className: cls, 
             // Output is sanitized by escapeHtml + a fixed tag whitelist in
             // renderMarkdown — safe to inject as HTML.
-            dangerouslySetInnerHTML: { __html: renderMarkdown(message.content) } }));
+            dangerouslySetInnerHTML: { __html: renderMarkdown(message.content) } }), speakerLabel);
     }
     // User & system messages stay as plain text — they're typed verbatim.
     // No avatar column on the user side; they align right.
@@ -413,10 +491,14 @@ function MessageBubble({ message, session, readOnly, onDecision, onContinue, bar
  * avatar column. Card variant skips the wrapper entirely so its
  * historical layout is unchanged.
  */
-function wrapAssistantRow(bare, showAvatar, theme, name, child) {
+function wrapAssistantRow(bare, showAvatar, theme, name, child, 
+/** When set + this is the first bubble of a speaker run (showAvatar
+ *  is true), render the speaker's display name just above the
+ *  bubble. Used by Team chats so members are visually attributed. */
+speakerLabel) {
     if (!bare)
         return child;
-    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg-row af-msg-row-assistant", children: [(0, jsx_runtime_1.jsx)(AssistantAvatar, { theme: theme, name: name, show: showAvatar }), child] }));
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg-row af-msg-row-assistant", children: [(0, jsx_runtime_1.jsx)(AssistantAvatar, { theme: theme, name: name, show: showAvatar }), (0, jsx_runtime_1.jsxs)("div", { className: "af-msg-col", children: [showAvatar && speakerLabel ? ((0, jsx_runtime_1.jsx)("div", { className: "af-msg-speaker", children: speakerLabel })) : null, child] })] }));
 }
 /**
  * Small circular avatar for the assistant-side column. Prefers the
@@ -722,13 +804,14 @@ const WIDGET_CSS = `
   width: 100%;
   height: 100%;
   min-height: 0;
+  flex: 1 1 0%;
 }
 .af-widget-root.af-variant-bare.af-inline .af-panel,
 .af-widget-root.af-variant-bare .af-panel {
   position: relative;
   width: 100%;
-  height: 100%;
-  max-height: none;
+  height: 100% !important;
+  max-height: none !important;
   background: transparent;
   border-radius: 0;
   box-shadow: none;
@@ -752,6 +835,15 @@ const WIDGET_CSS = `
   /* Let the parent flexbox give us a min-height; we'll grow into it
      and scroll internally when the transcript gets longer. */
   min-height: 0;
+  /* Anchor messages to the bottom of the scroll-area when the
+     transcript is shorter than the available height — short
+     conversations sit just above the composer instead of floating
+     up to the top of a tall window. The 'margin-top: auto' on the
+     first child does the same job in pure flex without needing
+     justify-content. */
+}
+.af-widget-root.af-variant-bare .af-messages > :first-child {
+  margin-top: auto;
 }
 .af-widget-root.af-variant-bare .af-msg {
   font-size: 15px;
@@ -859,7 +951,41 @@ const WIDGET_CSS = `
     display: none;
   }
 }
-.af-widget-root.af-variant-bare .af-msg-greeting { animation: af-msg-in 320ms cubic-bezier(0.2, 0.8, 0.2, 1); }
+/* Greeting slot — lives between the message scroller and the
+ * shortcut chips. The bubble itself animates in with a small upward
+ * slide + fade so the visitor's eye is pulled there instead of the
+ * static chip row underneath. Avatar slides in alongside it. The
+ * 120ms delay gives the chip row a beat to render first so the
+ * greeting reads as the assistant *responding* to the page loading,
+ * not part of the static UI. */
+.af-widget-root.af-variant-bare .af-greeting-slot {
+  padding: 4px 0 6px;
+}
+.af-widget-root.af-variant-bare .af-msg-row-greeting {
+  opacity: 0;
+  animation: af-greeting-row-in 420ms cubic-bezier(0.2, 0.8, 0.2, 1) 120ms forwards;
+}
+.af-widget-root.af-variant-bare .af-msg-greeting {
+  opacity: 0;
+  transform: translateY(6px);
+  animation: af-greeting-in 480ms cubic-bezier(0.2, 0.8, 0.2, 1) 180ms forwards;
+}
+@keyframes af-greeting-row-in {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+@keyframes af-greeting-in {
+  from { opacity: 0; transform: translateY(8px) scale(0.98); }
+  to   { opacity: 1; transform: translateY(0) scale(1); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .af-widget-root.af-variant-bare .af-msg-row-greeting,
+  .af-widget-root.af-variant-bare .af-msg-greeting {
+    animation: none;
+    opacity: 1;
+    transform: none;
+  }
+}
 
 /* Slack-style assistant rows: avatar column on the left, bubble on
  * the right. The row IS the alignment container — align-self targets
@@ -880,6 +1006,22 @@ const WIDGET_CSS = `
   max-width: 100%;
   align-self: flex-end;
 }
+/* Column wrapper around the bubble so a Team speaker label can sit
+ * above the bubble without disrupting the avatar's bottom-alignment. */
+.af-widget-root.af-variant-bare .af-msg-col {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 1;
+  gap: 2px;
+}
+.af-widget-root.af-variant-bare .af-msg-speaker {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--af-muted, #64748b);
+  padding-left: 2px;
+  letter-spacing: 0.01em;
+}
 .af-widget-root.af-variant-bare .af-msg-avatar {
   width: 26px;
   height: 26px;

package/dist/session.js

@@ -190,11 +190,23 @@ class ChatSession {
     // ─── Internals ──────────────────────────────────────────────────────────
     async runStream(text, assistant) {
         this.setStatus('sending');
+        // The "active" message is the one we're currently appending
+        // text_deltas into. For non-team sessions it's always the initial
+        // `assistant` message we seeded before calling runStream. For team
+        // sessions, every `delegation_start` opens a NEW message (the
+        // member's bubble) and `delegation_result` closes it back to the
+        // orchestrator's bubble. Hoisted out of the try so the catch can
+        // reach it during cleanup.
+        let active = assistant;
+        let activeFull = ''; // running text of the active message only
+        // Aggregate full transcript across every speaker so the empty-
+        // response guard at the end still works when an orchestrator turn
+        // delegates and the member's text is the only content.
+        let totalFull = '';
         try {
             const generator = this.state.conversationId
                 ? this.transport.streamSendMessage(this.state.conversationId, text, this.browserSessionId)
                 : this.transport.streamCreateConversation(text, this.browserSessionId);
-            let full = '';
             let sawAnyChunk = false;
             for await (const evt of generator) {
                 if (evt.kind === 'conversation') {
@@ -211,6 +223,61 @@ class ChatSession {
                     // legacy widget (no metadata renderer) still shows something
                     // readable.
                     const chunkType = evt.chunk.type;
+                    // Team orchestrator → member handoff. Open a new assistant
+                    // message tagged with the member's id; subsequent text_deltas
+                    // (which the server tags with `actingAgentId` matching the
+                    // delegation) flow into THIS bubble until delegation_result
+                    // closes the handoff and we revert to the orchestrator.
+                    if (chunkType === 'delegation_start') {
+                        const c = evt.chunk;
+                        // Close the orchestrator's wrapper (if any text accumulated).
+                        if (activeFull) {
+                            active.isStreaming = false;
+                            this.updateMessage(active);
+                        }
+                        // Open the member's bubble.
+                        const memberMsg = {
+                            id: makeMessageId('a'),
+                            role: 'assistant',
+                            content: '',
+                            createdAt: new Date(),
+                            isStreaming: true,
+                            actingAgentId: c.subAgentId,
+                        };
+                        this.appendMessage(memberMsg);
+                        active = memberMsg;
+                        activeFull = '';
+                        // UX hint: surface the routing decision so view layers can
+                        // render "Routing to <member>…" without parsing the stream.
+                        this.emit({
+                            type: 'delegation_routed',
+                            memberId: c.subAgentId,
+                            memberName: c.subAgentName,
+                            memberAvatarUrl: c.subAgentAvatarUrl,
+                        });
+                        continue;
+                    }
+                    if (chunkType === 'delegation_result') {
+                        // Close the member's bubble and re-open an orchestrator
+                        // bubble in case the orchestrator wants to add a closing
+                        // line ("Anything else?"). If no orchestrator text follows
+                        // we drop the empty wrapper at end-of-stream.
+                        if (activeFull) {
+                            active.isStreaming = false;
+                            this.updateMessage(active);
+                        }
+                        const wrapMsg = {
+                            id: makeMessageId('a'),
+                            role: 'assistant',
+                            content: '',
+                            createdAt: new Date(),
+                            isStreaming: true,
+                        };
+                        this.appendMessage(wrapMsg);
+                        active = wrapMsg;
+                        activeFull = '';
+                        continue;
+                    }
                     if (chunkType === 'awaiting_approval') {
                         const c = evt.chunk;
                         assistant.metadata = {
@@ -225,7 +292,8 @@ class ChatSession {
                         // Plain-text fallback for legacy clients that don't render
                         // metadata.kind. Capable widgets ignore `content` and read
                         // `metadata.copy` directly.
-                        assistant.content = full || c.copy?.body || (c.connectorName ?? '');
+                        assistant.content =
+                            totalFull || c.copy?.body || (c.connectorName ?? '');
                         this.updateMessage(assistant);
                         continue;
                     }
@@ -240,7 +308,10 @@ class ChatSession {
                             copy: c.copy,
                         };
                         assistant.content =
-                            full || c.copy?.blockedBody || c.reason || (c.connectorName ?? '');
+                            totalFull ||
+                                c.copy?.blockedBody ||
+                                c.reason ||
+                                (c.connectorName ?? '');
                         this.updateMessage(assistant);
                         continue;
                     }
@@ -249,9 +320,10 @@ class ChatSession {
                         continue;
                     if (this.state.status !== 'streaming')
                         this.setStatus('streaming');
-                    full += delta;
-                    assistant.content = full;
-                    this.updateMessage(assistant);
+                    activeFull += delta;
+                    totalFull += delta;
+                    active.content = activeFull;
+                    this.updateMessage(active);
                     continue;
                 }
                 if (evt.kind === 'error') {
@@ -270,26 +342,47 @@ class ChatSession {
             // chunk, the bubble carries that structured payload and is a
             // legitimate terminal state — not a missing reply. Skip the
             // "empty response" guard for those.
-            if (!full && !assistant.metadata) {
+            if (!totalFull && !assistant.metadata) {
                 throw new Error(sawAnyChunk
                     ? 'The model returned an empty response.'
                     : 'No response received from the server.');
             }
-            assistant.isStreaming = false;
-            this.updateMessage(assistant);
-            this.setStatus('ready');
-            return full;
-        }
-        catch (err) {
-            // Drop the half-built assistant message — leaving an empty bubble
-            // around is worse than no bubble at all.
-            if (!assistant.content) {
-                this.removeMessage(assistant.id);
+            // If we opened an orchestrator wrapper after the last delegation
+            // and the orchestrator didn't add a closing line, drop the empty
+            // wrapper instead of leaving a ghost bubble.
+            if (active !== assistant && !activeFull) {
+                this.removeMessage(active.id);
             }
             else {
-                assistant.isStreaming = false;
-                this.updateMessage(assistant);
+                active.isStreaming = false;
+                this.updateMessage(active);
             }
+            // The original `assistant` slot can also be empty if the first
+            // chunk we saw was a delegation_start (orchestrator chose to
+            // delegate immediately without prefacing). Drop it in that case.
+            if (assistant !== active && !assistant.content) {
+                this.removeMessage(assistant.id);
+            }
+            this.setStatus('ready');
+            return totalFull;
+        }
+        catch (err) {
+            // Drop the half-built bubble — leaving empty bubbles around is
+            // worse than no bubble at all. We may have multiple in flight
+            // (orchestrator wrapper + member) when delegating; clean each
+            // independently.
+            const cleanup = (m) => {
+                if (!m.content) {
+                    this.removeMessage(m.id);
+                }
+                else {
+                    m.isStreaming = false;
+                    this.updateMessage(m);
+                }
+            };
+            cleanup(assistant);
+            if (active !== assistant)
+                cleanup(active);
             this.handleError(err);
             return assistant.content;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/chat-sdk",
-  "version": "2.0.25",
+  "version": "2.1.1",
   "description": "Framework-free chat session SDK for AgentForge public chat tokens. Headless — no DOM. Drop into any frontend (React, Vue, Svelte, vanilla) and listen for events.",
   "license": "MIT",
   "main": "dist/index.js",