@agent-native/toolkit 0.213.1 → 0.216.0

package/src/app/agentkit/react/message-content-order.ts

@@ -0,0 +1,246 @@
+import type {
+  AgentEvent,
+  AgentMessage,
+  AgentMessagePart,
+  AgentWidget,
+} from "@agent-native/agentkit/protocol";
+
+export type AgentMessageContentItem =
+  | { key: string; type: "part"; part: AgentMessagePart }
+  | { key: string; type: "widget"; widget: AgentWidget };
+
+export interface AgentMessageContentOrderInput {
+  message: AgentMessage;
+  parts: AgentMessagePart[];
+  widgets: AgentWidget[];
+  events: AgentEvent[];
+  defaultOrder: AgentMessageContentItem[];
+}
+
+export type AgentMessageContentOrderResolver = (
+  input: AgentMessageContentOrderInput,
+) => AgentMessageContentItem[];
+
+type TextContentOrderItem = Extract<
+  AgentMessageContentItem,
+  { type: "part" }
+> & {
+  part: Extract<AgentMessagePart, { type: "text" }>;
+};
+
+function isTextContentOrderItem(
+  item: AgentMessageContentItem | null | undefined,
+): item is TextContentOrderItem {
+  return (
+    item?.type === "part" &&
+    typeof item.key === "string" &&
+    item.part?.type === "text" &&
+    typeof item.part.text === "string"
+  );
+}
+
+function resolvedItemsPreserveContent(
+  defaultOrder: AgentMessageContentItem[],
+  resolvedOrder: AgentMessageContentItem[],
+): AgentMessageContentItem[] | undefined {
+  if (!Array.isArray(resolvedOrder)) return undefined;
+
+  const defaultText = defaultOrder
+    .filter(isTextContentOrderItem)
+    .map((item) => item.part.text)
+    .join("");
+  const resolvedText = resolvedOrder
+    .filter(isTextContentOrderItem)
+    .map((item) => item.part.text)
+    .join("");
+  if (defaultText !== resolvedText) return undefined;
+
+  const expectedItems = new Map<string, AgentMessageContentItem[]>();
+  for (const item of defaultOrder) {
+    if (item.type === "part" && item.part.type === "text") continue;
+    const identity = `${item.type}:${item.key}`;
+    const matchingItems = expectedItems.get(identity) ?? [];
+    matchingItems.push(item);
+    expectedItems.set(identity, matchingItems);
+  }
+
+  const preservedItems: AgentMessageContentItem[] = [];
+  for (const item of resolvedOrder) {
+    if (!item || typeof item !== "object") return undefined;
+    if (item.type === "part" && item.part?.type === "text") {
+      if (typeof item.key !== "string" || typeof item.part.text !== "string") {
+        return undefined;
+      }
+      preservedItems.push(item);
+      continue;
+    }
+
+    if (
+      (item.type !== "part" && item.type !== "widget") ||
+      typeof item.key !== "string"
+    ) {
+      return undefined;
+    }
+
+    const identity = `${item.type}:${item.key}`;
+    const matchingItems = expectedItems.get(identity);
+    const original = matchingItems?.shift();
+    if (!original) return undefined;
+    preservedItems.push(original);
+  }
+
+  if (
+    [...expectedItems.values()].some((matchingItems) => matchingItems.length)
+  ) {
+    return undefined;
+  }
+  return preservedItems;
+}
+
+/** Uses the stream timeline only when it reconstructs the saved text exactly. */
+export function orderMessageContent(
+  message: AgentMessage,
+  visibleParts: AgentMessagePart[],
+  attachedWidgets: AgentWidget[],
+  events: AgentEvent[],
+  resolveOrder?: AgentMessageContentOrderResolver,
+): AgentMessageContentItem[] {
+  const fallback = [
+    ...visibleParts.map((part, index) => ({
+      key: `${message.id}-${index}`,
+      type: "part" as const,
+      part,
+    })),
+    ...attachedWidgets.map((widget) => ({
+      key: widget.id,
+      type: "widget" as const,
+      widget,
+    })),
+  ];
+  const resolve = (defaultOrder: AgentMessageContentItem[]) => {
+    const resolvedOrder = resolveOrder?.({
+      message,
+      parts: visibleParts,
+      widgets: attachedWidgets,
+      events,
+      defaultOrder,
+    });
+    if (resolvedOrder == null) return defaultOrder;
+    return (
+      resolvedItemsPreserveContent(defaultOrder, resolvedOrder) ?? defaultOrder
+    );
+  };
+
+  if (
+    attachedWidgets.length === 0 ||
+    message.parts.length !== 1 ||
+    message.parts[0]?.type !== "text" ||
+    visibleParts.length !== 1 ||
+    visibleParts[0]?.type !== "text" ||
+    visibleParts[0].text !== message.parts[0].text
+  ) {
+    return resolve(fallback);
+  }
+
+  const widgetIds = new Set(attachedWidgets.map((widget) => widget.id));
+  const widgetOffsets = new Map<string, number>();
+  const widgetEventOrder = new Map<string, number>();
+  let reconstructedText = "";
+  let textOffset = 0;
+
+  for (const [eventIndex, event] of events.entries()) {
+    if (event.type === "message.created" && event.message.id === message.id) {
+      const createdParts = event.message.parts;
+      if (
+        createdParts.length > 1 ||
+        createdParts.some((part) => part.type !== "text")
+      ) {
+        return resolve(fallback);
+      }
+      reconstructedText =
+        createdParts[0]?.type === "text" ? createdParts[0].text : "";
+      textOffset = reconstructedText.length;
+      continue;
+    }
+
+    if (event.type === "message.delta" && event.messageId === message.id) {
+      reconstructedText += event.text;
+      textOffset += event.text.length;
+      continue;
+    }
+
+    if (
+      (event.type === "widget.created" || event.type === "widget.updated") &&
+      event.messageId === message.id &&
+      widgetIds.has(event.widget.id) &&
+      !widgetOffsets.has(event.widget.id)
+    ) {
+      widgetOffsets.set(event.widget.id, textOffset);
+      widgetEventOrder.set(event.widget.id, eventIndex);
+    }
+  }
+
+  const fullText = message.parts[0].text;
+  if (
+    reconstructedText !== fullText ||
+    widgetOffsets.size !== attachedWidgets.length ||
+    [...widgetOffsets.values()].some((offset) => {
+      if (offset === 0 || offset === fullText.length) return false;
+      const preceding = fullText.charCodeAt(offset - 1);
+      const following = fullText.charCodeAt(offset);
+      return (
+        preceding >= 0xd800 &&
+        preceding <= 0xdbff &&
+        following >= 0xdc00 &&
+        following <= 0xdfff
+      );
+    })
+  ) {
+    return resolve(fallback);
+  }
+
+  const widgetsAtOffset = new Map<number, AgentWidget[]>();
+  for (const widget of attachedWidgets) {
+    const offset = widgetOffsets.get(widget.id)!;
+    const widgets = widgetsAtOffset.get(offset) ?? [];
+    widgets.push(widget);
+    widgetsAtOffset.set(offset, widgets);
+  }
+  for (const widgets of widgetsAtOffset.values()) {
+    widgets.sort(
+      (first, second) =>
+        widgetEventOrder.get(first.id)! - widgetEventOrder.get(second.id)!,
+    );
+  }
+
+  const insertions = [...widgetsAtOffset.entries()].sort(
+    ([first], [second]) => first - second,
+  );
+  const part = visibleParts[0];
+  if (part.type !== "text") return resolve(fallback);
+
+  const ordered: AgentMessageContentItem[] = [];
+  let cursor = 0;
+  for (const [offset, widgets] of insertions) {
+    if (offset > cursor) {
+      ordered.push({
+        key: `${message.id}-text-${cursor}`,
+        type: "part",
+        part: { ...part, text: part.text.slice(cursor, offset) },
+      });
+    }
+    for (const widget of widgets) {
+      ordered.push({ key: widget.id, type: "widget", widget });
+    }
+    cursor = offset;
+  }
+  if (cursor < part.text.length) {
+    ordered.push({
+      key: `${message.id}-text-${cursor}`,
+      type: "part",
+      part: { ...part, text: part.text.slice(cursor) },
+    });
+  }
+
+  return resolve(ordered);
+}

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

@@ -30,6 +30,8 @@ import {
   type AgentKitRunUsageLoader,
   type AgentKitSlots,
 } from "./context.js";
+import type { AgentMessageContentOrderResolver } from "./message-content-order.js";
+import type { AgentChatWorkedForRowLayout } from "./transcript-layout.js";
 
 const mountedManagedClients = new WeakMap<AgentKitClient, number>();
 
@@ -84,6 +86,9 @@ export interface AgentKitRootBaseProps {
     request: AgentConnectionRequest,
   ) => Promise<AgentConnectionResponse>;
   onRenderError?: (failure: AgentKitRenderFailure) => void;
+  resolveMessageContentOrder?: AgentMessageContentOrderResolver;
+  workedForRowLayout?: AgentChatWorkedForRowLayout;
+  formatWorkedForDuration?: (durationMs: number) => string;
   onClientEffect?: (effect: {
     type: "client.effect" | "client.deeplink";
     name: string;
@@ -113,6 +118,9 @@ export function AgentKitRoot({
   loadRunUsage,
   onConnectionRequest,
   onRenderError,
+  resolveMessageContentOrder,
+  workedForRowLayout,
+  formatWorkedForDuration,
   onClientEffect,
   load = "auto",
   onLoadError,
@@ -290,6 +298,9 @@ export function AgentKitRoot({
       loadRunUsage={loadRunUsage}
       onConnectionRequest={onConnectionRequest}
       onRenderError={onRenderError}
+      resolveMessageContentOrder={resolveMessageContentOrder}
+      workedForRowLayout={workedForRowLayout}
+      formatWorkedForDuration={formatWorkedForDuration}
       onClientEffect={onClientEffect}
     >
       {children}

package/src/app/agentkit/react/styles.css

@@ -669,11 +669,18 @@ body:has(> [data-agent-native-composer-popover="true"]) > .fixed.inset-0 {
 }
 
 .agentkit-transcript-content {
+  position: relative;
   box-sizing: border-box;
-  inline-size: min(100%, 47rem);
+  inline-size: min(100%, var(--agentkit-transcript-lane-width, 47rem));
   min-inline-size: 0;
   margin-inline: auto;
+  inset-inline-start: clamp(
+    calc((100% - min(100%, var(--agentkit-transcript-lane-width, 47rem))) / -2),
+    var(--agentkit-transcript-lane-offset-inline, 0px),
+    calc((100% - min(100%, var(--agentkit-transcript-lane-width, 47rem))) / 2)
+  );
   padding: 1.5rem 1rem;
+  padding-block-start: var(--agentkit-transcript-top-inset, 1.5rem);
 }
 
 .agentkit-scroll-to-bottom-control {
@@ -710,13 +717,21 @@ body:has(> [data-agent-native-composer-popover="true"]) > .fixed.inset-0 {
   display: flex;
   flex-direction: column;
   align-items: flex-start;
-  margin-block: 0 1.25rem;
+  margin-block: 0 var(--agentkit-transcript-message-gap, 1.25rem);
   font-size: 0.875rem;
-  line-height: 1.52;
+  font-family: var(
+    --agentkit-transcript-font-family,
+    var(--font-sans, inherit)
+  );
+  line-height: var(--agentkit-transcript-message-line-height, 1.52);
 }
 
 .agentkit-message[data-role="user"] {
   align-items: flex-end;
+  line-height: var(
+    --agentkit-user-bubble-line-height,
+    var(--agentkit-transcript-message-line-height, 1.52)
+  );
 }
 
 .agentkit-message-content {
@@ -726,8 +741,11 @@ body:has(> [data-agent-native-composer-popover="true"]) > .fixed.inset-0 {
 }
 
 .agentkit-message[data-role="user"] .agentkit-message-content {
-  max-inline-size: min(88%, 38rem);
-  padding: 0.625rem 0.8125rem;
+  position: relative;
+  inset-inline-start: var(--agentkit-user-bubble-offset-inline, 0px);
+  max-inline-size: min(88%, var(--agentkit-user-bubble-max-width, 38rem));
+  padding: var(--agentkit-user-bubble-padding-block, 0.625rem)
+    var(--agentkit-user-bubble-padding-inline, 0.8125rem);
   border-radius: var(--agentkit-radius-inner);
   background: var(--agentkit-subtle);
 }
@@ -845,6 +863,25 @@ body:has(> [data-agent-native-composer-popover="true"]) > .fixed.inset-0 {
   background: var(--agentkit-canvas);
 }
 
+.agentkit-message-content [data-post-widget-text="true"] {
+  display: contents;
+  color: var(--agentkit-transcript-post-widget-text-color, inherit);
+}
+
+.agentkit-message-content [data-post-widget-text="true"] > p,
+.agentkit-message-content [data-post-widget-text="true"] .agentkit-markdown p {
+  padding-block: var(
+    --agentkit-transcript-post-widget-paragraph-padding-block,
+    0px
+  );
+}
+
+.agentkit-message-content
+  > [data-post-widget-text="true"]:last-child
+  > :last-child {
+  margin-block-end: 0;
+}
+
 .agentkit-image-preview img {
   max-inline-size: 92vw;
   max-block-size: 90vh;
@@ -1216,7 +1253,7 @@ body:has(> [data-agent-native-composer-popover="true"]) > .fixed.inset-0 {
   inline-size: fit-content;
   max-inline-size: 100%;
   align-items: center;
-  gap: 0.375rem;
+  gap: 1rem;
 }
 
 .agentkit-activities {
@@ -1418,7 +1455,7 @@ body:has(> [data-agent-native-composer-popover="true"]) > .fixed.inset-0 {
 }
 
 .agentkit-activities-summary > .agentkit-summary-chevron {
-  opacity: 0;
+  opacity: 1;
 }
 
 .agentkit-activities[data-expandable="true"]
@@ -2133,6 +2170,6 @@ button.agentkit-object {
   }
 
   .agentkit-message[data-role="user"] .agentkit-message-content {
-    max-inline-size: 94%;
+    max-inline-size: min(94%, var(--agentkit-user-bubble-max-width, 38rem));
   }
 }

package/src/app/agentkit/react/transcript-layout.spec.ts

@@ -0,0 +1,72 @@
+import type { AgentKitController } from "@agent-native/agentkit/client";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { useAgentKit } from "./context.js";
+import { AgentKitRoot } from "./root.js";
+import {
+  workedForRowChevronStyle,
+  workedForRowSummaryStyle,
+} from "./transcript-layout.js";
+
+function WorkedForLayoutProbe() {
+  const { workedForRowLayout, formatWorkedForDuration } = useAgentKit();
+  return createElement("span", {
+    "data-icon-gap": workedForRowLayout?.iconGap,
+    "data-duration": formatWorkedForDuration?.(16_000),
+  });
+}
+
+describe("worked-for row layout", () => {
+  it("applies shared dimensions to the summary and leading chevron", () => {
+    const layout = {
+      chevronSize: 12,
+      iconGap: 8,
+      fontSize: 13,
+      lineHeight: 16,
+      paddingBlock: 2,
+      paddingInline: 4,
+    };
+
+    expect(workedForRowSummaryStyle(layout)).toEqual({
+      gap: "8px",
+      fontSize: "13px",
+      lineHeight: "16px",
+      paddingBlock: "2px",
+      paddingInline: "4px",
+      fontFamily: "inherit",
+    });
+    expect(workedForRowChevronStyle(layout)).toEqual({
+      width: "12px",
+      height: "12px",
+    });
+  });
+
+  it("rejects invalid CSS dimensions", () => {
+    expect(() => workedForRowSummaryStyle({ fontSize: 0 })).toThrow(
+      "workedForRowLayout.fontSize must be a valid CSS length",
+    );
+  });
+
+  it("carries the layout from the AgentKit root into shared context", () => {
+    const layout = { iconGap: 8 };
+    const formatWorkedForDuration = (durationMs: number) =>
+      `${Math.round(durationMs / 1000)} seconds`;
+    const markup = renderToStaticMarkup(
+      createElement(
+        AgentKitRoot,
+        {
+          controller: {} as AgentKitController,
+          threadId: "thread",
+          workedForRowLayout: layout,
+          formatWorkedForDuration,
+        },
+        createElement(WorkedForLayoutProbe),
+      ),
+    );
+
+    expect(markup).toContain('data-icon-gap="8"');
+    expect(markup).toContain('data-duration="16 seconds"');
+  });
+});

package/src/app/agentkit/react/transcript-layout.ts

@@ -0,0 +1,97 @@
+import type { CSSProperties } from "react";
+
+export interface AgentChatTranscriptLayout {
+  /** Top padding above transcript messages, in CSS pixels. */
+  topInset?: number;
+  /** Maximum centered message lane width, in CSS pixels. */
+  messageLaneWidth?: number;
+  /** Signed inline offset for the centered message lane, in CSS pixels. */
+  messageLaneOffsetInline?: number;
+  /** Space after each message, in CSS pixels. */
+  messageGap?: number;
+  /** Assistant message line height, in CSS pixels. */
+  messageLineHeight?: number;
+  /** Font family for transcript messages. Omitted uses the shared semantic font. */
+  fontFamily?: string;
+  /** Optional appearance for assistant text displayed after a widget. */
+  postWidgetText?: {
+    tone?: "muted";
+    paragraphPaddingBlock?: number;
+  };
+  /** User bubble line height, in CSS pixels. */
+  userBubbleLineHeight?: number;
+  /** Maximum user bubble width, in CSS pixels. */
+  userBubbleMaxWidth?: number;
+  /** Signed inline offset for the user bubble, in CSS pixels. */
+  userBubbleOffsetInline?: number;
+  /** User bubble padding on the block and inline axes, in CSS pixels. */
+  userBubblePadding?: { block?: number; inline?: number };
+}
+
+/** Optional geometry for the completed-work disclosure row in chat. */
+export interface AgentChatWorkedForRowLayout {
+  /** Chevron width and height, in CSS pixels. */
+  chevronSize?: number;
+  /** Space between the chevron and label, in CSS pixels. */
+  iconGap?: number;
+  /** Signed margin before the row, in CSS pixels. */
+  marginBlockStart?: number;
+  /** Label font size, in CSS pixels. */
+  fontSize?: number;
+  /** Label line height, in CSS pixels. */
+  lineHeight?: number;
+  /** Padding on the block axis, in CSS pixels. */
+  paddingBlock?: number;
+  /** Padding on the inline axis, in CSS pixels. */
+  paddingInline?: number;
+}
+
+function workedForRowLength(
+  value: number | undefined,
+  name: keyof AgentChatWorkedForRowLayout,
+  positive = false,
+) {
+  if (value === undefined) return undefined;
+  if (!Number.isFinite(value) || value < 0 || (positive && value === 0)) {
+    throw new RangeError(
+      `workedForRowLayout.${name} must be a valid CSS length`,
+    );
+  }
+  return `${value}px`;
+}
+
+function workedForRowOffset(
+  value: number | undefined,
+  name: keyof AgentChatWorkedForRowLayout,
+) {
+  if (value === undefined) return undefined;
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`workedForRowLayout.${name} must be finite`);
+  }
+  return `${value}px`;
+}
+
+export function workedForRowSummaryStyle(
+  layout?: AgentChatWorkedForRowLayout,
+): CSSProperties | undefined {
+  if (!layout) return undefined;
+  return {
+    gap: workedForRowLength(layout.iconGap, "iconGap"),
+    marginBlockStart: workedForRowOffset(
+      layout.marginBlockStart,
+      "marginBlockStart",
+    ),
+    fontSize: workedForRowLength(layout.fontSize, "fontSize", true),
+    lineHeight: workedForRowLength(layout.lineHeight, "lineHeight", true),
+    paddingBlock: workedForRowLength(layout.paddingBlock, "paddingBlock"),
+    paddingInline: workedForRowLength(layout.paddingInline, "paddingInline"),
+    fontFamily: "inherit",
+  };
+}
+
+export function workedForRowChevronStyle(
+  layout?: AgentChatWorkedForRowLayout,
+): CSSProperties | undefined {
+  const size = workedForRowLength(layout?.chevronSize, "chevronSize", true);
+  return size ? { width: size, height: size } : undefined;
+}

package/src/app/auth/AuthPage.attribution.spec.tsx

@@ -129,6 +129,12 @@ async function recordBoth(
 
 describe("AuthPage attribution", () => {
   beforeEach(() => {
+    // Attribution storage depends on the visitor's time zone, so pin it.
+    const realOptions = new Intl.DateTimeFormat().resolvedOptions();
+    vi.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions").mockReturnValue({
+      ...realOptions,
+      timeZone: "America/Los_Angeles",
+    });
     vi.useFakeTimers({ toFake: ["Date"] });
     vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
     vi.stubGlobal(

package/src/app/chat/AgentKitAssistantChat.spec.tsx

@@ -1054,6 +1054,27 @@ describe("AgentKitAssistantChat host behavior", () => {
     expect(chatMocks.composerProps.isReferenceTarget).toBe(true);
   });
 
+  it("passes the worked-for row layout into the shared AgentKit root", async () => {
+    const layout = {
+      chevronSize: 12,
+      iconGap: 8,
+      fontSize: 13,
+      lineHeight: 16,
+      paddingBlock: 2,
+      paddingInline: 4,
+    };
+    const formatWorkedForDuration = (durationMs: number) =>
+      `${Math.round(durationMs / 1000)} seconds`;
+    await mount(
+      baseProps({ workedForRowLayout: layout, formatWorkedForDuration }),
+    );
+
+    expect(chatMocks.rootProps.workedForRowLayout).toEqual(layout);
+    expect(chatMocks.rootProps.formatWorkedForDuration).toBe(
+      formatWorkedForDuration,
+    );
+  });
+
   it("reports whether a composer can hold a prefill with its current context", async () => {
     const ref = createRef<AssistantChatHandle>();
     await mount(baseProps(), ref);
@@ -3271,6 +3292,24 @@ describe("AgentKitAssistantChat host behavior", () => {
     ).not.toBeNull();
   });
 
+  it("forwards transcript layout options to the shared chat component", async () => {
+    const transcriptLayout = {
+      topInset: 5,
+      messageLaneWidth: 730,
+      messageLaneOffsetInline: -33,
+      messageGap: 12,
+      messageLineHeight: 20,
+      fontFamily: "IBM Plex Sans",
+      userBubbleLineHeight: 18,
+      userBubbleMaxWidth: 600,
+      userBubbleOffsetInline: 10,
+      userBubblePadding: { block: 8, inline: 13 },
+    };
+    await mount(baseProps({ transcriptLayout }));
+
+    expect(chatMocks.chatProps.transcriptLayout).toBe(transcriptLayout);
+  });
+
   it("anchors the composer at the bottom while restoring a persisted thread", async () => {
     await mount(
       baseProps({
@@ -3348,6 +3387,25 @@ describe("AgentKitAssistantChat host behavior", () => {
     expect(container.querySelector(".agentkit-home-intro")).toBeNull();
   });
 
+  it("renders the shared context banner slot alongside the existing composer slot", async () => {
+    await mount(
+      baseProps({
+        composerSlot: <div data-testid="legacy-composer-slot">Notice</div>,
+        composerContextBannerSlot: (
+          <div data-testid="composer-context-banner-slot">Add context</div>
+        ),
+      }),
+    );
+
+    const composer = container.querySelector(".agentkit-host-composer")!;
+    expect(
+      composer.querySelector('[data-testid="legacy-composer-slot"]'),
+    ).not.toBeNull();
+    expect(
+      composer.querySelector('[data-testid="composer-context-banner-slot"]'),
+    ).not.toBeNull();
+  });
+
   it("puts the beginning revert before messages inside the scrollable transcript", async () => {
     chatMocks.thread.messages = [
       { id: "first-message", role: "user", parts: [] },