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

package/src/app/agentkit/react/disclosures.spec.tsx

@@ -153,9 +153,14 @@ async function click(element: Element | null | undefined) {
 
 function expectSharedSummary(trigger: HTMLElement | null) {
   expect(trigger?.tagName).toBe("BUTTON");
-  const children = Array.from(trigger?.children ?? []).map(
-    (child) => child.classList[child.classList.length - 1],
-  );
+  // A trace line is `display: contents`: its parts are the summary's boxes.
+  const children = Array.from(trigger?.children ?? [])
+    .flatMap((child) =>
+      child.classList.contains("agentkit-trace-line")
+        ? Array.from(child.children)
+        : [child],
+    )
+    .map((child) => child.classList[child.classList.length - 1]);
   // Icon column first, then the label, then the chevron right after it.
   expect(children).toEqual([
     "agentkit-disclosure-icon-slot",
@@ -224,7 +229,10 @@ describe("AgentKit disclosures", () => {
     );
     expect(item.textContent).toContain("First file contents");
     await click(itemTrigger);
-    expect(item.querySelector(".agentkit-activity-summary")).toBeNull();
+    // Closed, it stays in the DOM for find-in-page.
+    expect(
+      item.querySelector(".agentkit-activity-summary")?.getAttribute("hidden"),
+    ).toBe("until-found");
 
     // A row with nothing to expand is text, not a disabled button.
     const plain = work.querySelectorAll<HTMLElement>(
@@ -1028,3 +1036,53 @@ describe("a turn that only answered", () => {
     ).toBe("Worked for 4s");
   });
 });
+
+describe("Sources", () => {
+  const cited = answer([
+    { type: "text", text: "The release shipped on Tuesday." },
+    { type: "citation", title: "Release notes", url: "https://example.com/r" },
+    { type: "citation", title: "Release notes", url: "https://example.com/r" },
+    { type: "citation", title: "", url: "https://docs.example.com/guide" },
+  ]);
+
+  it("collapses a message's citations into one deduped sources step", async () => {
+    const view = await renderThread([user, cited], eventsOf([], cited));
+    const sources = view.querySelector<HTMLElement>(".agentkit-sources");
+    const trigger = sources?.querySelector<HTMLElement>(
+      "button.agentkit-disclosure-summary",
+    );
+    expectSharedSummary(trigger ?? null);
+    expect(trigger?.textContent).toBe("Used 2 sources");
+    expect(trigger?.getAttribute("aria-expanded")).toBe("false");
+
+    // Closed sources stay findable in the page.
+    const content = sources?.querySelector<HTMLElement>(
+      '[data-slot="trace-collapsible-content"]',
+    );
+    expect(content?.getAttribute("hidden")).toBe("until-found");
+    const links = Array.from(
+      content?.querySelectorAll<HTMLAnchorElement>("a") ?? [],
+      (link) => [link.textContent, link.getAttribute("href")],
+    );
+    expect(links).toEqual([
+      ["Release notes", "https://example.com/r"],
+      ["docs.example.com", "https://docs.example.com/guide"],
+    ]);
+
+    await click(trigger);
+    expect(trigger?.getAttribute("aria-expanded")).toBe("true");
+    expect(content?.hidden).toBe(false);
+  });
+
+  it("names a single source in the singular", async () => {
+    const one = answer([
+      { type: "text", text: "See the guide." },
+      { type: "citation", title: "Guide", url: "https://example.com/g" },
+    ]);
+    const view = await renderThread([user, one], eventsOf([], one));
+    expect(
+      view.querySelector(".agentkit-sources .agentkit-disclosure-label")
+        ?.textContent,
+    ).toBe("Used 1 source");
+  });
+});

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

@@ -0,0 +1,22 @@
+export function formatAgentKitDuration(
+  ms: number,
+  units: { hour?: string; minute?: string; second?: string } = {},
+): string {
+  const hour = units.hour ?? "h";
+  const minute = units.minute ?? "m";
+  const second = units.second ?? "s";
+  const totalSeconds = Math.max(0, Math.round(ms / 1_000));
+  if (totalSeconds < 60) return `${Math.max(1, totalSeconds)}${second}`;
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes < 60) {
+    return seconds === 0
+      ? `${minutes}${minute}`
+      : `${minutes}${minute} ${seconds}${second}`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return remainingMinutes === 0
+    ? `${hours}${hour}`
+    : `${hours}${hour} ${remainingMinutes}${minute}`;
+}

package/src/app/agentkit/react/file-change.spec.tsx

@@ -0,0 +1,124 @@
+// @vitest-environment happy-dom
+
+import { act, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { FileChange } from "./file-change.js";
+import { computeLineDiff } from "./file-diff.js";
+
+let root: Root;
+let container: HTMLDivElement;
+
+beforeEach(() => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.unstubAllGlobals();
+});
+
+async function render(node: ReactNode) {
+  await act(async () => root.render(node));
+}
+
+const lines = (count: number) =>
+  Array.from({ length: count }, (_, index) => `line ${index + 1}`).join("\n");
+
+describe("FileChange", () => {
+  it("shows an edit as a diff with markers instead of colors alone", async () => {
+    await render(
+      <FileChange
+        defaultOpen
+        change={{
+          kind: "edit",
+          filePath: "src/app.ts",
+          oldText: "const a = 1;\nexport { a };",
+          newText: "const a = 2;\nexport { a };",
+        }}
+      />,
+    );
+    expect(
+      Array.from(
+        container.querySelectorAll<HTMLElement>(".agentkit-code-line"),
+        (line) => line.dataset.variant ?? "context",
+      ),
+    ).toEqual(["removed", "added", "context"]);
+    expect(container.querySelector("pre")?.textContent).toBe(
+      "Removed const a = 1;\nAdded const a = 2;\nexport { a };",
+    );
+    expect(
+      container.querySelector("[data-agent-file-change-stats]")?.textContent,
+    ).toBe("+1−1");
+  });
+
+  it("shows a new file with line numbers and its first 40 lines", async () => {
+    await render(
+      <FileChange
+        defaultOpen
+        change={{ kind: "write", filePath: "src/new.ts", content: lines(45) }}
+      />,
+    );
+    const pre = () => container.querySelector("pre");
+    expect(pre()?.dataset.lineNumbers).toBe("true");
+    expect(pre()?.querySelector("code")?.dataset.language).toBe("ts");
+    expect(pre()?.textContent?.split("\n")).toHaveLength(40);
+    const more = container.querySelector<HTMLButtonElement>(
+      ".agentkit-code-block-footer button",
+    );
+    expect(more?.textContent).toBe("Show 5 more lines");
+    await act(async () => more?.click());
+    expect(pre()?.textContent?.split("\n")).toHaveLength(45);
+    expect(
+      container.querySelector("[data-agent-file-change-stats]")?.textContent,
+    ).toBe("+45");
+  });
+
+  it("marks a cut-short change and hides counts while it runs", async () => {
+    await render(
+      <FileChange
+        change={{
+          kind: "write",
+          filePath: "big.json",
+          lineCount: 9000,
+          truncated: true,
+        }}
+      />,
+    );
+    // Nothing was kept, so there is nothing to open.
+    expect(container.querySelector("button")).toBeNull();
+    expect(
+      container.querySelector("[data-agent-file-change-stats]")?.textContent,
+    ).toBe("+9000Partial");
+
+    await render(
+      <FileChange
+        running
+        change={{ kind: "edit", filePath: "a.ts", oldText: "a", newText: "b" }}
+      />,
+    );
+    expect(
+      container.querySelector("[data-agent-file-change-stats]"),
+    ).toBeNull();
+    expect(
+      container
+        .querySelector('[data-slot="trace-line"]')
+        ?.getAttribute("data-trace-status"),
+    ).toBe("running");
+  });
+});
+
+describe("computeLineDiff", () => {
+  it("keeps an unchanged line after an edit as context", () => {
+    expect(
+      computeLineDiff("a\nshared\nb", "A\nshared\nB").map(
+        (line) => `${line.kind[0]}${line.text}`,
+      ),
+    ).toEqual(["ra", "aA", "cshared", "rb", "aB"]);
+  });
+});

package/src/app/agentkit/react/file-change.tsx

@@ -0,0 +1,228 @@
+import { IconFileDiff, IconFilePlus } from "@tabler/icons-react";
+import { useMemo, useState } from "react";
+
+import {
+  CodeBlock,
+  CodeBlockContent,
+  CodeBlockFooter,
+  CodeBlockLine,
+} from "./code-block.js";
+import { useAgentKitLabels } from "./context.js";
+import { cachedLineDiff, diffStats } from "./file-diff.js";
+import {
+  TraceCollapsible,
+  TraceCollapsibleContent,
+  TraceCollapsibleTrigger,
+  TraceDescription,
+  TraceIcon,
+  TraceLine,
+  TraceTitle,
+  type TraceCollapsibleOpenProps,
+} from "./trace.js";
+
+const MAX_COLLAPSED_LINES = 40;
+
+const EXTENSION_LANGUAGES: Record<string, string> = {
+  mjs: "javascript",
+  cjs: "javascript",
+  mts: "typescript",
+  cts: "typescript",
+  htm: "html",
+  zsh: "bash",
+};
+
+export interface FileChangeData {
+  filePath: string;
+  /** `edit` uses `oldText` and `newText`; `write` uses `content`. */
+  kind: "edit" | "write";
+  oldText?: string | undefined;
+  newText?: string | undefined;
+  content?: string | undefined;
+  /** A write's line count when its content was not kept. */
+  lineCount?: number | undefined;
+  truncated?: boolean | undefined;
+}
+
+export function fileChangeStats(change: FileChangeData): {
+  added: number;
+  removed: number;
+} {
+  if (change.kind === "write") {
+    return {
+      added:
+        change.lineCount ??
+        (change.content ? change.content.split("\n").length : 0),
+      removed: 0,
+    };
+  }
+  if (!change.oldText && !change.newText) return { added: 0, removed: 0 };
+  return diffStats(cachedLineDiff(change.oldText ?? "", change.newText ?? ""));
+}
+
+function fileLanguage(filePath: string): string | undefined {
+  const name = filePath.split(/[/\\]/).at(-1) ?? "";
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return undefined;
+  const extension = name.slice(dot + 1).toLowerCase();
+  return EXTENSION_LANGUAGES[extension] ?? extension;
+}
+
+/** A long directory truncates before the file name does. */
+export function FilePath({ filePath }: { filePath: string }) {
+  const separator = filePath.lastIndexOf("/");
+  const directory = separator < 0 ? "" : filePath.slice(0, separator + 1);
+  const fileName = separator < 0 ? filePath : filePath.slice(separator + 1);
+  return (
+    <TraceTitle
+      className="agentkit-file-path"
+      title={filePath}
+      data-agent-file-change-path=""
+    >
+      {directory ? (
+        <span className="agentkit-file-path-directory">{directory}</span>
+      ) : null}
+      <span className="agentkit-file-path-name">{fileName}</span>
+    </TraceTitle>
+  );
+}
+
+export function FileChangeStats({ change }: { change: FileChangeData }) {
+  const labels = useAgentKitLabels();
+  const { added, removed } = fileChangeStats(change);
+  return (
+    <TraceDescription
+      className="agentkit-file-change-stats"
+      data-agent-file-change-stats=""
+    >
+      <span data-sign="added">+{added}</span>
+      {change.kind === "edit" ? (
+        <span data-sign="removed">−{removed}</span>
+      ) : null}
+      {change.truncated ? <span>{labels.workStepFilePartial}</span> : null}
+    </TraceDescription>
+  );
+}
+
+export function FileChangeBody({ change }: { change: FileChangeData }) {
+  const labels = useAgentKitLabels();
+  const [showAll, setShowAll] = useState(false);
+  const diff = useMemo(
+    () =>
+      change.kind === "edit" && (change.oldText || change.newText)
+        ? cachedLineDiff(change.oldText ?? "", change.newText ?? "")
+        : undefined,
+    [change.kind, change.oldText, change.newText],
+  );
+  const lines = diff ?? (change.content ? change.content.split("\n") : []);
+  if (!lines.length) return null;
+  const hidden = showAll ? 0 : Math.max(0, lines.length - MAX_COLLAPSED_LINES);
+  const footer = hidden ? (
+    <CodeBlockFooter>
+      <button
+        type="button"
+        className="agentkit-terminal-earlier"
+        onClick={() => setShowAll(true)}
+      >
+        {labels.workStepFileMoreLines.replace("{{count}}", () => `${hidden}`)}
+      </button>
+    </CodeBlockFooter>
+  ) : null;
+  if (diff) {
+    const visible = hidden ? diff.slice(0, MAX_COLLAPSED_LINES) : diff;
+    return (
+      <CodeBlock size="sm" className="agentkit-file-change-body">
+        <CodeBlockContent wrap>
+          {visible.map((line, index) => (
+            <CodeBlockLine
+              key={index}
+              variant={line.kind === "context" ? "default" : line.kind}
+            >
+              {line.text}
+            </CodeBlockLine>
+          ))}
+        </CodeBlockContent>
+        {footer}
+      </CodeBlock>
+    );
+  }
+  const content = change.content ?? "";
+  return (
+    <CodeBlock size="sm" className="agentkit-file-change-body">
+      <CodeBlockContent
+        wrap
+        lineNumbers
+        language={fileLanguage(change.filePath)}
+      >
+        {hidden
+          ? content.split("\n").slice(0, MAX_COLLAPSED_LINES).join("\n")
+          : content}
+      </CodeBlockContent>
+      {footer}
+    </CodeBlock>
+  );
+}
+
+export function FileChange({
+  change,
+  running = false,
+  defaultOpen = false,
+  className,
+  ...openProps
+}: TraceCollapsibleOpenProps & {
+  change: FileChangeData;
+  running?: boolean;
+  defaultOpen?: boolean;
+  className?: string;
+}) {
+  const labels = useAgentKitLabels();
+  const hasBody =
+    change.kind === "edit"
+      ? Boolean(change.oldText || change.newText)
+      : Boolean(change.content);
+  const line = (
+    <TraceLine status={running ? "running" : undefined}>
+      <TraceIcon>
+        {change.kind === "edit" ? (
+          <IconFileDiff aria-hidden="true" className="agentkit-icon" />
+        ) : (
+          <IconFilePlus aria-hidden="true" className="agentkit-icon" />
+        )}
+      </TraceIcon>
+      <FilePath filePath={change.filePath} />
+      {running ? (
+        <span className="agentkit-visually-hidden">
+          {labels.taskStatusRunning}
+        </span>
+      ) : (
+        <FileChangeStats change={change} />
+      )}
+    </TraceLine>
+  );
+  const classes = className
+    ? `agentkit-file-change ${className}`
+    : "agentkit-file-change";
+  if (!hasBody) {
+    return (
+      <div className={classes} data-kind={change.kind}>
+        <span className="agentkit-disclosure-summary" data-expandable="false">
+          {line}
+        </span>
+      </div>
+    );
+  }
+  return (
+    <TraceCollapsible
+      {...openProps}
+      defaultOpen={defaultOpen}
+      className={classes}
+      data-kind={change.kind}
+    >
+      <TraceCollapsibleTrigger data-agent-file-change-row="">
+        {line}
+      </TraceCollapsibleTrigger>
+      <TraceCollapsibleContent className="agentkit-file-change-content">
+        <FileChangeBody change={change} />
+      </TraceCollapsibleContent>
+    </TraceCollapsible>
+  );
+}

package/src/app/agentkit/react/file-diff.ts

@@ -0,0 +1,110 @@
+export interface DiffLine {
+  kind: "context" | "added" | "removed";
+  text: string;
+  oldLineNo?: number;
+  newLineNo?: number;
+}
+
+export function computeLineDiff(oldText: string, newText: string): DiffLine[] {
+  const oldLines = oldText.split("\n");
+  const newLines = newText.split("\n");
+
+  const MAX_LINES = 2000;
+  const a = oldLines.slice(0, MAX_LINES);
+  const b = newLines.slice(0, MAX_LINES);
+
+  const m = a.length;
+  const n = b.length;
+
+  // LCS of suffixes: cell(i, j) covers a[i..] against b[j..].
+  const width = n + 1;
+  const lengths = new Uint32Array((m + 1) * width);
+  const cell = (row: number, column: number) =>
+    lengths.at(row * width + column) ?? 0;
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      lengths[i * width + j] =
+        a.at(i) === b.at(j)
+          ? cell(i + 1, j + 1) + 1
+          : Math.max(cell(i + 1, j), cell(i, j + 1));
+    }
+  }
+
+  const result: DiffLine[] = [];
+  let i = 0;
+  let j = 0;
+  let oldLineNo = 1;
+  let newLineNo = 1;
+
+  for (;;) {
+    const left = a.at(i);
+    const right = b.at(j);
+    if (left === undefined && right === undefined) break;
+    if (left !== undefined && left === right) {
+      result.push({
+        kind: "context",
+        text: left,
+        oldLineNo: oldLineNo++,
+        newLineNo: newLineNo++,
+      });
+      i++;
+      j++;
+    } else if (
+      left !== undefined &&
+      (right === undefined || cell(i + 1, j) >= cell(i, j + 1))
+    ) {
+      // Ties remove first, so removals precede the additions replacing them.
+      result.push({ kind: "removed", text: left, oldLineNo: oldLineNo++ });
+      i++;
+    } else if (right !== undefined) {
+      result.push({ kind: "added", text: right, newLineNo: newLineNo++ });
+      j++;
+    }
+  }
+
+  for (const text of oldLines.slice(MAX_LINES)) {
+    result.push({ kind: "removed", text, oldLineNo: oldLineNo++ });
+  }
+  for (const text of newLines.slice(MAX_LINES)) {
+    result.push({ kind: "added", text, newLineNo: newLineNo++ });
+  }
+
+  return result;
+}
+
+export function diffStats(lines: DiffLine[]): {
+  added: number;
+  removed: number;
+} {
+  let added = 0;
+  let removed = 0;
+  for (const line of lines) {
+    if (line.kind === "added") added++;
+    else if (line.kind === "removed") removed++;
+  }
+  return { added, removed };
+}
+
+const CACHED_DIFFS = 32;
+const cachedDiffs = new Map<string, DiffLine[]>();
+
+/**
+ * `computeLineDiff`, cached by text: a row's stats and its body share one
+ * quadratic pass, and a re-render reuses it.
+ */
+export function cachedLineDiff(oldText: string, newText: string): DiffLine[] {
+  const key = `${oldText.length}:${oldText}\u0000${newText}`;
+  const cached = cachedDiffs.get(key);
+  if (cached) {
+    cachedDiffs.delete(key);
+    cachedDiffs.set(key, cached);
+    return cached;
+  }
+  const diff = computeLineDiff(oldText, newText);
+  cachedDiffs.set(key, diff);
+  if (cachedDiffs.size > CACHED_DIFFS) {
+    const oldest = cachedDiffs.keys().next();
+    if (!oldest.done) cachedDiffs.delete(oldest.value);
+  }
+  return diff;
+}

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

@@ -1,8 +1,12 @@
 export * from "./approval-card.js";
+export * from "./question-card.js";
 export * from "./chat.js";
+export * from "./code-block.js";
 export * from "./components.js";
+export * from "./context-usage.js";
 export * from "./context.js";
 export * from "./data-chart-layout.js";
+export * from "./file-change.js";
 export * from "./message-content-order.js";
 export {
   AGENTKIT_CLIENT_REQUEST_ID_METADATA_KEY,
@@ -12,6 +16,9 @@ export {
   type AgentKitPendingSubmissionFile,
 } from "./pending-submissions.js";
 export * from "./root.js";
+export * from "./stack-trace.js";
 export * from "./streaming-text.js";
+export * from "./terminal.js";
+export * from "./trace.js";
 export * from "./transcript-layout.js";
 export * from "./work-steps.js";