@stigmer/react 0.0.92 → 0.0.93

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

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  RunnerSchema,
+  RunnerStatusSchema,
+  type Runner,
+} 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 { useStopRunner } from "../useStopRunner";
+
+function makeRunner(id: string, phase: RunnerPhase): Runner {
+  const runner = create(RunnerSchema);
+  runner.metadata = create(ApiResourceMetadataSchema);
+  runner.metadata.id = id;
+  runner.status = create(RunnerStatusSchema);
+  runner.status.phase = phase;
+  return runner;
+}
+
+function buildMockClient(overrides: {
+  stop?: ReturnType<typeof vi.fn>;
+} = {}) {
+  return {
+    runner: {
+      stop: overrides.stop ?? vi.fn(),
+    },
+  } as unknown as Stigmer;
+}
+
+function makeWrapper(client: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={client}>
+      {children}
+    </StigmerContext.Provider>
+  );
+}
+
+describe("useStopRunner", () => {
+  let stopMock: ReturnType<typeof vi.fn>;
+  let client: Stigmer;
+
+  beforeEach(() => {
+    stopMock = vi.fn();
+    client = buildMockClient({ stop: stopMock });
+  });
+
+  it("calls runner.stop with correct proto message and returns the runner", async () => {
+    const stoppedRunner = makeRunner("rnr_1", RunnerPhase.STOPPED);
+    stopMock.mockResolvedValueOnce(stoppedRunner);
+
+    const { result } = renderHook(() => useStopRunner(), {
+      wrapper: makeWrapper(client),
+    });
+
+    expect(result.current.isStopping).toBe(false);
+    expect(result.current.error).toBeNull();
+
+    let returned: Runner;
+    await act(async () => {
+      returned = await result.current.stop({
+        runnerId: "rnr_1",
+        reason: "user requested",
+      });
+    });
+
+    expect(stopMock).toHaveBeenCalledOnce();
+    const protoArg = stopMock.mock.calls[0][0];
+    expect(protoArg.runnerId).toBe("rnr_1");
+    expect(protoArg.reason).toBe("user requested");
+
+    expect(returned!).toBe(stoppedRunner);
+    expect(result.current.isStopping).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("defaults reason to empty string when omitted", async () => {
+    const stoppedRunner = makeRunner("rnr_2", RunnerPhase.STOPPED);
+    stopMock.mockResolvedValueOnce(stoppedRunner);
+
+    const { result } = renderHook(() => useStopRunner(), {
+      wrapper: makeWrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.stop({ runnerId: "rnr_2" });
+    });
+
+    const protoArg = stopMock.mock.calls[0][0];
+    expect(protoArg.reason).toBe("");
+  });
+
+  it("sets error and rethrows on failure", async () => {
+    const rpcError = new Error("runner not found");
+    stopMock.mockRejectedValueOnce(rpcError);
+
+    const { result } = renderHook(() => useStopRunner(), {
+      wrapper: makeWrapper(client),
+    });
+
+    await act(async () => {
+      await expect(
+        result.current.stop({ runnerId: "rnr_missing" }),
+      ).rejects.toThrow("runner not found");
+    });
+
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error!.message).toBe("runner not found");
+    expect(result.current.isStopping).toBe(false);
+  });
+
+  it("clears error via clearError", async () => {
+    stopMock.mockRejectedValueOnce(new Error("fail"));
+
+    const { result } = renderHook(() => useStopRunner(), {
+      wrapper: makeWrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.stop({ runnerId: "rnr_1" }).catch(() => {});
+    });
+    expect(result.current.error).not.toBeNull();
+
+    act(() => {
+      result.current.clearError();
+    });
+    expect(result.current.error).toBeNull();
+  });
+
+  it("resets previous error on a new successful stop", async () => {
+    stopMock.mockRejectedValueOnce(new Error("first fail"));
+
+    const { result } = renderHook(() => useStopRunner(), {
+      wrapper: makeWrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.stop({ runnerId: "rnr_1" }).catch(() => {});
+    });
+    expect(result.current.error).not.toBeNull();
+
+    const stoppedRunner = makeRunner("rnr_1", RunnerPhase.STOPPED);
+    stopMock.mockResolvedValueOnce(stoppedRunner);
+
+    await act(async () => {
+      await result.current.stop({ runnerId: "rnr_1" });
+    });
+    expect(result.current.error).toBeNull();
+  });
+});

package/src/runner/index.ts

@@ -0,0 +1,34 @@
+export { useRunnerList } from "./useRunnerList";
+export type {
+  UseRunnerListOptions,
+  UseRunnerListReturn,
+} from "./useRunnerList";
+
+export { useLaunchLocalRunner } from "./useLaunchLocalRunner";
+export type {
+  UseLaunchLocalRunnerOptions,
+  UseLaunchLocalRunnerReturn,
+  LaunchLocalRunnerResult,
+} from "./useLaunchLocalRunner";
+
+export { useStopRunner } from "./useStopRunner";
+export type {
+  StopRunnerInput,
+  UseStopRunnerReturn,
+} from "./useStopRunner";
+
+export { useDeleteRunner } from "./useDeleteRunner";
+export type { UseDeleteRunnerReturn } from "./useDeleteRunner";
+
+export { RunnerPicker } from "./RunnerPicker";
+export type { RunnerPickerProps } from "./RunnerPicker";
+
+export { RunnerListPanel } from "./RunnerListPanel";
+export type { RunnerListPanelProps } from "./RunnerListPanel";
+
+export {
+  phaseLabel,
+  phaseDotColor,
+  isActivePhase,
+  PHASE_SORT_ORDER,
+} from "./phase";

package/src/runner/phase.ts

@@ -0,0 +1,62 @@
+import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_pb";
+
+/**
+ * Sort order for runner phases — active phases first, then by severity.
+ *
+ * Used by both {@link RunnerPicker} and {@link RunnerListPanel} to present
+ * runners in a consistent, predictable order across all UI surfaces.
+ */
+export const PHASE_SORT_ORDER: Record<RunnerPhase, number> = {
+  [RunnerPhase.READY]: 0,
+  [RunnerPhase.BUSY]: 1,
+  [RunnerPhase.PENDING]: 2,
+  [RunnerPhase.STOPPED]: 3,
+  [RunnerPhase.FAILED]: 4,
+  [RunnerPhase.UNSPECIFIED]: 5,
+};
+
+const LABELS: Record<RunnerPhase, string> = {
+  [RunnerPhase.READY]: "Ready",
+  [RunnerPhase.BUSY]: "Busy",
+  [RunnerPhase.PENDING]: "Pending",
+  [RunnerPhase.STOPPED]: "Stopped",
+  [RunnerPhase.FAILED]: "Failed",
+  [RunnerPhase.UNSPECIFIED]: "Unknown",
+};
+
+/**
+ * Human-readable label for a runner phase.
+ *
+ * Returns title-case labels suitable for both compact indicators
+ * ("Ready") and full-row display ("Stopped").
+ */
+export function phaseLabel(phase: RunnerPhase): string {
+  return LABELS[phase] ?? "Unknown";
+}
+
+/**
+ * Tailwind `bg-*` class for the small colored dot indicator.
+ *
+ * - Ready  → `bg-success`  (green)
+ * - Busy   → `bg-warning`  (amber)
+ * - Others → `bg-muted-foreground` (neutral)
+ */
+export function phaseDotColor(phase: RunnerPhase): string {
+  switch (phase) {
+    case RunnerPhase.READY:
+      return "bg-success";
+    case RunnerPhase.BUSY:
+      return "bg-warning";
+    default:
+      return "bg-muted-foreground";
+  }
+}
+
+/**
+ * Whether the runner is in an active (workload-accepting) phase.
+ *
+ * Active = `READY` or `BUSY`. Inactive = everything else.
+ */
+export function isActivePhase(phase: RunnerPhase): boolean {
+  return phase === RunnerPhase.READY || phase === RunnerPhase.BUSY;
+}

package/src/runner/useDeleteRunner.ts

@@ -0,0 +1,67 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { Runner } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useDeleteRunner}. */
+export interface UseDeleteRunnerReturn {
+  /**
+   * Delete a runner by its resource ID. Resolves with the deleted
+   * {@link Runner} for confirmation display.
+   *
+   * The deletion is permanent — any sessions bound to this runner will
+   * fall back to auto-provisioning on their next execution.
+   */
+  readonly deleteRunner: (id: string) => Promise<Runner>;
+  /** `true` while the delete request is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that wraps `runner.delete()` with loading and error
+ * state.
+ *
+ * Deletes a runner by its resource ID. Returns the deleted
+ * {@link Runner} on success so callers can confirm which runner was
+ * removed (e.g., in a toast or undo prompt).
+ *
+ * @example
+ * ```tsx
+ * const { deleteRunner, isDeleting, error } = useDeleteRunner();
+ *
+ * await deleteRunner("rnr_abc123");
+ * refetch(); // refresh the runner list
+ * ```
+ */
+export function useDeleteRunner(): UseDeleteRunnerReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const deleteRunner = useCallback(
+    async (id: string): Promise<Runner> => {
+      setIsDeleting(true);
+      setError(null);
+
+      try {
+        return await stigmer.runner.delete(id);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { deleteRunner, isDeleting, error, clearError };
+}

package/src/runner/useLaunchLocalRunner.ts

@@ -0,0 +1,139 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { CreateLaunchTokenRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+const LAUNCH_RUNNER_SCHEME = "stigmer://launch-runner";
+
+function defaultOpenUrl(url: string): void {
+  window.location.href = url;
+}
+
+/** Options for {@link useLaunchLocalRunner}. */
+export interface UseLaunchLocalRunnerOptions {
+  /**
+   * Custom handler for opening the `stigmer://` URL.
+   *
+   * Defaults to `window.location.href` assignment, which is the standard
+   * browser pattern for dispatching custom URL schemes to the OS. The
+   * browser does not navigate away — it hands the scheme to the OS and
+   * the page stays on screen.
+   *
+   * Override this when embedding in non-standard environments (Electron,
+   * iframe, React Native WebView) where the default browser mechanism
+   * does not apply.
+   */
+  readonly openUrl?: (url: string) => void;
+}
+
+/** Result returned by a successful {@link UseLaunchLocalRunnerReturn.launch} call. */
+export interface LaunchLocalRunnerResult {
+  /** The `stigmer://launch-runner?token=...` URL that was opened. */
+  readonly url: string;
+  /**
+   * Absolute expiry time of the launch token. The desktop app must
+   * exchange the token before this time (typically 60 seconds).
+   */
+  readonly expiresAt: Date | undefined;
+}
+
+/** Return value of {@link useLaunchLocalRunner}. */
+export interface UseLaunchLocalRunnerReturn {
+  /**
+   * Create a one-time launch token and open the `stigmer://` URL to
+   * trigger the desktop app (or CLI fallback) to start a local runner.
+   *
+   * Resolves with the constructed URL and token expiry on success.
+   * The caller cannot detect whether the desktop app received the URL —
+   * use {@link useRunnerList} with `refetch()` to poll for the runner
+   * appearing in the list.
+   */
+  readonly launch: (input: { org: string }) => Promise<LaunchLocalRunnerResult>;
+  /** `true` while the token creation and URL dispatch are in flight. */
+  readonly isLaunching: boolean;
+  /** Error from the last failed launch attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that initiates a browser-to-desktop runner launch.
+ *
+ * Orchestrates two steps:
+ * 1. Calls `stigmer.runner.createLaunchToken({ org })` to mint a
+ *    one-time, 60-second token backed by the caller's credentials.
+ * 2. Opens `stigmer://launch-runner?token={token}` so the OS dispatches
+ *    to the Stigmer Desktop app (which exchanges the token for a JWT
+ *    and starts a local runner via its CLI sidecar).
+ *
+ * The hook reports success when the URL is opened. It does **not**
+ * detect whether the desktop app is installed or whether the runner
+ * actually started — those are observable via `useRunnerList`.
+ *
+ * @example
+ * ```tsx
+ * function LaunchButton({ org }: { org: string }) {
+ *   const { launch, isLaunching, error } = useLaunchLocalRunner();
+ *
+ *   return (
+ *     <button onClick={() => launch({ org })} disabled={isLaunching}>
+ *       {isLaunching ? "Launching…" : "Launch Local Runner"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom URL handler for non-browser environments
+ * const { launch } = useLaunchLocalRunner({
+ *   openUrl: (url) => nativeBridge.openExternal(url),
+ * });
+ * ```
+ */
+export function useLaunchLocalRunner(
+  options?: UseLaunchLocalRunnerOptions,
+): UseLaunchLocalRunnerReturn {
+  const stigmer = useStigmer();
+  const [isLaunching, setIsLaunching] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const openUrl = options?.openUrl ?? defaultOpenUrl;
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const launch = useCallback(
+    async (input: { org: string }): Promise<LaunchLocalRunnerResult> => {
+      setIsLaunching(true);
+      setError(null);
+
+      try {
+        const response = await stigmer.runner.createLaunchToken(
+          create(CreateLaunchTokenRequestSchema, { org: input.org }),
+        );
+
+        const url = `${LAUNCH_RUNNER_SCHEME}?token=${encodeURIComponent(response.token)}`;
+        const expiresAt = response.expiresAt
+          ? timestampDate(response.expiresAt)
+          : undefined;
+
+        openUrl(url);
+
+        return { url, expiresAt };
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsLaunching(false);
+      }
+    },
+    [stigmer, openUrl],
+  );
+
+  return { launch, isLaunching, error, clearError };
+}

package/src/runner/useRunnerList.ts

@@ -0,0 +1,114 @@
+"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";
+
+const SYSTEM_MANAGED_LABEL = "stigmer.ai/system-managed";
+
+/** Options for {@link useRunnerList}. */
+export interface UseRunnerListOptions {
+  /**
+   * Include system-managed (ephemeral cloud) runners in the result.
+   *
+   * System-managed runners are labeled `stigmer.ai/system-managed: "true"`
+   * and are created by the platform for cloud executions. They are hidden
+   * from the session composer by default but useful in admin views.
+   *
+   * @default false
+   */
+  readonly includeSystemManaged?: boolean;
+}
+
+/** Return value of {@link useRunnerList}. */
+export interface UseRunnerListReturn {
+  /** User-created runners for the organization, empty while loading or on error. */
+  readonly runners: readonly Runner[];
+  /** `true` while the 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 list from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches runners for an organization.
+ *
+ * Calls `stigmer.runner.list({ org })` and returns the result with
+ * loading/error state. System-managed (ephemeral cloud) runners are
+ * filtered out by default — pass `includeSystemManaged: true` to
+ * include them (useful for admin panels like Settings > Runners).
+ *
+ * Returns an empty array when `org` is `null` (no organization selected).
+ *
+ * @example
+ * ```tsx
+ * // Session composer — user-created runners only
+ * const { runners, isLoading } = useRunnerList("acme");
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Admin page — all runners including system-managed
+ * const { runners } = useRunnerList("acme", { includeSystemManaged: true });
+ * ```
+ */
+export function useRunnerList(
+  org: string | null,
+  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 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
+            ? result.items
+            : result.items.filter(
+                (r) => r.metadata?.labels[SYSTEM_MANAGED_LABEL] !== "true",
+              );
+
+          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 };
+}

package/src/runner/useStopRunner.ts

@@ -0,0 +1,92 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Runner } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/api_pb";
+import { RunnerStopInputSchema } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Input for {@link UseStopRunnerReturn.stop}. */
+export interface StopRunnerInput {
+  /** ID of the runner to stop. */
+  readonly runnerId: string;
+  /**
+   * Optional reason for the stop, logged on the runner and in audit.
+   *
+   * @example "user requested via web console"
+   */
+  readonly reason?: string;
+}
+
+/** Return value of {@link useStopRunner}. */
+export interface UseStopRunnerReturn {
+  /**
+   * Stop a runner gracefully.
+   *
+   * If the runner is connected, sends a stop command via the bidi stream
+   * and waits for acknowledgment. If offline, directly transitions to
+   * STOPPED. Idempotent — stopping an already-stopped or failed runner
+   * returns the resource as-is.
+   *
+   * Resolves with the updated {@link Runner} resource.
+   */
+  readonly stop: (input: StopRunnerInput) => Promise<Runner>;
+  /** `true` while the stop RPC is in flight. */
+  readonly isStopping: boolean;
+  /** Error from the last failed stop attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that wraps `runner.stop()` with loading and error state.
+ *
+ * Stops a runner gracefully. Connected runners receive a stop command
+ * via the bidi stream; offline runners transition directly to STOPPED.
+ * The operation is idempotent — stopping an already-stopped or failed
+ * runner succeeds without error.
+ *
+ * Returns the updated {@link Runner} resource on success so callers
+ * can reflect the new phase in the UI without a separate refetch.
+ *
+ * @example
+ * ```tsx
+ * const { stop, isStopping, error } = useStopRunner();
+ *
+ * await stop({ runnerId: "rnr_abc123", reason: "user requested" });
+ * refetch(); // refresh the runner list
+ * ```
+ */
+export function useStopRunner(): UseStopRunnerReturn {
+  const stigmer = useStigmer();
+  const [isStopping, setIsStopping] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const stop = useCallback(
+    async (input: StopRunnerInput): Promise<Runner> => {
+      setIsStopping(true);
+      setError(null);
+
+      try {
+        return await stigmer.runner.stop(
+          create(RunnerStopInputSchema, {
+            runnerId: input.runnerId,
+            reason: input.reason ?? "",
+          }),
+        );
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsStopping(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { stop, isStopping, error, clearError };
+}