@assistant-ui/react-devtools 1.2.6 → 1.2.7

package/src/views/runs/parse.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+import type { EventLogEntry } from "../../data/types";
+import { groupRuns } from "./parse";
+
+const base = 2_000_000_000_000;
+const t = (ms: number) => new Date(base + ms);
+
+describe("groupRuns", () => {
+  it("pairs runStart/runEnd and computes durations and offsets", () => {
+    const logs: EventLogEntry[] = [
+      { time: t(0), event: "thread.runStart", data: { threadId: "T1" } },
+      {
+        time: t(150),
+        event: "composer.send",
+        data: { threadId: "T1", messageId: "m1" },
+      },
+      { time: t(900), event: "thread.runEnd", data: { threadId: "T1" } },
+    ];
+
+    const { runs, orphans } = groupRuns(logs);
+    expect(orphans).toEqual([]);
+    expect(runs).toHaveLength(1);
+    const run = runs[0]!;
+    expect(run.index).toBe(0);
+    expect(run.threadId).toBe("T1");
+    expect(run.endTime).toBeDefined();
+    expect(run.durationMs).toBe(900);
+    expect(run.spanMs).toBe(900);
+    expect(run.events.map((e) => e.offsetMs)).toEqual([0, 150, 900]);
+    expect(run.events.map((e) => e.scope)).toEqual([
+      "thread",
+      "composer",
+      "thread",
+    ]);
+  });
+
+  it("marks a run with no runEnd as running, with span from last event", () => {
+    const logs: EventLogEntry[] = [
+      { time: t(0), event: "thread.runStart", data: { threadId: "T1" } },
+      { time: t(100), event: "composer.send", data: { threadId: "T1" } },
+    ];
+    const { runs } = groupRuns(logs);
+    expect(runs[0]!.endTime).toBeUndefined();
+    expect(runs[0]!.durationMs).toBeUndefined();
+    expect(runs[0]!.spanMs).toBe(100);
+  });
+
+  it("buckets events outside any run as orphans", () => {
+    const logs: EventLogEntry[] = [
+      {
+        time: t(0),
+        event: "thread.modelContextUpdate",
+        data: { threadId: "T1" },
+      },
+      { time: t(50), event: "thread.runStart", data: { threadId: "T1" } },
+      { time: t(200), event: "thread.runEnd", data: { threadId: "T1" } },
+    ];
+    const { runs, orphans } = groupRuns(logs);
+    expect(runs).toHaveLength(1);
+    expect(orphans).toHaveLength(1);
+    expect(orphans[0]!.event).toBe("thread.modelContextUpdate");
+  });
+
+  it("sorts out-of-order logs before pairing", () => {
+    const logs: EventLogEntry[] = [
+      { time: t(100), event: "thread.runEnd", data: { threadId: "T1" } },
+      { time: t(0), event: "thread.runStart", data: { threadId: "T1" } },
+    ];
+    const { runs, orphans } = groupRuns(logs);
+    expect(orphans).toEqual([]);
+    expect(runs).toHaveLength(1);
+    expect(runs[0]!.durationMs).toBe(100);
+  });
+
+  it("routes events to the matching thread when runs interleave", () => {
+    const logs: EventLogEntry[] = [
+      { time: t(0), event: "thread.runStart", data: { threadId: "T1" } },
+      { time: t(50), event: "thread.runStart", data: { threadId: "T2" } },
+      { time: t(60), event: "composer.send", data: { threadId: "T2" } },
+      { time: t(100), event: "thread.runEnd", data: { threadId: "T2" } },
+      { time: t(200), event: "thread.runEnd", data: { threadId: "T1" } },
+    ];
+    const { runs } = groupRuns(logs);
+    expect(runs).toHaveLength(2);
+    const t2 = runs.find((r) => r.threadId === "T2")!;
+    expect(t2.events.map((e) => e.event)).toEqual([
+      "thread.runStart",
+      "composer.send",
+      "thread.runEnd",
+    ]);
+    expect(runs.find((r) => r.threadId === "T1")!.durationMs).toBe(200);
+  });
+
+  it("closes a prior open run on the same thread when a new run starts", () => {
+    const logs: EventLogEntry[] = [
+      { time: t(0), event: "thread.runStart", data: { threadId: "T1" } },
+      { time: t(50), event: "thread.runStart", data: { threadId: "T1" } },
+      { time: t(100), event: "thread.runEnd", data: { threadId: "T1" } },
+    ];
+    const { runs } = groupRuns(logs);
+    expect(runs).toHaveLength(2);
+    expect(runs[0]!.endTime).toBeDefined();
+    expect(runs[0]!.durationMs).toBe(50);
+    expect(runs[1]!.endTime).toBeDefined();
+    expect(runs[1]!.durationMs).toBe(50);
+  });
+
+  it("orphans an event whose explicit threadId matches no open run", () => {
+    const logs: EventLogEntry[] = [
+      { time: t(0), event: "thread.runStart", data: { threadId: "T1" } },
+      { time: t(50), event: "composer.send", data: { threadId: "T2" } },
+      { time: t(100), event: "thread.runEnd", data: { threadId: "T1" } },
+    ];
+    const { runs, orphans } = groupRuns(logs);
+    expect(runs).toHaveLength(1);
+    expect(runs[0]!.events.map((e) => e.event)).toEqual([
+      "thread.runStart",
+      "thread.runEnd",
+    ]);
+    expect(orphans.map((o) => o.event)).toEqual(["composer.send"]);
+  });
+
+  it("attaches a thread-less event to the single open run", () => {
+    const logs: EventLogEntry[] = [
+      { time: t(0), event: "thread.runStart", data: { threadId: "T1" } },
+      { time: t(50), event: "custom.event", data: {} },
+      { time: t(100), event: "thread.runEnd", data: { threadId: "T1" } },
+    ];
+    const { runs, orphans } = groupRuns(logs);
+    expect(orphans).toEqual([]);
+    expect(runs[0]!.events.map((e) => e.event)).toContain("custom.event");
+  });
+
+  it("keeps an empty-string threadId distinct from a thread-less run", () => {
+    const logs: EventLogEntry[] = [
+      { time: t(0), event: "thread.runStart", data: { threadId: "" } },
+      { time: t(50), event: "thread.runStart", data: {} },
+      { time: t(100), event: "thread.runEnd", data: { threadId: "" } },
+    ];
+    const { runs } = groupRuns(logs);
+    expect(runs).toHaveLength(2);
+    expect(runs[0]!.threadId).toBe("");
+    expect(runs[0]!.endTime).toBeDefined();
+    expect(runs[0]!.durationMs).toBe(100);
+    expect(runs[1]!.threadId).toBeUndefined();
+    expect(runs[1]!.endTime).toBeUndefined();
+  });
+
+  it("returns nothing for an empty log", () => {
+    expect(groupRuns([])).toEqual({ runs: [], orphans: [] });
+  });
+});

package/src/views/runs/parse.ts

@@ -0,0 +1,110 @@
+import { eventScope, isRecord } from "../../utils/common";
+import type { EventLogEntry } from "../../data/types";
+import type { RunEventEntry, RunGrouping, RunPreview } from "./types";
+
+// thread.runStart/runEnd are @deprecated in core but kept for backward
+// compatibility; they are the only run-boundary signal in the event log.
+const RUN_START = "thread.runStart";
+const RUN_END = "thread.runEnd";
+
+const threadIdOf = (data: unknown): string | undefined =>
+  isRecord(data) && typeof data.threadId === "string"
+    ? data.threadId
+    : undefined;
+
+interface RunBuilder {
+  id: string;
+  threadId?: string;
+  index: number;
+  startTime: Date;
+  endTime?: Date;
+  events: RunEventEntry[];
+}
+
+const entryFor = (log: EventLogEntry, offsetMs: number): RunEventEntry => ({
+  time: log.time,
+  event: log.event,
+  scope: eventScope(log.event),
+  offsetMs: Math.max(0, offsetMs),
+  data: log.data,
+});
+
+export const groupRuns = (logs: readonly EventLogEntry[]): RunGrouping => {
+  const sorted = [...logs].sort((a, b) => a.time.getTime() - b.time.getTime());
+  const builders: RunBuilder[] = [];
+  const openByThread = new Map<string | undefined, RunBuilder>();
+  const orphans: RunEventEntry[] = [];
+
+  const targetRun = (tid: string | undefined): RunBuilder | undefined => {
+    const exact = openByThread.get(tid);
+    if (exact) return exact;
+    if (tid === undefined && openByThread.size === 1) {
+      return [...openByThread.values()][0];
+    }
+    return undefined;
+  };
+
+  for (const log of sorted) {
+    const tid = threadIdOf(log.data);
+
+    if (log.event === RUN_START) {
+      const stale = openByThread.get(tid);
+      if (stale) {
+        stale.endTime = log.time;
+        openByThread.delete(tid);
+      }
+      const builder: RunBuilder = {
+        id: `run-${builders.length}`,
+        ...(tid !== undefined ? { threadId: tid } : {}),
+        index: builders.length,
+        startTime: log.time,
+        events: [entryFor(log, 0)],
+      };
+      builders.push(builder);
+      openByThread.set(tid, builder);
+      continue;
+    }
+
+    if (log.event === RUN_END) {
+      const run = targetRun(tid);
+      if (run && run.endTime === undefined) {
+        run.endTime = log.time;
+        run.events.push(
+          entryFor(log, log.time.getTime() - run.startTime.getTime()),
+        );
+        openByThread.delete(run.threadId);
+        continue;
+      }
+      orphans.push(entryFor(log, 0));
+      continue;
+    }
+
+    const run = targetRun(tid);
+    if (run) {
+      run.events.push(
+        entryFor(log, log.time.getTime() - run.startTime.getTime()),
+      );
+    } else {
+      orphans.push(entryFor(log, 0));
+    }
+  }
+
+  const runs: RunPreview[] = builders.map((b) => {
+    const maxOffset = b.events.reduce((max, e) => Math.max(max, e.offsetMs), 0);
+    const durationMs = b.endTime
+      ? b.endTime.getTime() - b.startTime.getTime()
+      : undefined;
+    return {
+      id: b.id,
+      ...(b.threadId !== undefined ? { threadId: b.threadId } : {}),
+      index: b.index,
+      startTime: b.startTime,
+      ...(b.endTime !== undefined ? { endTime: b.endTime } : {}),
+      ...(durationMs !== undefined ? { durationMs } : {}),
+      spanMs: Math.max(durationMs ?? 0, maxOffset),
+      events: b.events,
+    };
+  });
+
+  return { runs, orphans };
+};

package/src/views/runs/types.ts

@@ -0,0 +1,23 @@
+export interface RunEventEntry {
+  readonly time: Date;
+  readonly event: string;
+  readonly scope: string;
+  readonly offsetMs: number;
+  readonly data: unknown;
+}
+
+export interface RunPreview {
+  readonly id: string;
+  readonly threadId?: string;
+  readonly index: number;
+  readonly startTime: Date;
+  readonly endTime?: Date;
+  readonly durationMs?: number;
+  readonly spanMs: number;
+  readonly events: readonly RunEventEntry[];
+}
+
+export interface RunGrouping {
+  readonly runs: readonly RunPreview[];
+  readonly orphans: readonly RunEventEntry[];
+}

package/src/views/scopes/ScopesView.tsx

@@ -0,0 +1,105 @@
+import { isRecord } from "../../utils/common";
+import { Chip, EmptyState, SummaryItem, SummaryList, ToneBadge } from "../ui";
+import { parseScopes } from "./parse";
+import type { ScopePreview } from "./types";
+
+const SourceBadge = ({ source }: { source: string | null }) => {
+  if (!source) return null;
+  if (source === "root") return <ToneBadge tone="emerald">root</ToneBadge>;
+  return <Chip>← {source}</Chip>;
+};
+
+const ScopeNode = ({
+  scope,
+  scopes,
+  path,
+}: {
+  scope: ScopePreview;
+  scopes: readonly ScopePreview[];
+  path: ReadonlySet<string>;
+}) => {
+  const hasQuery = isRecord(scope.query) && Object.keys(scope.query).length > 0;
+  const children = path.has(scope.name)
+    ? []
+    : scopes.filter((candidate) => candidate.source === scope.name);
+  const nextPath = new Set(path).add(scope.name);
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      <div className="flex flex-wrap items-center gap-2">
+        <span className="text-foreground text-[13px] font-medium">
+          {scope.name}
+        </span>
+        <SourceBadge source={scope.source} />
+        {hasQuery ? (
+          <span className="text-muted-foreground font-mono text-[11px]">
+            {JSON.stringify(scope.query)}
+          </span>
+        ) : null}
+      </div>
+
+      {scope.methods.length ? (
+        <div className="flex flex-wrap gap-1.5">
+          {scope.methods.map((method) => (
+            <Chip key={method} className="font-mono">
+              {method}
+            </Chip>
+          ))}
+        </div>
+      ) : null}
+
+      {children.length ? (
+        <div className="border-border/60 ms-1 mt-1 flex flex-col gap-3 border-s ps-3">
+          {children.map((child) => (
+            <ScopeNode
+              key={child.name}
+              scope={child}
+              scopes={scopes}
+              path={nextPath}
+            />
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+};
+
+export const ScopesView = ({ scopes }: { scopes?: unknown }) => {
+  const list = parseScopes(scopes);
+
+  if (list.length === 0) {
+    return (
+      <EmptyState>
+        No scopes reported. Update `@assistant-ui/react-devtools` to forward the
+        scope graph.
+      </EmptyState>
+    );
+  }
+
+  const names = new Set(list.map((scope) => scope.name));
+  const roots = list.filter(
+    (scope) =>
+      scope.source === "root" ||
+      scope.source === null ||
+      !names.has(scope.source),
+  );
+
+  return (
+    <div className="flex flex-col gap-4">
+      <SummaryList>
+        <SummaryItem label="Scopes" value={String(list.length)} />
+        <SummaryItem label="Roots" value={String(roots.length)} />
+      </SummaryList>
+      <div className="flex flex-col gap-3">
+        {roots.map((scope) => (
+          <ScopeNode
+            key={scope.name}
+            scope={scope}
+            scopes={list}
+            path={new Set()}
+          />
+        ))}
+      </div>
+    </div>
+  );
+};

package/src/views/scopes/index.ts

@@ -0,0 +1 @@
+export { ScopesView } from "./ScopesView";

package/src/views/scopes/parse.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { parseScopes } from "./parse";
+
+describe("parseScopes", () => {
+  it("parses scopes and sorts root first, then by name", () => {
+    const out = parseScopes([
+      {
+        name: "thread",
+        source: "threads",
+        query: { type: "main" },
+        methods: ["getState", "append"],
+      },
+      { name: "threads", source: "root", query: {}, methods: ["getState"] },
+    ]);
+
+    expect(out.map((s) => s.name)).toEqual(["threads", "thread"]);
+    expect(out[0]!.source).toBe("root");
+    expect(out[1]!.query).toEqual({ type: "main" });
+    expect(out[1]!.methods).toEqual(["getState", "append"]);
+  });
+
+  it("filters non-string methods and defaults a missing source to null", () => {
+    const out = parseScopes([{ name: "x", methods: ["a", 1, null, "b"] }]);
+    expect(out[0]!.methods).toEqual(["a", "b"]);
+    expect(out[0]!.source).toBeNull();
+  });
+
+  it("drops entries without a name and returns [] for non-arrays", () => {
+    expect(parseScopes([{ source: "root" }, 5, null])).toEqual([]);
+    expect(parseScopes(undefined)).toEqual([]);
+    expect(parseScopes(null)).toEqual([]);
+    expect(parseScopes(42)).toEqual([]);
+    expect(parseScopes({})).toEqual([]);
+  });
+});

package/src/views/scopes/parse.ts

@@ -0,0 +1,30 @@
+import { isRecord, isStringArray } from "../../utils/common";
+import type { ScopePreview } from "./types";
+
+const parseScope = (value: unknown): ScopePreview | null => {
+  if (!isRecord(value) || typeof value.name !== "string") return null;
+
+  const methods = isStringArray(value.methods);
+
+  return {
+    name: value.name,
+    source: typeof value.source === "string" ? value.source : null,
+    query: value.query,
+    methods,
+  };
+};
+
+export const parseScopes = (value: unknown): ScopePreview[] => {
+  if (!Array.isArray(value)) return [];
+
+  const scopes = value
+    .map((scope) => parseScope(scope))
+    .filter((scope): scope is ScopePreview => Boolean(scope));
+
+  // Root scopes first, then alphabetically by name. This is not a full
+  // hierarchy sort: a derived scope can sort before its parent.
+  return scopes.sort((a, b) => {
+    const rootDelta = Number(b.source === "root") - Number(a.source === "root");
+    return rootDelta !== 0 ? rootDelta : a.name.localeCompare(b.name);
+  });
+};

package/src/views/scopes/render.test.tsx

@@ -0,0 +1,35 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ScopesView } from "./ScopesView";
+
+describe("ScopesView", () => {
+  it("renders scope names, source, query, and methods", () => {
+    const html = renderToStaticMarkup(
+      <ScopesView
+        scopes={[
+          { name: "threads", source: "root", query: {}, methods: ["getState"] },
+          {
+            name: "composer",
+            source: "thread",
+            query: { type: "main" },
+            methods: ["send", "setText"],
+          },
+        ]}
+      />,
+    );
+
+    expect(html).toContain("threads");
+    expect(html).toContain("root");
+    expect(html).toContain("composer");
+    expect(html).toContain("send");
+    expect(html).toContain("setText");
+    // the query renders as escaped JSON ({&quot;type&quot;:&quot;main&quot;})
+    expect(html).toContain("type");
+    expect(html).toContain("main");
+  });
+
+  it("shows an empty state when no scopes are reported", () => {
+    const html = renderToStaticMarkup(<ScopesView scopes={undefined} />);
+    expect(html).toContain("No scopes reported");
+  });
+});

package/src/views/scopes/types.ts

@@ -0,0 +1,6 @@
+export interface ScopePreview {
+  readonly name: string;
+  readonly source: string | null;
+  readonly query: unknown;
+  readonly methods: readonly string[];
+}

package/src/views/thread/ComposerAttachments.test.tsx

@@ -0,0 +1,36 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ComposerAttachments } from "./ComposerAttachments";
+
+describe("ComposerAttachments", () => {
+  it("renders attachments with name, kind, and upload status", () => {
+    const html = renderToStaticMarkup(
+      <ComposerAttachments
+        attachments={[
+          {
+            id: "a1",
+            name: "photo.png",
+            kind: "image",
+            status: { type: "running", reason: "uploading", progress: 0.5 },
+          },
+          {
+            id: "a2",
+            name: "doc.pdf",
+            kind: "file",
+            status: { type: "complete" },
+          },
+        ]}
+      />,
+    );
+    expect(html).toContain("Composer attachments (2)");
+    expect(html).toContain("photo.png");
+    expect(html).toContain("uploading 50%");
+    expect(html).toContain("complete");
+  });
+
+  it("renders nothing when there are no attachments", () => {
+    expect(renderToStaticMarkup(<ComposerAttachments attachments={[]} />)).toBe(
+      "",
+    );
+  });
+});

package/src/views/thread/ComposerAttachments.tsx

@@ -0,0 +1,8 @@
+import type { AttachmentPreview } from "../attachments/types";
+import { AttachmentList } from "../attachments";
+
+export const ComposerAttachments = ({
+  attachments,
+}: {
+  attachments: readonly AttachmentPreview[];
+}) => <AttachmentList attachments={attachments} label="Composer attachments" />;

package/src/views/thread/ComposerFlags.test.tsx

@@ -0,0 +1,23 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ComposerFlags } from "./ComposerFlags";
+
+describe("ComposerFlags", () => {
+  it("renders only the boolean flags that are present", () => {
+    const html = renderToStaticMarkup(
+      <ComposerFlags
+        composer={{
+          textLength: 0,
+          attachments: [],
+          queue: [],
+          isEditing: true,
+          canSend: false,
+        }}
+      />,
+    );
+    expect(html).toContain("Edit: true");
+    expect(html).toContain("Can send: false");
+    expect(html).not.toContain("Can cancel");
+    expect(html).not.toContain("Empty");
+  });
+});

package/src/views/thread/ComposerFlags.tsx

@@ -0,0 +1,19 @@
+import { formatBoolean } from "../../utils/common";
+import type { ComposerPreview } from "./types";
+
+export const ComposerFlags = ({ composer }: { composer: ComposerPreview }) => (
+  <div className="text-muted-foreground flex flex-wrap gap-2 text-[11px]">
+    {typeof composer.isEditing === "boolean" ? (
+      <span>Edit: {formatBoolean(composer.isEditing)}</span>
+    ) : null}
+    {typeof composer.canCancel === "boolean" ? (
+      <span>Can cancel: {formatBoolean(composer.canCancel)}</span>
+    ) : null}
+    {typeof composer.canSend === "boolean" ? (
+      <span>Can send: {formatBoolean(composer.canSend)}</span>
+    ) : null}
+    {typeof composer.isEmpty === "boolean" ? (
+      <span>Empty: {formatBoolean(composer.isEmpty)}</span>
+    ) : null}
+  </div>
+);

package/src/views/thread/ComposerQueue.test.tsx

@@ -0,0 +1,20 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ComposerQueue } from "./ComposerQueue";
+
+describe("ComposerQueue", () => {
+  it("renders the queued prompts", () => {
+    const html = renderToStaticMarkup(
+      <ComposerQueue
+        queue={[{ id: "q1", prompt: "first" }, { prompt: "second" }]}
+      />,
+    );
+    expect(html).toContain("Message queue (2)");
+    expect(html).toContain("first");
+    expect(html).toContain("second");
+  });
+
+  it("renders nothing when the queue is empty", () => {
+    expect(renderToStaticMarkup(<ComposerQueue queue={[]} />)).toBe("");
+  });
+});

package/src/views/thread/ComposerQueue.tsx

@@ -0,0 +1,26 @@
+import { SectionLabel } from "../ui";
+import type { ComposerQueueItem } from "./types";
+
+export const ComposerQueue = ({
+  queue,
+}: {
+  queue: readonly ComposerQueueItem[];
+}) => {
+  if (!queue.length) return null;
+
+  return (
+    <div className="bg-card rounded-md border p-3">
+      <SectionLabel>Message queue ({queue.length})</SectionLabel>
+      <ol className="text-foreground mt-1 list-decimal space-y-0.5 pl-5 text-[11px]">
+        {queue.map((item, index) => (
+          <li
+            key={item.id ?? index}
+            className="wrap-break-word whitespace-pre-wrap"
+          >
+            {item.prompt || "(empty)"}
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+};