@tangle-network/ui 1.0.0

package/src/types/parts.ts

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// Part primitives — generic equivalents of blueprint-agent's
+// DevContainerSessionPart, decoupled from @opencode-ai/sdk.
+// ---------------------------------------------------------------------------
+
+export interface TextPart {
+  type: 'text';
+  text: string;
+  /** If true this text was synthesised client-side (e.g. echo of user input). */
+  synthetic?: boolean;
+}
+
+// -- Tool parts -------------------------------------------------------------
+
+export type ToolStatus = 'pending' | 'running' | 'completed' | 'error';
+
+export interface ToolTime {
+  start?: number;
+  end?: number;
+}
+
+export interface ToolState {
+  status: ToolStatus;
+  input?: unknown;
+  output?: unknown;
+  error?: string;
+  metadata?: Record<string, unknown>;
+  time?: ToolTime;
+}
+
+export interface ToolPart {
+  type: 'tool';
+  /** Unique ID for this tool invocation. */
+  id: string;
+  /** Tool name (e.g. "bash", "read", "write", "grep", "glob"). */
+  tool: string;
+  state: ToolState;
+  callID?: string;
+}
+
+// -- Reasoning parts --------------------------------------------------------
+
+export interface ReasoningPart {
+  type: 'reasoning';
+  text: string;
+  time?: ToolTime;
+}
+
+// -- Union ------------------------------------------------------------------
+
+export type SessionPart = TextPart | ToolPart | ReasoningPart;

package/src/types/run.ts

@@ -0,0 +1,56 @@
+import type { SessionMessage } from "./message";
+
+/** Broad category of a tool invocation, used for display grouping. */
+export type ToolCategory =
+  | "command"
+  | "write"
+  | "read"
+  | "search"
+  | "edit"
+  | "task"
+  | "web"
+  | "todo"
+  | "other";
+
+export interface RunStats {
+  toolCount: number;
+  messageCount: number;
+  thinkingDurationMs: number;
+  textPartCount: number;
+  toolCategories: Set<ToolCategory>;
+}
+
+export interface FinalTextPart {
+  messageId: string;
+  partIndex: number;
+  text: string;
+}
+
+/**
+ * A Run is a consecutive group of assistant messages that form one
+ * logical "turn" of the agent. Runs are collapsible in the UI and
+ * show a summary header when collapsed.
+ */
+export interface Run {
+  id: string;
+  messages: SessionMessage[];
+  isComplete: boolean;
+  isStreaming: boolean;
+  stats: RunStats;
+  summaryText: string | null;
+  finalTextPart: FinalTextPart | null;
+}
+
+// -- Grouped messages for rendering -----------------------------------------
+
+export interface MessageRun {
+  type: "run";
+  run: Run;
+}
+
+export interface MessageUser {
+  type: "user";
+  message: SessionMessage;
+}
+
+export type GroupedMessage = MessageRun | MessageUser;

package/src/types/tool-display.ts

@@ -0,0 +1,41 @@
+import type { ToolPart } from "./parts";
+import type { ReactNode } from "react";
+
+/**
+ * Variant-specific rendering instructions for tool output.
+ * Maps directly to specialised preview components.
+ */
+export type DisplayVariant =
+  | "command"
+  | "write-file"
+  | "read-file"
+  | "diff"
+  | "question"
+  | "web-search"
+  | "grep"
+  | "glob"
+  | "default";
+
+/**
+ * Custom renderer for tool details. Return a ReactNode to override the
+ * default ExpandedToolDetail, or null to fall back to the built-in renderer.
+ */
+export type CustomToolRenderer = (part: ToolPart) => ReactNode | null;
+
+/**
+ * Visual metadata for a tool invocation — computed from the tool name,
+ * input, and output by `getToolDisplayMetadata()`.
+ */
+export interface ToolDisplayMetadata {
+  title: string;
+  description?: string;
+  inputTitle?: string;
+  outputTitle?: string;
+  inputLanguage?: string;
+  outputLanguage?: string;
+  hasDiffOutput?: boolean;
+  diffFilePath?: string;
+  displayVariant?: DisplayVariant;
+  commandSnippet?: string;
+  targetPath?: string;
+}

package/src/utils/copy-text.ts

@@ -0,0 +1,30 @@
+/**
+ * Copy text to clipboard with a non-secure-context fallback.
+ * Returns true if a copy strategy likely succeeded.
+ */
+export async function copyText(text: string): Promise<boolean> {
+  if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return true;
+    } catch {
+      // Fall through to legacy fallback.
+    }
+  }
+
+  if (typeof document === 'undefined') return false;
+
+  try {
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+    const copied = document.execCommand('copy');
+    document.body.removeChild(textarea);
+    return copied;
+  } catch {
+    return false;
+  }
+}

package/src/utils/format.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { formatBytes, formatUptime } from "./format";
+
+describe("formatUptime", () => {
+  it("renders seconds for short durations", () => {
+    expect(formatUptime(0)).toBe("0s");
+    expect(formatUptime(7_500)).toBe("7s");
+  });
+
+  it("renders minutes and seconds under an hour", () => {
+    expect(formatUptime(90_000)).toBe("1m 30s");
+    expect(formatUptime(59 * 60_000 + 12_000)).toBe("59m 12s");
+  });
+
+  it("renders hours and minutes under a day", () => {
+    expect(formatUptime(3_600_000)).toBe("1h 0m");
+    expect(formatUptime(5 * 3_600_000 + 30 * 60_000)).toBe("5h 30m");
+  });
+
+  it("renders days and hours for multi-day durations", () => {
+    expect(formatUptime(86_400_000)).toBe("1d 0h");
+    expect(formatUptime(86_400_000 * 3 + 3_600_000 * 4)).toBe("3d 4h");
+  });
+
+  it("handles invalid input", () => {
+    expect(formatUptime(Number.NaN)).toBe("—");
+    expect(formatUptime(-1)).toBe("—");
+  });
+});
+
+describe("formatBytes", () => {
+  it("renders bytes, KB, MB, GB progressively", () => {
+    expect(formatBytes(512)).toBe("512 B");
+    expect(formatBytes(2_048)).toBe("2.0 KB");
+    expect(formatBytes(5 * 1024 * 1024)).toBe("5.0 MB");
+    expect(formatBytes(2.5 * 1024 * 1024 * 1024)).toBe("2.50 GB");
+  });
+
+  it("handles invalid input", () => {
+    expect(formatBytes(Number.NaN)).toBe("—");
+    expect(formatBytes(-1)).toBe("—");
+  });
+});

package/src/utils/format.ts

@@ -0,0 +1,56 @@
+/** Format a duration in milliseconds to a human-readable string. */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return "<1s";
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remaining = seconds % 60;
+  return remaining > 0 ? `${minutes}m ${remaining}s` : `${minutes}m`;
+}
+
+/** Truncate text to `max` characters, appending "..." if truncated. */
+export function truncateText(text: string, max: number): string {
+  const cleaned = text.replace(/\s+/g, " ").trim();
+  if (cleaned.length <= max) return cleaned;
+  return cleaned.slice(0, max).trim() + "...";
+}
+
+/**
+ * Format an uptime duration in milliseconds with progressive
+ * granularity, so short-lived sandboxes don't render as "0d 0h".
+ *  - < 60s        → "Ns"
+ *  - < 60m        → "Nm Ss"
+ *  - < 24h        → "Nh Mm"
+ *  - otherwise    → "Nd Hh"
+ */
+export function formatUptime(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "—";
+  const totalSeconds = Math.floor(ms / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes < 60) return `${minutes}m ${seconds}s`;
+  const hours = Math.floor(minutes / 60);
+  const remMinutes = minutes % 60;
+  if (hours < 24) return `${hours}h ${remMinutes}m`;
+  const days = Math.floor(hours / 24);
+  const remHours = hours % 24;
+  return `${days}d ${remHours}h`;
+}
+
+/**
+ * Format a byte count using binary units (KiB/MiB/GiB, surfaced as
+ * "KB/MB/GB" for readability). KB and MB use one decimal below 10 and
+ * round above; GB keeps two decimals below 10 so half-GB changes stay
+ * visible on memory dashboards, and drops to one decimal above.
+ */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "—";
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb < 10 ? kb.toFixed(1) : Math.round(kb)} KB`;
+  const mb = kb / 1024;
+  if (mb < 1024) return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)} MB`;
+  const gb = mb / 1024;
+  return `${gb < 10 ? gb.toFixed(2) : gb.toFixed(1)} GB`;
+}

package/src/utils/index.ts

@@ -0,0 +1,10 @@
+export { copyText } from './copy-text';
+export { formatBytes, formatDuration, formatUptime, truncateText } from './format';
+export { timeAgo } from './time-ago';
+export {
+  getToolCategory,
+  getToolDisplayMetadata,
+  getToolErrorText,
+  TOOL_CATEGORY_ICONS,
+} from './tool-display';
+export { cn } from '../lib/utils';

package/src/utils/time-ago.ts

@@ -0,0 +1,9 @@
+export function timeAgo(ts: number): string {
+  const secs = Math.floor((Date.now() - ts) / 1000);
+  if (secs < 5) return 'just now';
+  if (secs < 60) return `${secs}s ago`;
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  return `${hrs}h ago`;
+}

package/src/utils/tool-display.ts

@@ -0,0 +1,238 @@
+import type { ToolPart } from "../types/parts";
+import type { ToolDisplayMetadata } from "../types/tool-display";
+import type { ToolCategory } from "../types/run";
+
+// ---------------------------------------------------------------------------
+// Tool name normalisation
+// ---------------------------------------------------------------------------
+
+const TOOL_NAME_PREFIX = "tool:";
+
+function normalizeToolName(tool: string | undefined): string {
+  const n = tool?.toLowerCase() ?? "";
+  return n.startsWith(TOOL_NAME_PREFIX) ? n.slice(TOOL_NAME_PREFIX.length) : n;
+}
+
+// ---------------------------------------------------------------------------
+// Input helpers
+// ---------------------------------------------------------------------------
+
+function extractString(obj: unknown, key: string): string | undefined {
+  if (
+    typeof obj === "object" &&
+    obj !== null &&
+    key in (obj as Record<string, unknown>)
+  ) {
+    const val = (obj as Record<string, unknown>)[key];
+    if (typeof val === "string") return val;
+  }
+  return undefined;
+}
+
+function extractCommand(input: unknown): string | undefined {
+  if (typeof input === "string") return input;
+  return extractString(input, "command") ?? extractString(input, "cmd");
+}
+
+function extractFilePath(input: unknown): string | undefined {
+  return (
+    extractString(input, "file_path") ??
+    extractString(input, "path") ??
+    extractString(input, "filePath") ??
+    extractString(input, "file")
+  );
+}
+
+function cleanPath(path: string): string {
+  const parts = path.split("/");
+  return parts.length > 3 ? ".../" + parts.slice(-2).join("/") : path;
+}
+
+// ---------------------------------------------------------------------------
+// Category icons (emoji shorthand used by compact views)
+// ---------------------------------------------------------------------------
+
+export const TOOL_CATEGORY_ICONS: Record<ToolCategory, string> = {
+  command: "terminal",
+  write: "file-plus",
+  read: "file-text",
+  search: "search",
+  edit: "file-edit",
+  task: "cpu",
+  web: "globe",
+  todo: "check-square",
+  other: "box",
+};
+
+// ---------------------------------------------------------------------------
+// Category classification
+// ---------------------------------------------------------------------------
+
+export function getToolCategory(toolName: string): ToolCategory {
+  const name = normalizeToolName(toolName);
+  switch (name) {
+    case "bash":
+    case "shell":
+    case "command":
+    case "execute":
+      return "command";
+    case "write":
+    case "write_file":
+    case "create_file":
+      return "write";
+    case "read":
+    case "read_file":
+    case "cat":
+      return "read";
+    case "grep":
+    case "search":
+    case "rg":
+      return "search";
+    case "edit":
+    case "patch":
+    case "sed":
+      return "edit";
+    case "glob":
+    case "find":
+    case "ls":
+      return "search";
+    case "web_search":
+    case "web_fetch":
+    case "fetch":
+      return "web";
+    case "task":
+    case "agent":
+    case "spawn":
+      return "task";
+    case "todo":
+    case "todo_write":
+      return "todo";
+    default:
+      return "other";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main metadata resolver
+// ---------------------------------------------------------------------------
+
+export function getToolDisplayMetadata(part: ToolPart): ToolDisplayMetadata {
+  const name = normalizeToolName(part.tool);
+  const input = part.state.status !== "pending" ? part.state.input : undefined;
+  const filePath = extractFilePath(input);
+  const command = extractCommand(input);
+
+  switch (name) {
+    case "bash":
+    case "shell":
+    case "command":
+    case "execute":
+      return {
+        title: "Run command",
+        description: command ? truncateCommand(command) : undefined,
+        displayVariant: "command",
+        commandSnippet: command,
+      };
+
+    case "write":
+    case "write_file":
+    case "create_file":
+      return {
+        title: filePath ? `Write ${cleanPath(filePath)}` : "Write file",
+        description: filePath,
+        displayVariant: "write-file",
+        targetPath: filePath,
+      };
+
+    case "edit":
+    case "patch":
+      return {
+        title: filePath ? `Edit ${cleanPath(filePath)}` : "Edit file",
+        description: filePath,
+        hasDiffOutput: true,
+        diffFilePath: filePath,
+        displayVariant: "diff",
+        targetPath: filePath,
+      };
+
+    case "read":
+    case "read_file":
+    case "cat":
+      return {
+        title: filePath ? `Read ${cleanPath(filePath)}` : "Read file",
+        description: filePath,
+        displayVariant: "read-file",
+        targetPath: filePath,
+      };
+
+    case "grep":
+    case "search":
+    case "rg": {
+      const pattern = extractString(input, "pattern");
+      return {
+        title: pattern ? `Search: ${pattern}` : "Search",
+        description: pattern,
+        displayVariant: "grep",
+      };
+    }
+
+    case "glob":
+    case "find":
+    case "ls": {
+      const pattern = extractString(input, "pattern");
+      return {
+        title: pattern ? `Find: ${pattern}` : "Find files",
+        description: pattern,
+        displayVariant: "glob",
+      };
+    }
+
+    case "web_search":
+    case "web_fetch":
+    case "fetch": {
+      const query =
+        extractString(input, "query") ?? extractString(input, "url");
+      return {
+        title: query ? `Web: ${truncateCommand(query)}` : "Web search",
+        description: query,
+        displayVariant: "web-search",
+      };
+    }
+
+    case "task":
+    case "agent":
+    case "spawn": {
+      const desc =
+        extractString(input, "description") ??
+        extractString(input, "prompt");
+      return {
+        title: desc ? `Task: ${truncateCommand(desc)}` : "Agent task",
+        description: desc,
+      };
+    }
+
+    default:
+      return {
+        title: part.tool || "Tool",
+        description:
+          command ??
+          filePath ??
+          extractString(input, "pattern") ??
+          extractString(input, "query"),
+      };
+  }
+}
+
+function truncateCommand(cmd: string): string {
+  const first = cmd.split("\n")[0];
+  return first.length > 60 ? first.slice(0, 57) + "..." : first;
+}
+
+/** Extract error text from a tool part, if any. */
+export function getToolErrorText(
+  part: ToolPart,
+  fallback?: string,
+): string | undefined {
+  if (part.state.status !== "error") return undefined;
+  return part.state.error || fallback;
+}