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

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

@@ -0,0 +1,228 @@
+// @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 { Terminal, TerminalOutput } from "./terminal.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 trigger = () =>
+  container.querySelector<HTMLButtonElement>(
+    "button.agentkit-disclosure-summary",
+  );
+const status = () =>
+  container
+    .querySelector('[data-slot="trace-line"]')
+    ?.getAttribute("data-trace-status");
+
+describe("Terminal", () => {
+  it("shows a command with no output yet as a static running step", async () => {
+    await render(<Terminal command="pnpm build" running />);
+    expect(trigger()).toBeNull();
+    expect(container.querySelector(".agentkit-trace-title")?.textContent).toBe(
+      "pnpm build",
+    );
+    expect(status()).toBe("running");
+  });
+
+  it("masks closed output in fresh nodes, so replay never keeps it", async () => {
+    await render(
+      <Terminal command="pnpm build" output={"token=abc\n"} exitCode={0} />,
+    );
+    const output = () =>
+      document.querySelector(".agentkit-terminal-body [data-an-mask]");
+    expect(
+      document.querySelector(".agentkit-terminal-body")?.textContent,
+    ).toContain("token=abc");
+    expect(output()).not.toBeNull();
+
+    await act(async () =>
+      document
+        .querySelector<HTMLButtonElement>(".agentkit-disclosure-summary")
+        ?.click(),
+    );
+    const opened = document.querySelector(".agentkit-terminal-body");
+    expect(output()).toBeNull();
+
+    await act(async () =>
+      document
+        .querySelector<HTMLButtonElement>(".agentkit-disclosure-summary")
+        ?.click(),
+    );
+    // Closing replaces the node instead of masking the one replay recorded.
+    expect(opened?.isConnected).toBe(false);
+    expect(output()).not.toBeNull();
+  });
+
+  it("opens when output starts streaming and marks a nonzero exit failed", async () => {
+    await render(<Terminal command="pnpm test" running output="" />);
+    await render(
+      <Terminal command="pnpm test" running output={"1 passed\n"} />,
+    );
+    expect(trigger()?.getAttribute("aria-expanded")).toBe("true");
+    expect(container.querySelector("pre")?.textContent).toBe("1 passed");
+
+    await render(
+      <Terminal
+        command="pnpm test"
+        output={"1 passed\n1 failed\n"}
+        exitCode={1}
+        durationMs={4_200}
+      />,
+    );
+    expect(status()).toBe("error");
+    expect(
+      container.querySelector(".agentkit-trace-description")?.textContent,
+    ).toBe("4s · Exit code 1");
+    // Finishing never closes what streaming opened.
+    expect(trigger()?.getAttribute("aria-expanded")).toBe("true");
+  });
+
+  it("stays closed once the user closes it, while output keeps streaming", async () => {
+    await render(<Terminal command="pnpm dev" running output={"ready\n"} />);
+    await act(async () => trigger()?.click());
+    expect(trigger()?.getAttribute("aria-expanded")).toBe("false");
+    await render(
+      <Terminal command="pnpm dev" running output={"ready\nrebuilt\n"} />,
+    );
+    expect(trigger()?.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("shows the newest lines first and reveals the earlier ones", async () => {
+    const output = Array.from(
+      { length: 8 },
+      (_, index) => `line ${index + 1}`,
+    ).join("\n");
+    await render(
+      <Terminal command="seq 8" output={output} maxLines={3} defaultOpen />,
+    );
+    expect(trigger()?.getAttribute("aria-expanded")).toBe("true");
+    const pre = () => container.querySelector("pre")?.textContent;
+    expect(pre()).toBe("line 6\nline 7\nline 8");
+    const earlier = container.querySelector<HTMLButtonElement>(
+      ".agentkit-terminal-earlier",
+    );
+    expect(earlier?.textContent).toBe("Show 5 earlier lines");
+    await act(async () => earlier?.click());
+    expect(pre()).toBe(output);
+
+    // The body remounts on each toggle; the revealed lines stay revealed.
+    await act(async () => trigger()?.click());
+    await act(async () => trigger()?.click());
+    expect(pre()).toBe(output);
+  });
+
+  it("reveals earlier lines when given showAll without onShowAll", async () => {
+    const output = ["one", "two", "three"].join("\n");
+    await render(
+      <TerminalOutput output={output} maxLines={1} showAll={false} />,
+    );
+    await act(async () =>
+      container
+        .querySelector<HTMLButtonElement>(".agentkit-terminal-earlier")
+        ?.click(),
+    );
+    expect(container.querySelector("pre")?.textContent).toBe(output);
+  });
+
+  it("shows every line for showAll and reports a reveal to onShowAll", async () => {
+    const output = ["one", "two", "three"].join("\n");
+    const pre = () => container.querySelector("pre")?.textContent;
+    await render(<TerminalOutput output={output} maxLines={1} showAll />);
+    expect(pre()).toBe(output);
+
+    const onShowAll = vi.fn();
+    await render(
+      <TerminalOutput
+        key="callback-only"
+        output={output}
+        maxLines={1}
+        onShowAll={onShowAll}
+      />,
+    );
+    expect(pre()).toBe("three");
+    await act(async () =>
+      container
+        .querySelector<HTMLButtonElement>(".agentkit-terminal-earlier")
+        ?.click(),
+    );
+    expect(pre()).toBe(output);
+    expect(onShowAll).toHaveBeenCalledTimes(1);
+  });
+
+  it("leaves showAll to the host when it also passes onShowAll", async () => {
+    const output = ["one", "two", "three"].join("\n");
+    const pre = () => container.querySelector("pre")?.textContent;
+    const onShowAll = vi.fn();
+    const renderWith = (showAll: boolean) =>
+      render(
+        <TerminalOutput
+          output={output}
+          maxLines={1}
+          showAll={showAll}
+          onShowAll={onShowAll}
+        />,
+      );
+    await renderWith(false);
+    await act(async () =>
+      container
+        .querySelector<HTMLButtonElement>(".agentkit-terminal-earlier")
+        ?.click(),
+    );
+    expect(onShowAll).toHaveBeenCalledTimes(1);
+    expect(pre()).toBe("three");
+    await renderWith(true);
+    expect(pre()).toBe(output);
+    await renderWith(false);
+    expect(pre()).toBe("three");
+  });
+
+  it("copies the whole output without color codes", async () => {
+    const writeText = vi.fn(async () => undefined);
+    vi.stubGlobal("navigator", { ...navigator, clipboard: { writeText } });
+    await render(
+      <Terminal
+        command="pnpm lint"
+        output={"\u001b[31merror\u001b[0m in a.ts"}
+        exitCode={1}
+      />,
+    );
+    const copy = container.querySelector<HTMLButtonElement>(
+      ".agentkit-terminal-actions button",
+    );
+    expect(copy?.getAttribute("aria-label")).toBe("Copy output");
+    await act(async () => {
+      copy?.click();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(writeText).toHaveBeenCalledWith("error in a.ts");
+  });
+
+  it("marks a call that failed apart from its exit code", async () => {
+    await render(
+      <Terminal command="rm -rf /" output="Error: command blocked" failed />,
+    );
+    expect(status()).toBe("error");
+  });
+});

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

@@ -0,0 +1,228 @@
+import { IconAlertTriangle, IconTerminal2 } from "@tabler/icons-react";
+import { useEffect, useRef, useState } from "react";
+
+import {
+  CodeBlock,
+  CodeBlockContent,
+  CodeBlockCopyButton,
+  CodeBlockHeader,
+} from "./code-block.js";
+import { useAgentKitDurationFormat, useAgentKitLabels } from "./context.js";
+import {
+  Trace,
+  TraceCollapsible,
+  TraceCollapsibleContent,
+  TraceCollapsibleTrigger,
+  TraceDescription,
+  TraceIcon,
+  TraceLine,
+  TraceTitle,
+  type TraceCollapsibleOpenProps,
+} from "./trace.js";
+
+// A global regex's `test` keeps state between calls, so `HAS_ANSI` is separate.
+const ANSI_SEQUENCE = /\u001b\[[0-9;]*m/g;
+const HAS_ANSI = /\u001b\[[0-9;]*m/;
+
+const DEFAULT_MAX_LINES = 500;
+const SESSION_REPLAY_MASK_PROPS = { "data-an-mask": "" } as const;
+const FOLLOW_SLACK_PX = 24;
+
+/** Copy sits beside the trigger: a button cannot nest in the trigger. */
+export function Terminal({
+  command,
+  output,
+  running = false,
+  exitCode,
+  durationMs,
+  timedOut = false,
+  failed: failedOverride,
+  defaultOpen = false,
+  maxLines = DEFAULT_MAX_LINES,
+  className,
+  ...openProps
+}: TraceCollapsibleOpenProps & {
+  command: string;
+  /** May hold ANSI color codes. */
+  output?: string | undefined;
+  running?: boolean;
+  exitCode?: number | null | undefined;
+  durationMs?: number | undefined;
+  timedOut?: boolean | undefined;
+  /** A failure the exit code does not show, such as a rejected command. */
+  failed?: boolean | undefined;
+  defaultOpen?: boolean;
+  /** How many of the newest lines show before "Show earlier lines". */
+  maxLines?: number;
+  className?: string;
+}) {
+  const labels = useAgentKitLabels();
+  const formatDuration = useAgentKitDurationFormat();
+  const failed =
+    !running &&
+    (failedOverride === true ||
+      timedOut ||
+      (exitCode !== undefined && exitCode !== null && exitCode !== 0));
+  const hasOutput = Boolean(output?.trim());
+  // Opens once when running output starts; never closes on its own.
+  const [autoOpen, setAutoOpen] = useState(false);
+  // Outlives the body, which remounts on each toggle.
+  const [showAllOutput, setShowAllOutput] = useState(false);
+  useEffect(() => {
+    if (running && hasOutput) setAutoOpen(true);
+  }, [running, hasOutput]);
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const open = openProps.open ?? (uncontrolledOpen || autoOpen);
+  const setOpen = (next: boolean) => {
+    if (openProps.open === undefined) {
+      setUncontrolledOpen(next);
+      setAutoOpen(false);
+    }
+    openProps.onOpenChange?.(next);
+  };
+  const meta = [
+    !running && durationMs !== undefined && durationMs >= 1_000
+      ? formatDuration(durationMs)
+      : undefined,
+    failed && exitCode !== undefined && exitCode !== null && exitCode !== 0
+      ? labels.workStepTerminalExitCode.replace("{{code}}", () => `${exitCode}`)
+      : undefined,
+    timedOut ? labels.workStepTerminalTimedOut : undefined,
+  ].filter((part): part is string => Boolean(part));
+  const line = (
+    <TraceLine status={running ? "running" : failed ? "error" : undefined}>
+      <TraceIcon>
+        {/* Without an exit code, the triangle marks a failure besides color. */}
+        {failed ? (
+          <IconAlertTriangle aria-hidden="true" className="agentkit-icon" />
+        ) : (
+          <IconTerminal2 aria-hidden="true" className="agentkit-icon" />
+        )}
+      </TraceIcon>
+      <TraceTitle className="agentkit-terminal-command">{command}</TraceTitle>
+      {running || failed ? (
+        // Status shows as motion and color; the accessible name says it.
+        <span className="agentkit-visually-hidden">
+          {running ? labels.taskStatusRunning : labels.taskStatusFailed}
+        </span>
+      ) : null}
+      {meta.length ? (
+        <TraceDescription>{meta.join(" · ")}</TraceDescription>
+      ) : null}
+    </TraceLine>
+  );
+  return (
+    <Trace
+      data-slot="terminal"
+      data-status={running ? "running" : failed ? "failed" : "completed"}
+      className={
+        className ? `agentkit-terminal ${className}` : "agentkit-terminal"
+      }
+    >
+      {hasOutput ? (
+        <TraceCollapsible open={open} onOpenChange={setOpen}>
+          <div className="agentkit-terminal-row">
+            <TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
+            <span className="agentkit-terminal-actions">
+              <CodeBlockCopyButton
+                value={(output ?? "").replace(ANSI_SEQUENCE, "")}
+                label={labels.workStepCopyOutput}
+              />
+            </span>
+          </div>
+          <TraceCollapsibleContent
+            // A fresh node on each toggle: masking a node replay already
+            // recorded would not hide its text.
+            key={open ? "open" : "closed"}
+            keepMounted
+            className="agentkit-terminal-body"
+          >
+            <TerminalOutput
+              output={output ?? ""}
+              maxLines={maxLines}
+              masked={failed || !open}
+              showAll={showAllOutput}
+              onShowAll={() => setShowAllOutput(true)}
+            />
+          </TraceCollapsibleContent>
+        </TraceCollapsible>
+      ) : (
+        <span className="agentkit-disclosure-summary" data-expandable="false">
+          {line}
+        </span>
+      )}
+    </Trace>
+  );
+}
+
+export function TerminalOutput({
+  output,
+  maxLines = DEFAULT_MAX_LINES,
+  masked = false,
+  showAll: controlledShowAll,
+  onShowAll,
+}: {
+  output: string;
+  maxLines?: number;
+  /** Hides the output from session replays. */
+  masked?: boolean;
+  /** Shows every line. Pass with `onShowAll` to control it. */
+  showAll?: boolean;
+  /** Called when the user reveals the earlier lines. */
+  onShowAll?: () => void;
+}) {
+  const labels = useAgentKitLabels();
+  const [revealed, setRevealed] = useState(false);
+  // With both props the host owns it; with one, a press still reveals.
+  const showAll =
+    onShowAll && controlledShowAll !== undefined
+      ? controlledShowAll
+      : controlledShowAll === true || revealed;
+  const setShowAll = () => {
+    setRevealed(true);
+    onShowAll?.();
+  };
+  const content = useRef<HTMLPreElement>(null);
+  const lines = output.replace(/\n$/, "").split("\n");
+  const hidden = showAll ? 0 : Math.max(0, lines.length - maxLines);
+  const visible = hidden ? lines.slice(hidden).join("\n") : output;
+  // Follow only if the reader was at the bottom before the output grew;
+  // measured here, not tracked from scroll events.
+  const lastHeight = useRef(0);
+  useEffect(() => {
+    const element = content.current;
+    if (!element) return;
+    const wasAtBottom =
+      lastHeight.current - element.scrollTop - element.clientHeight <=
+      FOLLOW_SLACK_PX;
+    if (wasAtBottom) element.scrollTop = element.scrollHeight;
+    lastHeight.current = element.scrollHeight;
+  }, [visible]);
+  return (
+    <CodeBlock size="sm">
+      {hidden ? (
+        <CodeBlockHeader>
+          <button
+            type="button"
+            className="agentkit-terminal-earlier"
+            onClick={setShowAll}
+          >
+            {labels.workStepTerminalEarlierLines.replace(
+              "{{count}}",
+              () => `${hidden}`,
+            )}
+          </button>
+        </CodeBlockHeader>
+      ) : null}
+      <CodeBlockContent
+        ref={content}
+        wrap
+        language={HAS_ANSI.test(visible) ? "ansi" : undefined}
+        className="agentkit-terminal-output"
+        {...(masked ? SESSION_REPLAY_MASK_PROPS : {})}
+      >
+        {visible}
+      </CodeBlockContent>
+    </CodeBlock>
+  );
+}

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

@@ -0,0 +1,120 @@
+// @vitest-environment happy-dom
+
+import { act, useState, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  TraceCollapsible,
+  TraceCollapsibleContent,
+  TraceCollapsibleTrigger,
+  TraceLine,
+  TraceTitle,
+} from "./trace.js";
+
+(
+  globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | undefined;
+let container: HTMLDivElement | undefined;
+
+afterEach(() => {
+  act(() => root?.unmount());
+  container?.remove();
+  root = undefined;
+  container = undefined;
+});
+
+function render(node: ReactNode): HTMLDivElement {
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+  act(() => root!.render(node));
+  return container;
+}
+
+function step(keepMounted?: boolean) {
+  return (
+    <TraceCollapsible>
+      <TraceCollapsibleTrigger>
+        <TraceLine status="running">
+          <TraceTitle>Reading file</TraceTitle>
+        </TraceLine>
+      </TraceCollapsibleTrigger>
+      <TraceCollapsibleContent keepMounted={keepMounted}>
+        File contents
+      </TraceCollapsibleContent>
+    </TraceCollapsible>
+  );
+}
+
+describe("Trace", () => {
+  it("mounts closed content only while open by default", () => {
+    const view = render(step());
+    const trigger = view.querySelector("button")!;
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+    expect(trigger.hasAttribute("aria-controls")).toBe(false);
+    expect(view.textContent).not.toContain("File contents");
+
+    act(() => trigger.click());
+    const content = view.querySelector<HTMLElement>(
+      '[data-slot="trace-collapsible-content"]',
+    )!;
+    expect(trigger.getAttribute("aria-expanded")).toBe("true");
+    expect(trigger.getAttribute("aria-controls")).toBe(content.id);
+    expect(content.textContent).toBe("File contents");
+
+    act(() => trigger.click());
+    expect(view.textContent).not.toContain("File contents");
+  });
+
+  it("keeps closed content findable and opens on a find-in-page match", () => {
+    const view = render(step(true));
+    const trigger = view.querySelector("button")!;
+    const content = view.querySelector<HTMLElement>(
+      '[data-slot="trace-collapsible-content"]',
+    )!;
+    expect(content.getAttribute("hidden")).toBe("until-found");
+    expect(content.textContent).toBe("File contents");
+    expect(trigger.getAttribute("aria-controls")).toBe(content.id);
+
+    act(() => content.dispatchEvent(new Event("beforematch")));
+    expect(trigger.getAttribute("aria-expanded")).toBe("true");
+    expect(content.hidden).toBe(false);
+  });
+
+  it("follows a controlled open state", () => {
+    let setOpen: (open: boolean) => void = () => undefined;
+    const changes: boolean[] = [];
+    function Controlled() {
+      const [open, update] = useState(false);
+      setOpen = update;
+      return (
+        <TraceCollapsible
+          open={open}
+          onOpenChange={(next) => {
+            changes.push(next);
+            update(next);
+          }}
+        >
+          <TraceCollapsibleTrigger>Step</TraceCollapsibleTrigger>
+          <TraceCollapsibleContent>Detail</TraceCollapsibleContent>
+        </TraceCollapsible>
+      );
+    }
+    const view = render(<Controlled />);
+    act(() => setOpen(true));
+    expect(view.textContent).toContain("Detail");
+    act(() => view.querySelector("button")!.click());
+    expect(changes).toEqual([false]);
+    expect(view.textContent).not.toContain("Detail");
+  });
+
+  it("keeps the trace status apart from a row's protocol status", () => {
+    const view = render(step());
+    const line = view.querySelector('[data-slot="trace-line"]')!;
+    expect(line.getAttribute("data-trace-status")).toBe("running");
+    expect(line.hasAttribute("data-status")).toBe(false);
+  });
+});