@stigmer/react 0.0.101 → 0.1.0

package/src/platform-client/usePlatformClient.ts

@@ -1,9 +1,8 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link usePlatformClient}. */
 export interface UsePlatformClientReturn {
@@ -11,6 +10,8 @@ export interface UsePlatformClientReturn {
   readonly platformClient: PlatformClient | null;
   /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch from the server. */
@@ -44,43 +45,12 @@ export function usePlatformClient(
   id: string | null,
 ): UsePlatformClientReturn {
   const stigmer = useStigmer();
-  const [platformClient, setPlatformClient] =
-    useState<PlatformClient | null>(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+  const { data: platformClient, isLoading, isRefetching, error, refetch } = useFetch(
+    id ? () => stigmer.platformclient.get(id) : null,
+    [id, stigmer],
+    null as PlatformClient | null,
+  );
 
-  useEffect(() => {
-    if (!id) {
-      setPlatformClient(null);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.platformclient.get(id).then(
-      (result) => {
-        if (cancelled.current) return;
-        setPlatformClient(result);
-        setIsLoading(false);
-      },
-      (err) => {
-        if (cancelled.current) return;
-        setError(toError(err));
-        setIsLoading(false);
-      },
-    );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [id, stigmer, fetchKey]);
-
-  return { platformClient, isLoading, error, refetch };
+  return { platformClient, isLoading, isRefetching, error, refetch };
 }

package/src/platform-client/usePlatformClientList.ts

@@ -1,11 +1,10 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
 import { ListPlatformClientsByOrgInputSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/io_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link usePlatformClientList}. */
 export interface UsePlatformClientListReturn {
@@ -13,6 +12,8 @@ export interface UsePlatformClientListReturn {
   readonly platformClients: readonly PlatformClient[];
   /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch from the server. */
@@ -51,46 +52,17 @@ export function usePlatformClientList(
   org: string | null,
 ): UsePlatformClientListReturn {
   const stigmer = useStigmer();
-  const [platformClients, setPlatformClients] = useState<PlatformClient[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+  const { data: platformClients, isLoading, isRefetching, error, refetch } = useFetch(
+    org
+      ? () =>
+          stigmer.platformclient
+            .listByOrg(create(ListPlatformClientsByOrgInputSchema, { org }))
+            .then((r) => [...r.entries])
+      : null,
+    [org, stigmer],
+    [] as PlatformClient[],
+  );
 
-  useEffect(() => {
-    if (!org) {
-      setPlatformClients([]);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.platformclient
-      .listByOrg(
-        create(ListPlatformClientsByOrgInputSchema, { org }),
-      )
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setPlatformClients([...result.entries]);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [org, stigmer, fetchKey]);
-
-  return { platformClients, isLoading, error, refetch };
+  return { platformClients, isLoading, isRefetching, error, refetch };
 }

package/src/runner/RunnerListPanel.tsx

@@ -17,12 +17,14 @@ import { useStopRunner } from "./useStopRunner";
 import { useDeleteRunner } from "./useDeleteRunner";
 import {
   isActivePhase,
+  isTransitionalPhase,
   phaseLabel,
   phaseDotColor,
   PHASE_SORT_ORDER,
 } from "./phase";
 
 const SYSTEM_MANAGED_LABEL = "stigmer.ai/system-managed";
+const TRANSITIONAL_POLL_MS = 5_000;
 
 type ConfirmingState = {
   readonly runnerId: string;
@@ -109,11 +111,21 @@ export function RunnerListPanel({
   onDeleted,
   className,
 }: RunnerListPanelProps) {
+  const [hasTransitional, setHasTransitional] = useState(false);
   const { runners, isLoading, error, refetch } = useRunnerList(org, {
     includeSystemManaged,
+    refetchInterval: hasTransitional ? TRANSITIONAL_POLL_MS : false,
   });
   const [confirming, setConfirming] = useState<ConfirmingState>(null);
 
+  useEffect(() => {
+    setHasTransitional(
+      runners.some((r) =>
+        isTransitionalPhase(r.status?.phase ?? RunnerPhase.UNSPECIFIED),
+      ),
+    );
+  }, [runners]);
+
   if (onRefetchRef) {
     onRefetchRef(refetch);
   }
@@ -154,7 +166,7 @@ export function RunnerListPanel({
         {Array.from({ length: 3 }, (_, i) => (
           <div
             key={i}
-            className="bg-muted-subtle h-14 animate-pulse rounded-lg"
+            className="bg-muted-subtle h-[4.25rem] animate-pulse rounded-lg"
           />
         ))}
       </div>
@@ -328,54 +340,44 @@ function RunnerRow({
     );
   }
 
+  const metaSegments: string[] = [];
+  if (hostname) metaSegments.push(hostname);
+  if (osArch) metaSegments.push(osArch);
+  if (active) metaSegments.push(`${executions} exec${executions !== 1 ? "s" : ""}`);
+  if (lastHeartbeat) {
+    metaSegments.push(formatRelativeTime(timestampDate(lastHeartbeat)));
+  }
+
   return (
     <div
       role="listitem"
       className={cn(
-        "flex items-center gap-3 rounded-lg border border-border-muted px-3 py-2.5",
+        "flex items-start gap-3 rounded-lg border border-border-muted px-3 py-2.5",
         "hover:border-border transition-colors",
         !active && "opacity-60",
       )}
     >
-      <RunnerIcon size={14} />
-
-      {/* Name + phase badge */}
-      <div className="flex min-w-0 flex-1 items-center gap-2">
-        <span className="truncate text-sm font-medium text-foreground">
-          {name}
-        </span>
-        {systemManaged && (
-          <span className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[0.6rem] font-medium text-muted-foreground">
-            System
-          </span>
-        )}
-        <PhaseBadge phase={phase} />
-      </div>
+      <RunnerIcon size={16} className="mt-0.5" />
 
-      {/* Metadata columns — responsive */}
-      <div className="hidden items-center gap-4 text-xs text-muted-foreground sm:flex">
-        {hostname && (
-          <span className="max-w-[10rem] truncate" title={hostname}>
-            {hostname}
-          </span>
-        )}
-        {osArch && (
-          <span className="font-mono text-[0.65rem]">{osArch}</span>
-        )}
-        {version && (
-          <span className="font-mono text-[0.65rem]">v{version}</span>
-        )}
-        {active && (
-          <span title="Current executions">
-            {executions} exec{executions !== 1 ? "s" : ""}
-          </span>
-        )}
-        {lastHeartbeat && (
-          <span
-            title={`Last heartbeat: ${timestampDate(lastHeartbeat).toISOString()}`}
-          >
-            {formatRelativeTime(timestampDate(lastHeartbeat))}
+      <div className="min-w-0 flex-1">
+        {/* Line 1: name + badges + phase */}
+        <div className="flex items-center gap-2">
+          <span className="truncate text-sm font-medium text-foreground">
+            {name}
           </span>
+          {systemManaged && (
+            <span className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[0.6rem] font-medium text-muted-foreground">
+              System
+            </span>
+          )}
+          <PhaseBadge phase={phase} />
+        </div>
+
+        {/* Line 2: metadata */}
+        {metaSegments.length > 0 && (
+          <p className="mt-0.5 truncate text-[0.65rem] text-muted-foreground">
+            {metaSegments.join(" \u00b7 ")}
+          </p>
         )}
       </div>
 
@@ -627,7 +629,13 @@ function formatRelativeTime(date: Date): string {
 // Icons
 // ---------------------------------------------------------------------------
 
-function RunnerIcon({ size = 14 }: { size?: number }) {
+function RunnerIcon({
+  size = 14,
+  className,
+}: {
+  size?: number;
+  className?: string;
+}) {
   return (
     <svg
       width={size}
@@ -639,7 +647,7 @@ function RunnerIcon({ size = 14 }: { size?: number }) {
       strokeLinecap="round"
       strokeLinejoin="round"
       aria-hidden="true"
-      className="shrink-0 text-muted-foreground"
+      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" />

package/src/runner/__tests__/phase.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_pb";
+import { isTransitionalPhase, isActivePhase } from "../phase";
+
+describe("isTransitionalPhase", () => {
+  it("returns true for PENDING", () => {
+    expect(isTransitionalPhase(RunnerPhase.PENDING)).toBe(true);
+  });
+
+  it.each([
+    ["READY", RunnerPhase.READY],
+    ["BUSY", RunnerPhase.BUSY],
+    ["STOPPED", RunnerPhase.STOPPED],
+    ["FAILED", RunnerPhase.FAILED],
+    ["UNSPECIFIED", RunnerPhase.UNSPECIFIED],
+  ] as const)("returns false for %s", (_label, phase) => {
+    expect(isTransitionalPhase(phase)).toBe(false);
+  });
+
+  it("is disjoint from isActivePhase", () => {
+    const allPhases = [
+      RunnerPhase.READY,
+      RunnerPhase.BUSY,
+      RunnerPhase.PENDING,
+      RunnerPhase.STOPPED,
+      RunnerPhase.FAILED,
+      RunnerPhase.UNSPECIFIED,
+    ];
+    for (const phase of allPhases) {
+      if (isTransitionalPhase(phase)) {
+        expect(isActivePhase(phase)).toBe(false);
+      }
+    }
+  });
+});

package/src/runner/__tests__/useRunnerList.test.tsx

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  RunnerSchema,
+  RunnerStatusSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/runner/v1/api_pb";
+import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useRunnerList } from "../useRunnerList";
+
+function makeRunner(id: string, name: string, phase: RunnerPhase) {
+  const runner = create(RunnerSchema);
+  runner.metadata = create(ApiResourceMetadataSchema);
+  runner.metadata.id = id;
+  runner.metadata.name = name;
+  runner.status = create(RunnerStatusSchema);
+  runner.status.phase = phase;
+  return runner;
+}
+
+function buildMockClient(listMock: ReturnType<typeof vi.fn>) {
+  return {
+    runner: { list: listMock },
+  } as unknown as Stigmer;
+}
+
+function makeWrapper(client: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={client}>
+      {children}
+    </StigmerContext.Provider>
+  );
+}
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe("useRunnerList — refetchInterval", () => {
+  let listMock: ReturnType<typeof vi.fn>;
+  let client: Stigmer;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    listMock = vi.fn();
+    client = buildMockClient(listMock);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("polls when refetchInterval is set", async () => {
+    const runners = [makeRunner("r1", "dev", RunnerPhase.PENDING)];
+    listMock.mockResolvedValue({ items: runners });
+
+    const { result } = renderHook(
+      () => useRunnerList("acme", { refetchInterval: 2000 }),
+      { wrapper: makeWrapper(client) },
+    );
+
+    // Initial fetch.
+    await flush();
+    expect(listMock).toHaveBeenCalledTimes(1);
+    expect(result.current.runners).toHaveLength(1);
+
+    // Advance by one interval.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000);
+    });
+    expect(listMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not poll when refetchInterval is false", async () => {
+    listMock.mockResolvedValue({ items: [] });
+
+    renderHook(
+      () => useRunnerList("acme", { refetchInterval: false }),
+      { wrapper: makeWrapper(client) },
+    );
+
+    await flush();
+    expect(listMock).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(10_000);
+    });
+    expect(listMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/runner/index.ts

@@ -11,6 +11,12 @@ export type {
   LaunchLocalRunnerResult,
 } from "./useLaunchLocalRunner";
 
+export { useRunnerCredential } from "./useRunnerCredential";
+export type {
+  RunnerCredential,
+  UseRunnerCredentialReturn,
+} from "./useRunnerCredential";
+
 export { useStopRunner } from "./useStopRunner";
 export type {
   StopRunnerInput,
@@ -30,5 +36,6 @@ export {
   phaseLabel,
   phaseDotColor,
   isActivePhase,
+  isTransitionalPhase,
   PHASE_SORT_ORDER,
 } from "./phase";

package/src/runner/phase.ts

@@ -60,3 +60,19 @@ export function phaseDotColor(phase: RunnerPhase): string {
 export function isActivePhase(phase: RunnerPhase): boolean {
   return phase === RunnerPhase.READY || phase === RunnerPhase.BUSY;
 }
+
+/**
+ * Whether the runner is in a transitional phase whose status is
+ * expected to change soon without user action.
+ *
+ * Currently only `PENDING` — the runner has registered but hasn't
+ * completed its startup handshake yet. This is distinct from
+ * {@link isActivePhase} (READY | BUSY) where the runner is stable
+ * and accepting work.
+ *
+ * Useful for driving conditional polling: poll while transitional
+ * runners exist, stop when all runners reach a stable state.
+ */
+export function isTransitionalPhase(phase: RunnerPhase): boolean {
+  return phase === RunnerPhase.PENDING;
+}

package/src/runner/useRunnerCredential.ts

@@ -0,0 +1,89 @@
+"use client";
+
+import { useCallback } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+
+/**
+ * Resolved credential bundle for starting a runner sidecar process.
+ *
+ * Contains everything a CLI sidecar needs to authenticate with the
+ * Stigmer backend — the Bearer token (Auth0 JWT, PlatformClient JWT,
+ * or API key), the API endpoint, and the organization scope.
+ */
+export interface RunnerCredential {
+  /** Bearer token or API key. `null` when no credential is available. */
+  readonly token: string | null;
+  /** Base URL of the Stigmer API server (e.g., "https://api.stigmer.ai"). */
+  readonly endpoint: string;
+  /** Organization slug, if provided. */
+  readonly org?: string;
+}
+
+/** Return value of {@link useRunnerCredential}. */
+export interface UseRunnerCredentialReturn {
+  /**
+   * Resolve the current authentication credential for a runner sidecar.
+   *
+   * Reads the credential from the {@link Stigmer} client configured in
+   * the nearest `StigmerProvider`. Works with any auth mode: static API
+   * key, dynamic token provider (Auth0, PlatformClient), or custom
+   * transport.
+   *
+   * @param org - Optional organization slug to include in the result.
+   * @returns The credential bundle for the sidecar process.
+   */
+  readonly getCredential: (org?: string) => Promise<RunnerCredential>;
+}
+
+/**
+ * Behavior hook that resolves the current auth credential for passing
+ * to a runner sidecar process.
+ *
+ * This is the SDK-level abstraction for starting runners from within
+ * a desktop or native application — where the app already holds the
+ * credential and needs to hand it to a CLI child process. It avoids
+ * the `createLaunchToken` / `exchangeLaunchToken` round-trip, which
+ * is only needed for cross-process browser-to-desktop handshakes
+ * (see {@link useLaunchLocalRunner} for that scenario).
+ *
+ * The hook reads from `useStigmer()` and calls
+ * `client.getAuthCredential()`, so it works identically regardless
+ * of auth mode (Auth0 JWT, PlatformClient JWT, API key).
+ *
+ * @example
+ * ```tsx
+ * function StartRunnerButton({ org }: { org: string }) {
+ *   const { getCredential } = useRunnerCredential();
+ *
+ *   const handleStart = async () => {
+ *     const cred = await getCredential(org);
+ *     // Pass cred.token, cred.endpoint, cred.org to your sidecar
+ *     await nativeBridge.startRunner({
+ *       token: cred.token,
+ *       endpoint: cred.endpoint,
+ *       org: cred.org,
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleStart}>Start Runner</button>;
+ * }
+ * ```
+ */
+export function useRunnerCredential(): UseRunnerCredentialReturn {
+  const stigmer = useStigmer();
+
+  const getCredential = useCallback(
+    async (org?: string): Promise<RunnerCredential> => {
+      const token = await stigmer.getAuthCredential();
+      return {
+        token,
+        endpoint: stigmer.baseUrl,
+        org,
+      };
+    },
+    [stigmer],
+  );
+
+  return { getCredential };
+}

package/src/runner/useRunnerList.ts

@@ -1,11 +1,10 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { Runner } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/api_pb";
 import { ListRunnersRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/io_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch, type UseFetchOptions } from "../internal/useFetch";
 
 const SYSTEM_MANAGED_LABEL = "stigmer.ai/system-managed";
 
@@ -21,6 +20,24 @@ export interface UseRunnerListOptions {
    * @default false
    */
   readonly includeSystemManaged?: boolean;
+  /**
+   * Poll interval in milliseconds for automatic re-fetching.
+   *
+   * When set to a positive number, the hook re-fetches the runner list
+   * on a timer. Useful for monitoring status transitions (e.g. Pending
+   * to Ready) without requiring the user to navigate away and back.
+   *
+   * Set to `false` or `0` to disable polling (the default).
+   *
+   * @example
+   * ```tsx
+   * // Poll every 5 seconds while runners are transitioning
+   * const { runners } = useRunnerList("acme", {
+   *   refetchInterval: hasPendingRunners ? 5000 : false,
+   * });
+   * ```
+   */
+  readonly refetchInterval?: UseFetchOptions["refetchInterval"];
 }
 
 /** Return value of {@link useRunnerList}. */
@@ -29,6 +46,8 @@ export interface UseRunnerListReturn {
   readonly runners: readonly Runner[];
   /** `true` while the fetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
   /** Error from the last failed fetch, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch the runner list from the server. */
@@ -62,53 +81,26 @@ export function useRunnerList(
   options?: UseRunnerListOptions,
 ): UseRunnerListReturn {
   const stigmer = useStigmer();
-  const [runners, setRunners] = useState<Runner[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
   const includeSystemManaged = options?.includeSystemManaged ?? false;
+  const refetchInterval = options?.refetchInterval;
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
-
-  useEffect(() => {
-    if (!org) {
-      setRunners([]);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.runner
-      .list(create(ListRunnersRequestSchema, { org }))
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-
-          const items = includeSystemManaged
+  const { data: runners, isLoading, isRefetching, error, refetch } = useFetch(
+    org
+      ? async () => {
+          const result = await stigmer.runner.list(
+            create(ListRunnersRequestSchema, { org }),
+          );
+          return includeSystemManaged
             ? result.items
             : result.items.filter(
                 (r) => r.metadata?.labels[SYSTEM_MANAGED_LABEL] !== "true",
               );
+        }
+      : null,
+    [stigmer, org, includeSystemManaged],
+    [] as Runner[],
+    { refetchInterval },
+  );
 
-          setRunners(items);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [stigmer, org, includeSystemManaged, fetchKey]);
-
-  return { runners, isLoading, error, refetch };
+  return { runners, isLoading, isRefetching, error, refetch };
 }