feat(inspector): custom actor inspector tab UI (Test/Mounts/Software/Processes/Filesystem)

The shared Vite/React inspector-tabs source that fetches live actor actions and renders the custom tabs.

Author: abcxff

packages/agentos/src/actor.ts

@@ -11,7 +11,8 @@
  */
 
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import common from "@agentos-software/common";
 import {
 	OPT_AGENTOS_BIN,
@@ -399,6 +400,16 @@ function buildNativeFactoryBuilder<TConnParams>(
 			// spawns the bundled binary rather than relying on `agentos-sidecar`
 			// being on PATH.
 			sidecarPath: getSidecarPath(),
+			// Custom inspector tabs. The native-plugin path bypasses the normal
+			// actor-config assembly (`buildActorConfig`/`inspectorTabs`), so the
+			// tabs MUST ride on the plugin options: the Rust NAPI binding
+			// `from_native_plugin` forwards `inspectorTabs` into the actor config so
+			// the dashboard serves `/inspector/custom-tabs/<id>/` and advertises them
+			// in `tab-config`. (Setting `actor({ inspector })` alone does nothing for
+			// native-plugin actors.)
+			inspectorTabs: AGENTOS_INSPECTOR_CONFIG.tabs,
+		} as NapiNativePluginOptions & {
+			inspectorTabs: typeof AGENTOS_INSPECTOR_CONFIG.tabs;
 		};
 		return runtime.createNativePluginFactory(options);
 	};
@@ -465,6 +476,34 @@ export const DEFAULT_AGENTOS_ACTOR_OPTIONS = {
 	maxQueueMessageSize: ACTOR_NEVER_HIT_MESSAGE_BYTES,
 } as const;
 
+// Absolute path to the built inspector-tabs app (the shared Vite bundle). All
+// custom tabs share this one `source` dir; the app routes on the
+// `/inspector/custom-tabs/<id>/` URL segment. Resolves from both `src/` (tsx dev
+// / the demo) and the published `dist/`, since `assets/` sits at the package
+// root in both layouts.
+const INSPECTOR_TABS_ASSET_DIR = join(
+	dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"assets",
+	"inspector-tabs-app",
+);
+
+// Custom inspector tabs shipped by agent-os. Ids MUST match the `TABS` registry
+// in `src/inspector-tabs/main.tsx`. The built-in rivetkit tabs are hidden so the
+// dashboard shows only the agent-os tabs.
+const AGENTOS_INSPECTOR_CONFIG = {
+	tabs: [
+		{ id: "transcript", label: "Transcript", source: INSPECTOR_TABS_ASSET_DIR, icon: "comments" },
+		{ id: "filesystem", label: "Filesystem", source: INSPECTOR_TABS_ASSET_DIR, icon: "folder-tree" },
+		{ id: "processes", label: "Processes", source: INSPECTOR_TABS_ASSET_DIR, icon: "microchip" },
+		{ id: "software", label: "Software", source: INSPECTOR_TABS_ASSET_DIR, icon: "box-archive" },
+		{ id: "mounts", label: "Mounts", source: INSPECTOR_TABS_ASSET_DIR, icon: "hard-drive" },
+		...(["workflow", "database", "state", "queue", "connections", "console"].map(
+			(id) => ({ id, hidden: true as const }),
+		)),
+	],
+};
+
 export function agentOs<TConnParams = undefined>(
 	config: AgentOsActorConfigInput<TConnParams>,
 ): AgentOsActorDefinition<TConnParams> {
@@ -487,6 +526,10 @@ export function agentOs<TConnParams = undefined>(
 	const definition = actor({
 		actions: {},
 		options: actorOptions,
+		// Register the custom agent-os inspector tabs (and hide the built-in
+		// rivetkit tabs) so the dashboard renders the agent-os UI. Without this
+		// the shipped tab assets are never surfaced.
+		inspector: AGENTOS_INSPECTOR_CONFIG,
 	} as Parameters<
 		typeof actor
 	>[0]) as unknown as AgentOsActorDefinition<TConnParams>;

packages/agentos/src/inspector-tabs/common.tsx

@@ -0,0 +1,168 @@
+import type { ReactNode } from "react";
+import { cn } from "./lib/cn";
+import React, { useState } from "react";
+
+/** Centered empty/placeholder state filling the tab body. */
+export function AgentOsEmpty({ children }: { children: ReactNode }) {
+	return (
+		<div className="flex h-full flex-1 items-center justify-center p-8 text-center text-sm text-muted-foreground">
+			{children}
+		</div>
+	);
+}
+
+export type DotColor = "green" | "amber" | "red" | "muted";
+const DOT_CLASS: Record<DotColor, string> = {
+	green: "text-green-500",
+	amber: "text-amber-500",
+	red: "text-red-500",
+	muted: "text-muted-foreground/50",
+};
+
+export function StatusDot({ color, className }: { color: DotColor; className?: string }) {
+	return (
+		<svg
+			viewBox="0 0 8 8"
+			className={cn("size-2 shrink-0 fill-current", DOT_CLASS[color], className)}
+			aria-hidden="true"
+		>
+			<circle cx="4" cy="4" r="4" />
+		</svg>
+	);
+}
+
+/** Inline chevron (replaces @rivet-gg/icons faChevronRight). */
+export function ChevronRight({ className }: { className?: string }) {
+	return (
+		<svg
+			className={className}
+			viewBox="0 0 16 16"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth="2"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			aria-hidden="true"
+		>
+			<path d="M6 4l4 4-4 4" />
+		</svg>
+	);
+}
+
+/** Clipboard + check glyphs for the copy button. */
+function CopyIcon({ className }: { className?: string }) {
+	return (
+		<svg
+			className={className}
+			viewBox="0 0 16 16"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth="1.5"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			aria-hidden="true"
+		>
+			<rect x="5.5" y="5.5" width="8" height="8" rx="1.5" />
+			<path d="M10.5 5.5V4A1.5 1.5 0 0 0 9 2.5H4A1.5 1.5 0 0 0 2.5 4v5A1.5 1.5 0 0 0 4 10.5h1.5" />
+		</svg>
+	);
+}
+function CheckIcon({ className }: { className?: string }) {
+	return (
+		<svg
+			className={className}
+			viewBox="0 0 16 16"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth="2"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			aria-hidden="true"
+		>
+			<path d="M3 8.5l3.5 3.5L13 4.5" />
+		</svg>
+	);
+}
+
+/** Small, subtle copy-to-clipboard button. Shows a check briefly on success. */
+export function CopyButton({ value, className }: { value: string; className?: string }) {
+	const [copied, setCopied] = useState(false);
+	return (
+		<button
+			type="button"
+			aria-label={copied ? "Copied" : "Copy"}
+			title={copied ? "Copied" : "Copy"}
+			onClick={(e) => {
+				e.stopPropagation();
+				navigator.clipboard
+					?.writeText(value)
+					.then(() => {
+						setCopied(true);
+						setTimeout(() => setCopied(false), 1200);
+					})
+					.catch(() => {});
+			}}
+			className={cn(
+				"inline-flex size-5 items-center justify-center rounded text-muted-foreground/40 transition-colors hover:bg-muted hover:text-foreground",
+				copied && "text-green-500",
+				className,
+			)}
+		>
+			{copied ? <CheckIcon className="size-3" /> : <CopyIcon className="size-3.5" />}
+		</button>
+	);
+}
+
+/** Inline folder/file glyphs for the filesystem tree. */
+export function FileGlyph({ dir, className }: { dir: boolean; className?: string }) {
+	return (
+		<svg
+			className={className}
+			viewBox="0 0 16 16"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth="1.5"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			aria-hidden="true"
+		>
+			{dir ? (
+				<path d="M1.5 4.5A1 1 0 0 1 2.5 3.5h3l1.5 1.5h5.5a1 1 0 0 1 1 1v6a1 1 0 0 1-1 1h-10a1 1 0 0 1-1-1z" />
+			) : (
+				<>
+					<path d="M4 1.5h5l3 3v9a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1v-11a1 1 0 0 1 1-1z" />
+					<path d="M9 1.5v3h3" />
+				</>
+			)}
+		</svg>
+	);
+}
+
+/** Human-readable byte size; "—" for nullish. */
+export function formatBytes(bytes?: number | null): string {
+	if (bytes == null) return "—";
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KiB", "MiB", "GiB", "TiB"];
+	let value = bytes / 1024;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit += 1;
+	}
+	const f = value >= 100 ? value.toFixed(0) : value.toFixed(1);
+	return `${f.replace(/\.0$/, "")} ${units[unit]}`;
+}
+
+/** Compact relative time ("5s ago", "3m ago") from an epoch-ms value. */
+export function relativeTime(ms?: number | null): string {
+	if (ms == null) return "—";
+	const diff = Date.now() - ms;
+	if (diff < 0) return "just now";
+	const s = Math.floor(diff / 1000);
+	if (s < 60) return `${s}s ago`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m}m ago`;
+	const h = Math.floor(m / 60);
+	if (h < 24) return `${h}h ago`;
+	return `${Math.floor(h / 24)}d ago`;
+}

packages/agentos/src/inspector-tabs/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>agentOS inspector</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./main.tsx"></script>
+	</body>
+</html>

packages/agentos/src/inspector-tabs/lib/actor-client.ts

@@ -0,0 +1,83 @@
+// Same-origin agentOS action client for inspector-tab iframes.
+//
+// The dashboard serves each custom tab at `/gateway/<actorId>@<authToken>/
+// inspector/custom-tabs/<id>/` and posts an `init` message with the actorId +
+// authToken. We call actor actions with the stateless JSON encoding — a plain
+// `fetch`, no rivetkit client, no websocket (proven by the vanilla Mounts tab).
+
+import { isMockMode, mockCallAction } from "./mock";
+
+interface Auth {
+	actorId: string;
+	authToken: string;
+}
+
+let auth: Auth | undefined;
+
+export function setAuth(next: Auth): void {
+	auth = next;
+}
+
+export function getAuth(): Auth | undefined {
+	return auth;
+}
+
+/** The tab id this iframe is rendering, parsed from its own gateway URL. */
+export function tabIdFromUrl(): string | undefined {
+	const parts = window.location.pathname.split("/").filter(Boolean);
+	const idx = parts.indexOf("custom-tabs");
+	return idx >= 0 ? parts[idx + 1] : undefined;
+}
+
+export interface ActionError {
+	group?: string;
+	code?: string;
+	message?: string;
+}
+
+/** Invoke an actor action over the same-origin gateway (JSON encoding).
+ *
+ * `timeoutMs` aborts the request (via AbortController) on expiry — important
+ * because some VM actions (e.g. `stat` on /proc, /sys) hang server-side, and an
+ * un-aborted hung fetch keeps a browser connection slot open. Enough of those
+ * exhaust the ~6-connection pool and starve every other request. Aborting frees
+ * the slot.
+ */
+export async function callAction<T = unknown>(
+	name: string,
+	args: unknown[] = [],
+	opts: { timeoutMs?: number } = {},
+): Promise<T> {
+	// Dummy/offline mode: serve every action from in-memory fixtures, no actor.
+	if (isMockMode()) return mockCallAction<T>(name, args);
+	if (!auth) throw new Error("not initialized: missing actorId/authToken");
+	const seg = `${encodeURIComponent(auth.actorId)}@${encodeURIComponent(auth.authToken)}`;
+	const url = `/gateway/${seg}/action/${encodeURIComponent(name)}`;
+	const ctrl = new AbortController();
+	const timer = opts.timeoutMs
+		? setTimeout(() => ctrl.abort(), opts.timeoutMs)
+		: undefined;
+	let res: Response;
+	try {
+		res = await fetch(url, {
+			method: "POST",
+			headers: { "x-rivet-encoding": "json" },
+			body: JSON.stringify({ args }),
+			signal: ctrl.signal,
+		});
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+	const text = await res.text();
+	let body: { output?: T } & ActionError;
+	try {
+		body = text ? JSON.parse(text) : {};
+	} catch {
+		throw new Error(`non-JSON response (HTTP ${res.status}): ${text.slice(0, 200)}`);
+	}
+	if (!res.ok) {
+		const label = body.code ? `${body.group}/${body.code}` : `HTTP ${res.status}`;
+		throw new Error(`${label}: ${body.message ?? text}`);
+	}
+	return body.output as T;
+}

packages/agentos/src/inspector-tabs/lib/cn.ts

@@ -0,0 +1,8 @@
+// Vendored from the rivet design system (@/components/lib/utils.ts → `cn`).
+// Self-contained: only clsx + tailwind-merge.
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}