@agent-native/toolkit 0.228.0-nightly-20261111212500 → 0.228.0

package/src/app/agentkit/react/composer-context.spec.tsx

@@ -616,6 +616,41 @@ describe("AgentKit composer context submission", () => {
     },
   );
 
+  it.each(["immediate", "queued"] as const)(
+    "sends a custom agent mention as a run reference on %s submissions",
+    async (intent) => {
+      const runtime = transport();
+      if (intent === "queued") withActiveRun(runtime);
+      client = new AgentKitClient({ transport: runtime });
+      if (intent === "queued") await client.loadThread("thread-1");
+      await act(async () =>
+        root.render(
+          <AgentKitProvider controller={client} threadId="thread-1">
+            <AgentKitComposer autoFocus={false} />
+          </AgentKitProvider>,
+        ),
+      );
+      const researcher = {
+        type: "custom-agent" as const,
+        path: "agents/researcher.md",
+        name: "Researcher",
+        source: "agent:custom",
+        refType: "custom-agent",
+        refId: "researcher",
+      };
+      await act(async () => {
+        await capture.props!.onSubmit("Find sources", [], [researcher], {
+          intent,
+        });
+      });
+      const input =
+        intent === "queued"
+          ? runtime.queueMessage.mock.calls[0][0]
+          : runtime.startRun.mock.calls[0][0];
+      expect(input.references).toEqual([researcher]);
+    },
+  );
+
   it.each(["immediate", "queued"] as const)(
     "includes mode instructions without context items in %s submissions",
     async (intent) => {

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

@@ -0,0 +1,353 @@
+import {
+  IconAlertTriangle,
+  IconChevronDown,
+  IconChevronRight,
+} from "@tabler/icons-react";
+import { useId, useState, type CSSProperties, type ReactNode } from "react";
+
+import { COMPOSER_POPOVER_SURFACE_CLASS } from "../../../composer/popover-surface.js";
+import {
+  fallbackContextTranslate,
+  type ContextTranslate,
+} from "../../../context-ui/types.js";
+import { Button } from "../../../ui/button.js";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "../../../ui/popover.js";
+import { Spinner } from "../../../ui/spinner.js";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "../../../ui/tooltip.js";
+
+export const CONTEXT_USAGE_WARNING_FRACTION = 0.8;
+
+export interface ContextUsageSegmentView {
+  kind: string;
+  label: string;
+  tokens: number;
+  color?: string | undefined;
+  colorClass?: string | undefined;
+}
+
+export type ContextCompactState =
+  | { state: "idle" }
+  | { state: "running" }
+  | { state: "done"; message: string }
+  | { state: "error"; message: string };
+
+/** 779.8k, 1M, 1.05M: the window's own unit, never "1000k". */
+export function formatContextWindowTokens(tokens: number): string {
+  const value = Math.max(0, Math.round(tokens));
+  if (value >= 1_000_000) return `${Number((value / 1_000_000).toFixed(2))}M`;
+  if (value >= 1000) return `${Number((value / 1000).toFixed(1))}k`;
+  return String(value);
+}
+
+export function contextUsagePercent(
+  usedTokens: number,
+  windowTokens: number,
+): number {
+  return Math.round((usedTokens / windowTokens) * 100);
+}
+
+function formatWindowShare(tokens: number, windowTokens: number): string {
+  return `${((Math.max(0, tokens) / windowTokens) * 100).toFixed(1)}%`;
+}
+
+const CONTEXT_RING_RADIUS = 7;
+const CONTEXT_RING_CIRCUMFERENCE = 2 * Math.PI * CONTEXT_RING_RADIUS;
+
+export function contextRingDashOffset(fraction: number): number {
+  const share = Math.min(1, Math.max(0, fraction));
+  return CONTEXT_RING_CIRCUMFERENCE * (1 - share);
+}
+
+function segmentStyle(
+  segment: Pick<ContextUsageSegmentView, "color">,
+  width?: string,
+): CSSProperties | undefined {
+  if (!segment.color && !width) return undefined;
+  return {
+    ...(segment.color ? { background: segment.color } : {}),
+    ...(width ? { width } : {}),
+  };
+}
+
+// Never pad a small share or round the caps: a short dash on a track reads as a spinner.
+function ContextRing({
+  fraction,
+  warning,
+}: {
+  fraction: number;
+  warning: boolean;
+}) {
+  return (
+    <svg
+      aria-hidden="true"
+      viewBox="0 0 20 20"
+      className="agentkit-context-ring"
+      data-context-ring=""
+    >
+      <circle
+        cx="10"
+        cy="10"
+        r={CONTEXT_RING_RADIUS}
+        fill="none"
+        strokeWidth="3"
+        className="agentkit-context-ring-track"
+        data-context-ring-track=""
+      />
+      <circle
+        cx="10"
+        cy="10"
+        r={CONTEXT_RING_RADIUS}
+        fill="none"
+        strokeWidth="3"
+        strokeLinecap="butt"
+        strokeDasharray={CONTEXT_RING_CIRCUMFERENCE}
+        strokeDashoffset={contextRingDashOffset(fraction)}
+        className="agentkit-context-ring-fill"
+        data-warning={warning ? "true" : undefined}
+        data-context-ring-fill=""
+      />
+    </svg>
+  );
+}
+
+/** Opens `children`, usually `ContextUsagePanel`, in a popover. */
+export function ContextUsageRing({
+  usedTokens,
+  windowTokens,
+  open,
+  onOpenChange,
+  children,
+  translate = fallbackContextTranslate,
+}: {
+  usedTokens: number;
+  windowTokens: number;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  children: ReactNode;
+  translate?: ContextTranslate;
+}) {
+  const fraction = usedTokens / windowTokens;
+  const warning = fraction >= CONTEXT_USAGE_WARNING_FRACTION;
+  const label = translate("agentChat.contextRing.usedLabel", {
+    defaultValue: "Context {{percent}}% used",
+    percent: contextUsagePercent(usedTokens, windowTokens),
+  });
+  return (
+    <TooltipProvider delayDuration={200}>
+      <Popover open={open} onOpenChange={onOpenChange}>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <PopoverTrigger asChild>
+              <button
+                type="button"
+                aria-label={label}
+                data-agent-composer-slot="context-ring"
+                data-warning={warning ? "true" : undefined}
+                data-state={open ? "open" : "closed"}
+                className="agentkit-context-ring-trigger"
+              >
+                <ContextRing fraction={fraction} warning={warning} />
+              </button>
+            </PopoverTrigger>
+          </TooltipTrigger>
+          <TooltipContent>{label}</TooltipContent>
+        </Tooltip>
+        <PopoverContent
+          side="top"
+          align="end"
+          sideOffset={6}
+          collisionPadding={8}
+          data-agent-native-composer-popover="true"
+          // Portaled outside the chat, so it needs `agentkit-tokens` itself.
+          className={`agentkit-tokens w-[min(calc(100vw-2rem),22rem)] ${COMPOSER_POPOVER_SURFACE_CLASS}`}
+        >
+          {children}
+        </PopoverContent>
+      </Popover>
+    </TooltipProvider>
+  );
+}
+
+export function ContextUsagePanel({
+  usedTokens,
+  windowTokens,
+  segments,
+  tokensUntilAutoCompact,
+  compact,
+  onCompact,
+  translate = fallbackContextTranslate,
+}: {
+  usedTokens: number;
+  windowTokens: number;
+  segments: readonly ContextUsageSegmentView[];
+  /** Omitted when no automatic threshold applies or it could not be read. */
+  tokensUntilAutoCompact?: number | undefined;
+  compact: ContextCompactState;
+  onCompact?: (() => void) | undefined;
+  translate?: ContextTranslate;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const breakdownId = useId();
+  const percent = contextUsagePercent(usedTokens, windowTokens);
+  const warning = usedTokens / windowTokens >= CONTEXT_USAGE_WARNING_FRACTION;
+  const barTotal = Math.max(usedTokens, windowTokens);
+  const breakdownLabel = translate("agentChat.contextRing.breakdown", {
+    defaultValue: "Breakdown",
+  });
+  const rows: ContextUsageSegmentView[] = [
+    ...segments,
+    {
+      kind: "free-space",
+      label: translate("agentChat.contextRing.freeSpace", {
+        defaultValue: "Free space",
+      }),
+      tokens: Math.max(0, windowTokens - usedTokens),
+    },
+  ];
+  return (
+    <div className="agentkit-context-usage" data-context-usage-panel="">
+      <div className="agentkit-context-usage-header">
+        <span className="agentkit-context-usage-title">
+          {translate("agentChat.contextRing.title", {
+            defaultValue: "Context window",
+          })}
+        </span>
+        <span className="agentkit-context-usage-total">
+          {translate("agentChat.contextRing.usage", {
+            defaultValue: "{{used}} / {{window}} ({{percent}}%)",
+            used: formatContextWindowTokens(usedTokens),
+            window: formatContextWindowTokens(windowTokens),
+            percent,
+          })}
+        </span>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-xs"
+          className="agentkit-context-usage-toggle rounded-[var(--agent-kit-radius-xs,0.25rem)]"
+          aria-label={breakdownLabel}
+          aria-expanded={expanded}
+          aria-controls={breakdownId}
+          onClick={() => setExpanded((current) => !current)}
+        >
+          {expanded ? (
+            <IconChevronDown aria-hidden="true" className="agentkit-icon" />
+          ) : (
+            <IconChevronRight aria-hidden="true" className="agentkit-icon" />
+          )}
+        </Button>
+      </div>
+      <div
+        role="img"
+        aria-label={segments
+          .map(
+            (segment) =>
+              `${segment.label} ${formatContextWindowTokens(segment.tokens)}`,
+          )
+          .join(", ")}
+        className="agentkit-context-usage-bar"
+        data-context-usage-bar=""
+      >
+        {segments.map((segment) => (
+          <span
+            key={segment.kind}
+            data-context-usage-segment={segment.kind}
+            className={segment.colorClass}
+            style={segmentStyle(
+              segment,
+              `${(segment.tokens / barTotal) * 100}%`,
+            )}
+          />
+        ))}
+      </div>
+      <div
+        id={breakdownId}
+        hidden={!expanded}
+        className="agentkit-context-usage-breakdown"
+        data-context-usage-breakdown=""
+      >
+        <table>
+          <tbody>
+            {rows.map((row) => (
+              <tr key={row.kind} data-context-usage-row={row.kind}>
+                <td>
+                  <span
+                    aria-hidden="true"
+                    data-context-usage-swatch=""
+                    className={
+                      row.colorClass
+                        ? `agentkit-context-usage-swatch ${row.colorClass}`
+                        : "agentkit-context-usage-swatch"
+                    }
+                    style={segmentStyle(row)}
+                  />
+                </td>
+                <td>{row.label}</td>
+                <td>{formatContextWindowTokens(row.tokens)}</td>
+                <td>{formatWindowShare(row.tokens, windowTokens)}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      {tokensUntilAutoCompact !== undefined ? (
+        <p
+          className="agentkit-context-usage-caption"
+          data-warning={warning ? "true" : undefined}
+        >
+          {warning ? (
+            <IconAlertTriangle aria-hidden="true" className="agentkit-icon" />
+          ) : null}
+          {translate("agentChat.contextRing.untilAutoCompact", {
+            defaultValue: "{{tokens}} until auto-compact",
+            tokens: formatContextWindowTokens(tokensUntilAutoCompact),
+          })}
+        </p>
+      ) : null}
+      {compact.state === "done" ? (
+        <p role="status" className="agentkit-context-usage-caption">
+          {compact.message}
+        </p>
+      ) : null}
+      {compact.state === "error" ? (
+        <p
+          role="alert"
+          className="agentkit-context-usage-caption"
+          data-warning="true"
+        >
+          <IconAlertTriangle aria-hidden="true" className="agentkit-icon" />
+          <span>{compact.message}</span>
+        </p>
+      ) : null}
+      {onCompact ? (
+        <div className="agentkit-context-usage-actions">
+          <Button
+            type="button"
+            variant="outline"
+            size="xs"
+            className="rounded-[var(--agent-kit-radius-xs,0.25rem)]"
+            disabled={compact.state === "running"}
+            aria-busy={compact.state === "running" || undefined}
+            onClick={onCompact}
+          >
+            {compact.state === "running" ? (
+              <Spinner className="size-3" />
+            ) : null}
+            {translate("agentChat.contextRing.compactNow", {
+              defaultValue: "Compact now",
+            })}
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

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

@@ -47,6 +47,7 @@ import {
 } from "react";
 
 import type { AgentChatDataChartLayout } from "./data-chart-layout.js";
+import { formatAgentKitDuration } from "./duration.js";
 import type { AgentMessageContentOrderResolver } from "./message-content-order.js";
 import {
   AGENTKIT_CLIENT_REQUEST_ID_METADATA_KEY,
@@ -263,6 +264,23 @@ export interface AgentKitLabels {
   workStepReadPagesOther: string;
   workStepFetchedOne: string;
   workStepFetchedOther: string;
+  /** A message's citations: "Used 1 source", "Used {{count}} sources". */
+  workStepSourcesOne: string;
+  workStepSourcesOther: string;
+  /** A folded run of two or more framework frames in a stack trace. */
+  workStepFrameworkFrames: string;
+  workStepCopyStackTrace: string;
+  /** Takes {{code}}; shown only for a nonzero exit. */
+  workStepTerminalExitCode: string;
+  workStepTerminalTimedOut: string;
+  workStepTerminalEarlierLines: string;
+  workStepCopyOutput: string;
+  /** A file change cut short in what was kept. */
+  workStepFilePartial: string;
+  workStepFileMoreLines: string;
+  /** Screen-reader prefix for an added or removed diff line. */
+  workStepLineAdded: string;
+  workStepLineRemoved: string;
   workStepReadFilesOne: string;
   workStepReadFilesOther: string;
   workStepEditedOne: string;
@@ -286,6 +304,19 @@ export interface AgentKitLabels {
   durationSecondShort: string;
   agents: string;
   tasks: string;
+  tasksProgress: string;
+  question: string;
+  questionProgress: string;
+  questionProgressLabel: string;
+  questionOwnResponse: string;
+  questionAnswer: string;
+  questionSkip: string;
+  questionNext: string;
+  questionSend: string;
+  questionRecommended: string;
+  questionDismiss: string;
+  questionChooseFiles: string;
+  questionRemoveFile: string;
   toolInput?: string;
   toolResult?: string;
   activityValueIdentifierHidden?: string;
@@ -383,6 +414,8 @@ export interface AgentKitLabels {
   dropFilesToAttach: string;
   dropFileFailed: string;
   scrollToBottom: string;
+  /** Skip link past the transcript; visible only when focused. */
+  skipToComposer: string;
   formatTimestamp?: (createdAt: string) => string;
   error: string;
   renderError: string;
@@ -399,6 +432,8 @@ export interface AgentKitLabels {
   agentResumed: string;
   agentMessaged: string;
   agentDelegated: string;
+  agentWorking: string;
+  agentWorkedFor: string;
   agentPaused: string;
   agentCompleted: string;
   agentFailed: string;
@@ -474,6 +509,18 @@ export const defaultAgentKitLabels: ResolvedAgentKitLabels = {
   workStepReadPagesOther: "Read {{count}} pages",
   workStepFetchedOne: "Fetched 1 URL",
   workStepFetchedOther: "Fetched {{count}} URLs",
+  workStepSourcesOne: "Used 1 source",
+  workStepSourcesOther: "Used {{count}} sources",
+  workStepFrameworkFrames: "{{count}} framework frames",
+  workStepCopyStackTrace: "Copy stack trace",
+  workStepTerminalExitCode: "Exit code {{code}}",
+  workStepTerminalTimedOut: "Timed out",
+  workStepTerminalEarlierLines: "Show {{count}} earlier lines",
+  workStepCopyOutput: "Copy output",
+  workStepFilePartial: "Partial",
+  workStepFileMoreLines: "Show {{count}} more lines",
+  workStepLineAdded: "Added",
+  workStepLineRemoved: "Removed",
   workStepReadFilesOne: "Read 1 file",
   workStepReadFilesOther: "Read {{count}} files",
   workStepEditedOne: "Edited 1 file",
@@ -496,6 +543,19 @@ export const defaultAgentKitLabels: ResolvedAgentKitLabels = {
   durationSecondShort: "s",
   agents: "Agent collaboration",
   tasks: "Agent tasks",
+  tasksProgress: "{{completed}} of {{total}} done",
+  question: "Question",
+  questionProgress: "{{current}}/{{total}}",
+  questionProgressLabel: "{{current}} of {{total}}",
+  questionOwnResponse: "Or write your own response",
+  questionAnswer: "Write your answer",
+  questionSkip: "Skip",
+  questionNext: "Next",
+  questionSend: "Send",
+  questionRecommended: "Recommended",
+  questionDismiss: "Dismiss questions",
+  questionChooseFiles: "Choose files…",
+  questionRemoveFile: "Remove {{name}}",
   toolInput: "Input",
   toolResult: "Result",
   activityValueIdentifierHidden: "[Identifier hidden]",
@@ -590,6 +650,7 @@ export const defaultAgentKitLabels: ResolvedAgentKitLabels = {
   dropFilesToAttach: "Drop files to attach",
   dropFileFailed: "Could not add the dropped file. Try a different format.",
   scrollToBottom: "Scroll to bottom",
+  skipToComposer: "Skip to message box",
   error: "Something went wrong",
   renderError: "This content couldn’t be displayed.",
   runFailed: "Run failed",
@@ -605,6 +666,8 @@ export const defaultAgentKitLabels: ResolvedAgentKitLabels = {
   agentResumed: "resumed working",
   agentMessaged: "sent a message",
   agentDelegated: "delegated work",
+  agentWorking: "working",
+  agentWorkedFor: "worked for {{duration}}",
   agentPaused: "paused",
   agentCompleted: "finished",
   agentFailed: "needs attention",
@@ -710,6 +773,10 @@ export interface AgentKitProviderProps {
   workedForRowLayout?: AgentChatWorkedForRowLayout;
   dataChartLayout?: AgentChatDataChartLayout;
   formatWorkedForDuration?: (durationMs: number) => string;
+  /** Detail beside an interaction row's label; undefined keeps its own. */
+  formatAgentInteractionDetail?: (
+    interaction: AgentInteraction,
+  ) => string | undefined;
   /** Display name for a model id in run details; the id shows without it. */
   formatModelName?: (model: string) => string;
   onClientEffect?: (effect: {
@@ -738,7 +805,7 @@ export interface AgentKitThreadLoadState {
   retry?: () => void;
 }
 
-interface ResolvedAgentKitLabels extends AgentKitLabels {
+export interface ResolvedAgentKitLabels extends AgentKitLabels {
   toolInput: string;
   toolResult: string;
   queueSendNow: string;
@@ -768,6 +835,9 @@ export interface AgentKitContextValue {
   workedForRowLayout?: AgentChatWorkedForRowLayout;
   dataChartLayout?: AgentChatDataChartLayout;
   formatWorkedForDuration?: (durationMs: number) => string;
+  formatAgentInteractionDetail?: (
+    interaction: AgentInteraction,
+  ) => string | undefined;
   formatModelName?: (model: string) => string;
   registerComposerFocus: (threadId: ThreadId, focus: () => void) => () => void;
   requestComposerFocus: (threadId: ThreadId) => void;
@@ -856,6 +926,7 @@ export function AgentKitProvider({
   workedForRowLayout: workedForRowLayoutInput,
   dataChartLayout: dataChartLayoutInput,
   formatWorkedForDuration,
+  formatAgentInteractionDetail,
   formatModelName: formatModelNameInput,
   onClientEffect: onClientEffectInput,
   threadLoad,
@@ -971,6 +1042,7 @@ export function AgentKitProvider({
       workedForRowLayout,
       dataChartLayout,
       formatWorkedForDuration,
+      formatAgentInteractionDetail,
       formatModelName,
       registerComposerFocus,
       requestComposerFocus,
@@ -994,6 +1066,7 @@ export function AgentKitProvider({
       workedForRowLayout,
       dataChartLayout,
       formatWorkedForDuration,
+      formatAgentInteractionDetail,
       formatModelName,
       registerComposerFocus,
       requestComposerFocus,
@@ -1135,6 +1208,25 @@ function useAgentKitControllerSnapshot(
   );
 }
 
+/** Falls back to English defaults so parts also work outside a provider. */
+export function useAgentKitLabels(): ResolvedAgentKitLabels {
+  return useContext(AgentKitContext)?.labels ?? defaultAgentKitLabels;
+}
+
+export function useAgentKitDurationFormat(): (durationMs: number) => string {
+  const value = useContext(AgentKitContext);
+  const labels = value?.labels ?? defaultAgentKitLabels;
+  return (
+    value?.formatWorkedForDuration ??
+    ((durationMs) =>
+      formatAgentKitDuration(durationMs, {
+        hour: labels.durationHourShort,
+        minute: labels.durationMinuteShort,
+        second: labels.durationSecondShort,
+      }))
+  );
+}
+
 export function useAgentKit(): AgentKitContextValue {
   const value = useContext(AgentKitContext);
   if (!value) throw new Error("AgentKit hooks require an AgentKitProvider.");

package/src/app/agentkit/react/disclosure-content.ts

@@ -0,0 +1,42 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
+
+import { scheduleIdleMount } from "./idle-mount.js";
+
+/** True while a long thread opens, so closed rows can mount later. */
+export const AgentKitDeferClosedContentContext = createContext(false);
+
+/**
+ * Keeps closed content mounted for find-in-page; in a long thread it mounts
+ * at idle, so the history paints first.
+ */
+export function useUntilFoundContent(
+  open: boolean,
+  onReveal: (() => void) | undefined,
+): { ref: RefObject<HTMLDivElement | null>; mounted: boolean } {
+  const ref = useRef<HTMLDivElement>(null);
+  const revealRef = useRef(onReveal);
+  revealRef.current = onReveal;
+  const deferClosed = useContext(AgentKitDeferClosedContentContext);
+  const [contentMounted, setContentMounted] = useState(open || !deferClosed);
+  if (open && !contentMounted) setContentMounted(true);
+  useEffect(() => {
+    if (contentMounted) return;
+    return scheduleIdleMount(() => setContentMounted(true));
+  }, [contentMounted]);
+  useEffect(() => {
+    const element = ref.current;
+    if (!element || open) return;
+    element.setAttribute("hidden", "until-found");
+    const reveal = () => revealRef.current?.();
+    element.addEventListener("beforematch", reveal);
+    return () => element.removeEventListener("beforematch", reveal);
+  }, [open]);
+  return { ref, mounted: contentMounted || open };
+}