@agent-native/toolkit 0.213.1 → 0.216.0

package/src/app/agentkit/react/components.tsx

@@ -40,6 +40,7 @@ import {
 import {
   createContext,
   Component,
+  Fragment,
   memo,
   useCallback,
   useContext,
@@ -49,6 +50,7 @@ import {
   useRef,
   useState,
   type ComponentType,
+  type CSSProperties,
   type ErrorInfo,
   type KeyboardEvent as ReactKeyboardEvent,
   type PointerEvent as ReactPointerEvent,
@@ -136,7 +138,13 @@ import {
   type AgentKitSuggestionsRenderProps,
   type AgentRunFailureRenderProps,
 } from "./context.js";
+import { orderMessageContent } from "./message-content-order.js";
 import { AgentStreamingText } from "./streaming-text.js";
+import {
+  workedForRowChevronStyle,
+  workedForRowSummaryStyle,
+  type AgentChatTranscriptLayout,
+} from "./transcript-layout.js";
 
 // AgentKit React installs without @agent-native/core, so it repeats core's
 // replay markers. Its specs assert core's attribute names.
@@ -1464,7 +1472,8 @@ export function AgentActivityGroup({
   excludeAgentActivities?: boolean;
   isCurrentSegment?: boolean;
 }) {
-  const { threadId, slots, registry, labels } = useAgentKit();
+  const { threadId, slots, registry, labels, formatWorkedForDuration } =
+    useAgentKit();
   const thread = useAgentThread();
   const runEvents = runId
     ? thread.events.filter((event) => event.runId === runId)
@@ -1761,6 +1770,7 @@ export function AgentActivityGroup({
   }
   const hasExpandableActivity = displayGroups.length > 0;
   const formatDuration = (ms: number) =>
+    formatWorkedForDuration?.(ms) ??
     formatAgentKitDuration(ms, {
       hour: labels.durationHourShort,
       minute: labels.durationMinuteShort,
@@ -1907,7 +1917,9 @@ function AgentWorkDisclosure({
   current?: ReactNode;
   children: ReactNode;
 }) {
+  const { slots, workedForRowLayout } = useAgentKit();
   const [open, setOpen] = useState(false);
+  const Summary = slots.workedForSummary;
   return (
     <details
       className="agentkit-activities"
@@ -1918,24 +1930,39 @@ function AgentWorkDisclosure({
       <summary
         className="agentkit-activities-summary"
         aria-disabled={!expandable}
+        style={workedForRowSummaryStyle(workedForRowLayout)}
         onClick={(event) => {
           event.preventDefault();
           if (!expandable) return;
           setOpen((value) => !value);
         }}
       >
-        <span className="agentkit-activities-summary-content">
-          {label ? (
-            <span className="agentkit-activities-heading">
-              <span className="agentkit-activities-label">{label}</span>
+        {Summary ? (
+          <Summary
+            label={label}
+            running={running}
+            expandable={expandable}
+            open={open}
+            current={current}
+            layout={workedForRowLayout}
+          />
+        ) : (
+          <>
+            <IconChevronRight
+              aria-hidden="true"
+              className="agentkit-icon agentkit-summary-chevron"
+              style={workedForRowChevronStyle(workedForRowLayout)}
+            />
+            <span className="agentkit-activities-summary-content">
+              {label ? (
+                <span className="agentkit-activities-heading">
+                  <span className="agentkit-activities-label">{label}</span>
+                </span>
+              ) : null}
+              {current}
             </span>
-          ) : null}
-          {current}
-        </span>
-        <IconChevronRight
-          aria-hidden="true"
-          className="agentkit-icon agentkit-summary-chevron"
-        />
+          </>
+        )}
       </summary>
       {children}
     </details>
@@ -3783,11 +3810,15 @@ export function AgentMessageActions({
   );
 }
 
+const AgentKitPostWidgetTextContext =
+  createContext<AgentChatTranscriptLayout["postWidgetText"]>(undefined);
+
 export function AgentMessageView({
   value: message,
   threadId,
 }: AgentKitRenderProps<AgentMessage>) {
-  const { labels, slots } = useAgentKit();
+  const { labels, slots, resolveMessageContentOrder } = useAgentKit();
+  const postWidgetText = useContext(AgentKitPostWidgetTextContext);
   const thread = useAgentThread(threadId);
   const visibleMessage = stripAgentMessageContext(message);
   const Supplement = slots.messageSupplement;
@@ -3812,6 +3843,13 @@ export function AgentMessageView({
       thread.annotationMessageIds[annotation.id] === message.id &&
       !embeddedAnnotationIds.has(annotation.id),
   );
+  const orderedContent = orderMessageContent(
+    visibleMessage,
+    visibleMessage.parts,
+    attachedWidgets,
+    thread.events,
+    resolveMessageContentOrder,
+  );
   if (
     !message.parts.length &&
     !attachedWidgets.length &&
@@ -3821,6 +3859,7 @@ export function AgentMessageView({
       <Supplement value={visibleMessage} threadId={threadId} />
     ) : null;
   }
+  let hasSeenWidget = false;
   return (
     <article
       className="agentkit-message"
@@ -3830,23 +3869,39 @@ export function AgentMessageView({
       aria-busy={message.status === "streaming"}
     >
       <div className="agentkit-message-content">
-        {visibleMessage.parts.map((part, index) => (
-          <AgentMessagePartView
-            key={`${message.id}-${index}`}
-            value={part}
-            threadId={threadId}
-            active={message.status === "streaming"}
-            resetKey={`${threadId}:${message.id}:${index}`}
-            userMessage={message.role === "user"}
-          />
-        ))}
-        {attachedWidgets.map((widget) => (
-          <AgentMessagePartView
-            key={widget.id}
-            value={{ type: "widget", widget }}
-            threadId={threadId}
-          />
-        ))}
+        {orderedContent.map((item, index) => {
+          const isWidget =
+            item.type === "widget" ||
+            (item.type === "part" && item.part.type === "widget");
+          const followsWidget =
+            message.role === "assistant" &&
+            postWidgetText !== undefined &&
+            hasSeenWidget &&
+            item.type === "part" &&
+            item.part.type === "text";
+          if (isWidget) hasSeenWidget = true;
+          const content = (
+            <AgentMessagePartView
+              value={
+                item.type === "widget"
+                  ? { type: "widget", widget: item.widget }
+                  : item.part
+              }
+              threadId={threadId}
+              active={message.status === "streaming"}
+              resetKey={`${threadId}:${message.id}:${index}`}
+              userMessage={message.role === "user"}
+            />
+          );
+
+          return followsWidget ? (
+            <div key={item.key} data-post-widget-text="true">
+              {content}
+            </div>
+          ) : (
+            <Fragment key={item.key}>{content}</Fragment>
+          );
+        })}
         {attachedAnnotations.length ? (
           <div className="agentkit-annotations">
             {attachedAnnotations.map((annotation) => (
@@ -4781,9 +4836,103 @@ export interface AgentKitChatProps {
   emptyComposerPlacement?: "center" | "bottom";
   /** Follow new output until the user deliberately scrolls away. */
   autoScroll?: boolean;
+  /** Optional transcript geometry. Omitted values keep the shared defaults. */
+  transcriptLayout?: AgentChatTranscriptLayout;
   className?: string;
 }
 
+type AgentKitTranscriptContentStyle = CSSProperties & {
+  "--agentkit-transcript-top-inset"?: string;
+  "--agentkit-transcript-lane-width"?: string;
+  "--agentkit-transcript-lane-offset-inline"?: string;
+  "--agentkit-transcript-message-gap"?: string;
+  "--agentkit-transcript-message-line-height"?: string;
+  "--agentkit-transcript-font-family"?: string;
+  "--agentkit-transcript-post-widget-text-color"?: string;
+  "--agentkit-transcript-post-widget-paragraph-padding-block"?: string;
+  "--agentkit-user-bubble-line-height"?: string;
+  "--agentkit-user-bubble-max-width"?: string;
+  "--agentkit-user-bubble-offset-inline"?: string;
+  "--agentkit-user-bubble-padding-block"?: string;
+  "--agentkit-user-bubble-padding-inline"?: string;
+};
+
+function transcriptLength(value: number | undefined, name: string) {
+  if (value === undefined) return undefined;
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `transcriptLayout.${name} must be a non-negative number`,
+    );
+  }
+  return `${value}px`;
+}
+
+function transcriptOffset(value: number | undefined, name: string) {
+  if (value === undefined) return undefined;
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`transcriptLayout.${name} must be a finite number`);
+  }
+  return `${value}px`;
+}
+
+function transcriptContentStyle(
+  layout?: AgentChatTranscriptLayout,
+): AgentKitTranscriptContentStyle | undefined {
+  if (!layout) return undefined;
+  return {
+    "--agentkit-transcript-top-inset": transcriptLength(
+      layout.topInset,
+      "topInset",
+    ),
+    "--agentkit-transcript-lane-width": transcriptLength(
+      layout.messageLaneWidth,
+      "messageLaneWidth",
+    ),
+    "--agentkit-transcript-lane-offset-inline": transcriptOffset(
+      layout.messageLaneOffsetInline,
+      "messageLaneOffsetInline",
+    ),
+    "--agentkit-transcript-message-gap": transcriptLength(
+      layout.messageGap,
+      "messageGap",
+    ),
+    "--agentkit-transcript-message-line-height": transcriptLength(
+      layout.messageLineHeight,
+      "messageLineHeight",
+    ),
+    "--agentkit-transcript-font-family": layout.fontFamily,
+    "--agentkit-transcript-post-widget-text-color":
+      layout.postWidgetText?.tone === "muted"
+        ? "var(--agentkit-text-muted)"
+        : undefined,
+    "--agentkit-transcript-post-widget-paragraph-padding-block":
+      transcriptLength(
+        layout.postWidgetText?.paragraphPaddingBlock,
+        "postWidgetText.paragraphPaddingBlock",
+      ),
+    "--agentkit-user-bubble-line-height": transcriptLength(
+      layout.userBubbleLineHeight,
+      "userBubbleLineHeight",
+    ),
+    "--agentkit-user-bubble-max-width": transcriptLength(
+      layout.userBubbleMaxWidth,
+      "userBubbleMaxWidth",
+    ),
+    "--agentkit-user-bubble-offset-inline": transcriptOffset(
+      layout.userBubbleOffsetInline,
+      "userBubbleOffsetInline",
+    ),
+    "--agentkit-user-bubble-padding-block": transcriptLength(
+      layout.userBubblePadding?.block,
+      "userBubblePadding.block",
+    ),
+    "--agentkit-user-bubble-padding-inline": transcriptLength(
+      layout.userBubblePadding?.inline,
+      "userBubblePadding.inline",
+    ),
+  };
+}
+
 const AGENTKIT_TRANSCRIPT_BOTTOM_THRESHOLD = 24;
 const AGENTKIT_TRANSCRIPT_SCROLLBAR_IDLE_MS = 900;
 const AGENTKIT_TRANSCRIPT_SCROLL_KEYS = new Set([
@@ -4813,6 +4962,7 @@ export function AgentKitChat({
   hasRenderedMessages = false,
   emptyComposerPlacement = "center",
   autoScroll = true,
+  transcriptLayout,
   className,
 }: AgentKitChatProps) {
   const { threadId, slots, registry, labels, onThreadForked } = useAgentKit();
@@ -5563,12 +5713,17 @@ export function AgentKitChat({
           <div
             ref={transcriptContentRef}
             className="agentkit-transcript-content"
+            style={transcriptContentStyle(transcriptLayout)}
           >
             <AgentKitRegionSlot slot={Transcript} threadId={threadId}>
               {!hasConversation && EmptyState ? (
                 <EmptyState threadId={threadId} />
               ) : null}
-              {transcriptItems}
+              <AgentKitPostWidgetTextContext.Provider
+                value={transcriptLayout?.postWidgetText}
+              >
+                {transcriptItems}
+              </AgentKitPostWidgetTextContext.Provider>
               {approvalEntries.map(([approvalId, request]) => (
                 <AgentKitSurfaceBoundary
                   key={`${threadId}:${approvalId}`}

package/src/app/agentkit/react/context.tsx

@@ -43,6 +43,9 @@ import {
   type ReactNode,
 } from "react";
 
+import type { AgentMessageContentOrderResolver } from "./message-content-order.js";
+import type { AgentChatWorkedForRowLayout } from "./transcript-layout.js";
+
 export interface AgentKitRenderProps<T> {
   value: T;
   threadId: ThreadId;
@@ -79,6 +82,15 @@ export interface AgentKitSuggestionsRenderProps {
   onSelect: (suggestion: AgentSuggestion) => void;
 }
 
+export interface AgentKitWorkedForSummaryRenderProps {
+  label: string;
+  running?: boolean;
+  expandable: boolean;
+  open: boolean;
+  current?: ReactNode;
+  layout?: AgentChatWorkedForRowLayout;
+}
+
 export interface AgentConnectionErrorRenderProps {
   error: AgentError;
   threadId: ThreadId;
@@ -153,6 +165,8 @@ export interface AgentKitSlots {
   composer?: ComponentType<{ threadId: ThreadId }>;
   queue?: ComponentType<AgentKitQueueRenderProps>;
   suggestions?: ComponentType<AgentKitSuggestionsRenderProps>;
+  /** Replaces the visible work-summary row while the shared disclosure owns its semantics. */
+  workedForSummary?: ComponentType<AgentKitWorkedForSummaryRenderProps>;
 }
 
 export interface AgentKitToolSource {
@@ -482,6 +496,9 @@ export interface AgentKitProviderProps {
   ) => Promise<AgentConnectionResponse>;
   /** Receives full renderer failures while the UI shows a safe fallback. */
   onRenderError?: (failure: AgentKitRenderFailure) => void;
+  resolveMessageContentOrder?: AgentMessageContentOrderResolver;
+  workedForRowLayout?: AgentChatWorkedForRowLayout;
+  formatWorkedForDuration?: (durationMs: number) => string;
   onClientEffect?: (effect: {
     type: "client.effect" | "client.deeplink";
     name: string;
@@ -511,6 +528,9 @@ export interface AgentKitContextValue {
   loadRunUsage?: AgentKitRunUsageLoader;
   onConnectionRequest?: AgentKitProviderProps["onConnectionRequest"];
   onRenderError?: (failure: AgentKitRenderFailure) => void;
+  resolveMessageContentOrder?: AgentMessageContentOrderResolver;
+  workedForRowLayout?: AgentChatWorkedForRowLayout;
+  formatWorkedForDuration?: (durationMs: number) => string;
   registerComposerFocus: (threadId: ThreadId, focus: () => void) => () => void;
   requestComposerFocus: (threadId: ThreadId) => void;
 }
@@ -531,6 +551,9 @@ export function AgentKitProvider({
   loadRunUsage,
   onConnectionRequest,
   onRenderError,
+  resolveMessageContentOrder,
+  workedForRowLayout,
+  formatWorkedForDuration,
   onClientEffect,
   children,
 }: AgentKitProviderProps) {
@@ -597,6 +620,9 @@ export function AgentKitProvider({
       loadRunUsage,
       onConnectionRequest,
       onRenderError,
+      resolveMessageContentOrder,
+      workedForRowLayout,
+      formatWorkedForDuration,
       registerComposerFocus,
       requestComposerFocus,
     }),
@@ -614,6 +640,9 @@ export function AgentKitProvider({
       loadRunUsage,
       onConnectionRequest,
       onRenderError,
+      resolveMessageContentOrder,
+      workedForRowLayout,
+      formatWorkedForDuration,
       registerComposerFocus,
       requestComposerFocus,
     ],

package/src/app/agentkit/react/index.ts

@@ -1,5 +1,7 @@
 export * from "./chat.js";
 export * from "./components.js";
 export * from "./context.js";
+export * from "./message-content-order.js";
 export * from "./root.js";
 export * from "./streaming-text.js";
+export * from "./transcript-layout.js";