@stigmer/react 0.4.8 → 0.5.0

package/src/runner/RunnerListPanel.tsx

@@ -22,6 +22,8 @@ import {
   phaseDotColor,
   PHASE_SORT_ORDER,
 } from "./phase";
+import { EmptyState } from "../empty-state";
+import { RunnerIcon, PhaseBadge, formatRelativeTime } from "./shared";
 
 const SYSTEM_MANAGED_LABEL = "stigmer.ai/system-managed";
 const TRANSITIONAL_POLL_MS = 5_000;
@@ -35,6 +37,9 @@ type ConfirmingState = {
 // Public API
 // ---------------------------------------------------------------------------
 
+/** Sort key for the runner list. */
+export type RunnerSortKey = "phase" | "name" | "heartbeat" | "executions";
+
 /** Props for {@link RunnerListPanel}. */
 export interface RunnerListPanelProps {
   /** Organization slug to scope the runner list. */
@@ -50,6 +55,28 @@ export interface RunnerListPanelProps {
    * @default false
    */
   readonly includeSystemManaged?: boolean;
+  /**
+   * Restrict the list to runners in the specified phases.
+   *
+   * When provided, only runners whose phase is in this array are shown.
+   * When omitted or empty, all phases are included.
+   */
+  readonly filterPhases?: readonly RunnerPhase[];
+  /**
+   * Client-side text filter. When provided, only runners whose name
+   * or hostname contains this substring (case-insensitive) are shown.
+   */
+  readonly searchQuery?: string;
+  /**
+   * Sort key for ordering the runner list.
+   * @default "phase"
+   */
+  readonly sortBy?: RunnerSortKey;
+  /**
+   * Sort direction.
+   * @default "asc"
+   */
+  readonly sortDirection?: "asc" | "desc";
   /** Expose refetch so parent components can trigger a list refresh. */
   readonly onRefetchRef?: (refetch: () => void) => void;
   /**
@@ -106,6 +133,10 @@ export interface RunnerListPanelProps {
 export function RunnerListPanel({
   org,
   includeSystemManaged = false,
+  filterPhases,
+  searchQuery,
+  sortBy = "phase",
+  sortDirection = "asc",
   onRefetchRef,
   onStopped,
   onDeleted,
@@ -130,10 +161,33 @@ export function RunnerListPanel({
     onRefetchRef(refetch);
   }
 
-  const sorted = useMemo(
-    () => [...runners].sort(phaseThenName),
-    [runners],
-  );
+  const hasActiveFilters =
+    (filterPhases != null && filterPhases.length > 0) ||
+    (searchQuery != null && searchQuery.trim().length > 0);
+
+  const sorted = useMemo(() => {
+    let result = [...runners];
+
+    if (filterPhases != null && filterPhases.length > 0) {
+      const phaseSet = new Set(filterPhases);
+      result = result.filter((r) =>
+        phaseSet.has(r.status?.phase ?? RunnerPhase.UNSPECIFIED),
+      );
+    }
+
+    if (searchQuery != null && searchQuery.trim().length > 0) {
+      const q = searchQuery.trim().toLowerCase();
+      result = result.filter((r) => {
+        const name = (r.metadata?.name ?? "").toLowerCase();
+        const hostname = (r.status?.connectionInfo?.hostname ?? "").toLowerCase();
+        return name.includes(q) || hostname.includes(q);
+      });
+    }
+
+    const comparator = buildComparator(sortBy, sortDirection);
+    result.sort(comparator);
+    return result;
+  }, [runners, filterPhases, searchQuery, sortBy, sortDirection]);
 
   const handleRequestConfirm = useCallback(
     (runnerId: string, action: "stop" | "delete") => {
@@ -175,31 +229,35 @@ export function RunnerListPanel({
 
   if (error) {
     return (
-      <p className={cn("text-destructive text-xs", className)} role="alert">
-        {getUserMessage(error)}
-      </p>
+      <div className={className}>
+        <EmptyState
+          variant="error"
+          resourceLabel="runners"
+          errorMessage={getUserMessage(error)}
+          action={{ label: "Retry", onClick: refetch }}
+        />
+      </div>
     );
   }
 
   if (sorted.length === 0) {
     return (
-      <div
-        className={cn(
-          "flex flex-col items-center gap-2 py-8 text-center",
-          className,
-        )}
-      >
-        <RunnerIcon size={24} />
-        <p className="text-muted-foreground text-xs">
-          No runners registered.
-        </p>
-        <p className="text-muted-foreground-subtle max-w-xs text-[0.65rem]">
-          Start a runner with{" "}
-          <code className="bg-muted rounded px-1 py-0.5 font-mono text-[0.6rem]">
-            stigmer up
-          </code>{" "}
-          or launch one from your browser with the button above.
-        </p>
+      <div className={className}>
+        <EmptyState
+          variant={hasActiveFilters ? "zero-results" : "first-use"}
+          resourceLabel="runners"
+          icon={hasActiveFilters ? undefined : <RunnerIcon size={24} />}
+          title={
+            hasActiveFilters
+              ? "No runners match your filters"
+              : undefined
+          }
+          description={
+            hasActiveFilters
+              ? "Try adjusting your search or removing some filters."
+              : "Start a runner with stigmer up or launch one from your browser."
+          }
+        />
       </div>
     );
   }
@@ -571,106 +629,63 @@ function ActionMenu({
   );
 }
 
-// ---------------------------------------------------------------------------
-// PhaseBadge (internal)
-// ---------------------------------------------------------------------------
-
-function PhaseBadge({ phase }: { phase: RunnerPhase }) {
-  const starting = phase === RunnerPhase.STARTING;
-  return (
-    <span className="inline-flex shrink-0 items-center gap-1">
-      {starting ? (
-        <span
-          className="inline-block h-2.5 w-2.5 animate-spin rounded-full border border-primary border-t-transparent"
-          aria-hidden="true"
-        />
-      ) : (
-        <span
-          className={`inline-block h-1.5 w-1.5 rounded-full ${phaseDotColor(phase)}`}
-          aria-hidden="true"
-        />
-      )}
-      <span className={cn("text-[0.65rem]", starting ? "text-primary" : "text-muted-foreground")}>
-        {phaseLabel(phase)}
-      </span>
-    </span>
-  );
-}
-
 // ---------------------------------------------------------------------------
 // Utilities
 // ---------------------------------------------------------------------------
 
-function phaseThenName(a: Runner, b: Runner): number {
-  const pa = a.status?.phase ?? RunnerPhase.UNSPECIFIED;
-  const pb = b.status?.phase ?? RunnerPhase.UNSPECIFIED;
-  const order = PHASE_SORT_ORDER[pa] - PHASE_SORT_ORDER[pb];
-  if (order !== 0) return order;
-  return (a.metadata?.name ?? "").localeCompare(b.metadata?.name ?? "");
-}
-
-function formatRelativeTime(date: Date): string {
-  const diffMs = Date.now() - date.getTime();
+function buildComparator(
+  sortBy: RunnerSortKey,
+  direction: "asc" | "desc",
+): (a: Runner, b: Runner) => number {
+  const dir = direction === "desc" ? -1 : 1;
 
-  if (diffMs < 0) return "just now";
+  return (a, b) => {
+    let order: number;
 
-  const seconds = Math.floor(diffMs / 1000);
-  if (seconds < 60) return "just now";
-
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m ago`;
-
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
+    switch (sortBy) {
+      case "name":
+        order = (a.metadata?.name ?? "").localeCompare(
+          b.metadata?.name ?? "",
+        );
+        break;
+
+      case "heartbeat": {
+        const ha = a.status?.lastHeartbeatAt;
+        const hb = b.status?.lastHeartbeatAt;
+        const ta = ha ? timestampDate(ha).getTime() : 0;
+        const tb = hb ? timestampDate(hb).getTime() : 0;
+        order = ta - tb;
+        break;
+      }
 
-  const days = Math.floor(hours / 24);
-  if (days < 30) return `${days}d ago`;
+      case "executions":
+        order =
+          (a.status?.currentExecutions ?? 0) -
+          (b.status?.currentExecutions ?? 0);
+        break;
+
+      case "phase":
+      default: {
+        const pa = a.status?.phase ?? RunnerPhase.UNSPECIFIED;
+        const pb = b.status?.phase ?? RunnerPhase.UNSPECIFIED;
+        order = PHASE_SORT_ORDER[pa] - PHASE_SORT_ORDER[pb];
+        if (order !== 0) return order * dir;
+        return (a.metadata?.name ?? "").localeCompare(
+          b.metadata?.name ?? "",
+        );
+      }
+    }
 
-  return date.toLocaleDateString(undefined, {
-    month: "short",
-    day: "numeric",
-    year: "numeric",
-  });
+    if (order !== 0) return order * dir;
+    // Stable secondary sort by name
+    return (a.metadata?.name ?? "").localeCompare(b.metadata?.name ?? "");
+  };
 }
 
 // ---------------------------------------------------------------------------
-// Icons
+// Icons (internal to RunnerListPanel)
 // ---------------------------------------------------------------------------
 
-function RunnerIcon({
-  size = 14,
-  className,
-}: {
-  size?: number;
-  className?: string;
-}) {
-  return (
-    <svg
-      width={size}
-      height={size}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden="true"
-      className={cn("shrink-0 text-muted-foreground", className)}
-    >
-      <rect x="4" y="4" width="16" height="16" rx="2" />
-      <rect x="9" y="9" width="6" height="6" />
-      <path d="M15 2v2" />
-      <path d="M15 20v2" />
-      <path d="M2 15h2" />
-      <path d="M2 9h2" />
-      <path d="M20 15h2" />
-      <path d="M20 9h2" />
-      <path d="M9 2v2" />
-      <path d="M9 20v2" />
-    </svg>
-  );
-}
-
 function MoreVerticalIcon() {
   return (
     <svg

package/src/runner/index.ts

@@ -1,3 +1,12 @@
+export { useRunner } from "./useRunner";
+export type {
+  UseRunnerReturn,
+  UseRunnerOptions,
+} from "./useRunner";
+
+export { RunnerDetailView } from "./RunnerDetailView";
+export type { RunnerDetailViewProps } from "./RunnerDetailView";
+
 export { useRunnerList } from "./useRunnerList";
 export type {
   UseRunnerListOptions,
@@ -39,7 +48,7 @@ export type {
 } from "./useRunnerFileBrowser";
 
 export { RunnerListPanel } from "./RunnerListPanel";
-export type { RunnerListPanelProps } from "./RunnerListPanel";
+export type { RunnerListPanelProps, RunnerSortKey } from "./RunnerListPanel";
 
 export { WorkspaceRunnerSelector } from "./WorkspaceRunnerSelector";
 export type { WorkspaceRunnerSelectorProps } from "./WorkspaceRunnerSelector";
@@ -51,3 +60,6 @@ export {
   isTransitionalPhase,
   PHASE_SORT_ORDER,
 } from "./phase";
+
+export { RunnerIcon, PhaseBadge, formatRelativeTime } from "./shared";
+export type { RunnerIconProps, PhaseBadgeProps } from "./shared";

package/src/runner/shared.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_pb";
+import { phaseLabel, phaseDotColor } from "./phase";
+
+// ---------------------------------------------------------------------------
+// RunnerIcon
+// ---------------------------------------------------------------------------
+
+/** Props for {@link RunnerIcon}. */
+export interface RunnerIconProps {
+  readonly size?: number;
+  readonly className?: string;
+}
+
+/**
+ * CPU-chip icon representing a runner. Used across the runner list,
+ * fleet section, and empty states.
+ */
+export function RunnerIcon({ size = 14, className }: RunnerIconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={cn("shrink-0 text-muted-foreground", className)}
+    >
+      <rect x="4" y="4" width="16" height="16" rx="2" />
+      <rect x="9" y="9" width="6" height="6" />
+      <path d="M15 2v2" />
+      <path d="M15 20v2" />
+      <path d="M2 15h2" />
+      <path d="M2 9h2" />
+      <path d="M20 15h2" />
+      <path d="M20 9h2" />
+      <path d="M9 2v2" />
+      <path d="M9 20v2" />
+    </svg>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// PhaseBadge
+// ---------------------------------------------------------------------------
+
+/** Props for {@link PhaseBadge}. */
+export interface PhaseBadgeProps {
+  readonly phase: RunnerPhase;
+}
+
+/**
+ * Compact badge showing a colored dot indicator and label for a runner
+ * phase. Renders a spinning indicator for the STARTING phase.
+ */
+export function PhaseBadge({ phase }: PhaseBadgeProps) {
+  const starting = phase === RunnerPhase.STARTING;
+  return (
+    <span className="inline-flex shrink-0 items-center gap-1">
+      {starting ? (
+        <span
+          className="inline-block h-2.5 w-2.5 animate-spin rounded-full border border-primary border-t-transparent"
+          aria-hidden="true"
+        />
+      ) : (
+        <span
+          className={`inline-block h-1.5 w-1.5 rounded-full ${phaseDotColor(phase)}`}
+          aria-hidden="true"
+        />
+      )}
+      <span
+        className={cn(
+          "text-[0.65rem]",
+          starting ? "text-primary" : "text-muted-foreground",
+        )}
+      >
+        {phaseLabel(phase)}
+      </span>
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// formatRelativeTime
+// ---------------------------------------------------------------------------
+
+/**
+ * Formats a Date as a compact relative time string.
+ *
+ * - < 60s → "just now"
+ * - < 60m → "5m ago"
+ * - < 24h → "3h ago"
+ * - < 30d → "12d ago"
+ * - otherwise → locale short date
+ */
+export function formatRelativeTime(date: Date): string {
+  const diffMs = Date.now() - date.getTime();
+
+  if (diffMs < 0) return "just now";
+
+  const seconds = Math.floor(diffMs / 1000);
+  if (seconds < 60) return "just now";
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days}d ago`;
+
+  return date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  });
+}

package/src/runner/useRunner.ts

@@ -0,0 +1,59 @@
+"use client";
+
+import type { Runner } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { useFetch, type UseFetchOptions } from "../internal/useFetch";
+
+/** Return value of {@link useRunner}. */
+export interface UseRunnerReturn {
+  /** The fetched runner, or `null` while loading or on error. */
+  readonly runner: Runner | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed fetch, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the runner from the server. */
+  readonly refetch: () => void;
+}
+
+/** Options for {@link useRunner}. */
+export interface UseRunnerOptions {
+  /**
+   * Poll interval in milliseconds for automatic re-fetching.
+   *
+   * Useful for monitoring runner status transitions (e.g. Starting
+   * to Ready) without requiring manual refresh.
+   */
+  readonly refetchInterval?: UseFetchOptions["refetchInterval"];
+}
+
+/**
+ * Data hook that fetches a single runner by ID.
+ *
+ * Calls `stigmer.runner.get(id)` and returns the result with
+ * loading/error state. Returns `null` runner when `id` is `null`
+ * (no runner selected).
+ *
+ * @example
+ * ```tsx
+ * const { runner, isLoading, error } = useRunner(runnerId);
+ * ```
+ */
+export function useRunner(
+  id: string | null,
+  options?: UseRunnerOptions,
+): UseRunnerReturn {
+  const stigmer = useStigmer();
+  const refetchInterval = options?.refetchInterval;
+
+  const { data: runner, isLoading, error, refetch } = useFetch(
+    id
+      ? async () => stigmer.runner.get(id)
+      : null,
+    [stigmer, id],
+    null as Runner | null,
+    { refetchInterval },
+  );
+
+  return { runner, isLoading, error, refetch };
+}

package/src/session/__tests__/group-sessions.test.ts

@@ -1,9 +1,11 @@
 import { describe, it, expect } from "vitest";
 import { create } from "@bufbuild/protobuf";
 import { timestampFromDate } from "@bufbuild/protobuf/wkt";
-import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import {
-  ApiResourceAuditStatusSchema,
+  SessionSchema,
+  SessionStatusSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import {
   ApiResourceAuditSchema,
   ApiResourceAuditInfoSchema,
 } from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
@@ -18,7 +20,7 @@ function makeSession(date: Date | null) {
     auditInfo.createdAt = timestampFromDate(date);
     const audit = create(ApiResourceAuditSchema);
     audit.specAudit = auditInfo;
-    const status = create(ApiResourceAuditStatusSchema);
+    const status = create(SessionStatusSchema);
     status.audit = audit;
     session.status = status;
   }