@stigmer/react 1.0.3 → 2.0.0

package/src/runner/useRunner.ts

@@ -1,59 +0,0 @@
-"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/runner/useRunnerCredential.ts

@@ -1,89 +0,0 @@
-"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/useRunnerFileBrowser.ts

@@ -1,344 +0,0 @@
-"use client";
-
-import { useCallback, useEffect, useReducer, useRef } from "react";
-import { create } from "@bufbuild/protobuf";
-import {
-  RunnerSendCommandInputSchema,
-  ListDirectoryRequestSchema,
-  type DirectoryEntry,
-} from "@stigmer/protos/ai/stigmer/agentic/runner/v1/io_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
-
-/** A single segment of the breadcrumb path bar. */
-export interface PathSegment {
-  /** Display name (directory name, or "/" for root). */
-  readonly name: string;
-  /** Absolute path up to and including this segment. */
-  readonly path: string;
-}
-
-/** Return value of {@link useRunnerFileBrowser}. */
-export interface UseRunnerFileBrowserReturn {
-  /** Current resolved absolute path. */
-  readonly currentPath: string;
-  /** Directory entries for the current path. */
-  readonly entries: readonly DirectoryEntry[];
-  /** Breadcrumb segments for the current path. */
-  readonly segments: readonly PathSegment[];
-  /** Runner's home directory (enables Home shortcut). */
-  readonly homeDirectory: string;
-  /** Runner process's current working directory (enables CWD shortcut). */
-  readonly currentDirectory: string;
-  /** Whether hidden files are shown. */
-  readonly showHidden: boolean;
-  /** Toggle hidden file visibility. */
-  readonly toggleHidden: () => void;
-  /** True while a directory listing is in flight. */
-  readonly isLoading: boolean;
-  /** Error from the last navigation attempt. */
-  readonly error: Error | null;
-  /** Navigate into a child directory by name. */
-  readonly navigateTo: (name: string) => void;
-  /** Navigate to an absolute path. */
-  readonly navigateToPath: (path: string) => void;
-  /** Navigate to the parent directory. */
-  readonly navigateUp: () => void;
-  /** Navigate to the runner's home directory. */
-  readonly navigateHome: () => void;
-  /** Navigate to the runner's current working directory. */
-  readonly navigateCwd: () => void;
-  /** Retry the last failed navigation. */
-  readonly retry: () => void;
-  /** True when at the filesystem root (no parent). */
-  readonly isAtRoot: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Reducer
-// ---------------------------------------------------------------------------
-
-/** Cached result of a single directory listing. */
-interface CachedListing {
-  readonly entries: readonly DirectoryEntry[];
-  readonly fetchedAt: number;
-}
-
-interface State {
-  currentPath: string;
-  entries: readonly DirectoryEntry[];
-  homeDirectory: string;
-  currentDirectory: string;
-  showHidden: boolean;
-  isLoading: boolean;
-  error: Error | null;
-  /** The path we last requested — used for retry. */
-  requestedPath: string;
-  /** Directory listing cache keyed by resolved absolute path. */
-  cache: Map<string, CachedListing>;
-}
-
-type Action =
-  | { type: "NAVIGATE"; path: string }
-  | { type: "SUCCESS"; resolvedPath: string; entries: DirectoryEntry[]; homeDirectory: string; currentDirectory: string }
-  | { type: "FAILURE"; error: Error }
-  | { type: "TOGGLE_HIDDEN" }
-  | { type: "CACHE_HIT"; resolvedPath: string; entries: readonly DirectoryEntry[] };
-
-const CACHE_MAX_AGE_MS = 30_000;
-
-function reducer(state: State, action: Action): State {
-  switch (action.type) {
-    case "NAVIGATE":
-      return {
-        ...state,
-        requestedPath: action.path,
-        isLoading: true,
-        error: null,
-      };
-    case "SUCCESS": {
-      const nextCache = new Map(state.cache);
-      nextCache.set(action.resolvedPath, {
-        entries: action.entries,
-        fetchedAt: Date.now(),
-      });
-      return {
-        ...state,
-        currentPath: action.resolvedPath,
-        entries: action.entries,
-        homeDirectory: action.homeDirectory || state.homeDirectory,
-        currentDirectory: action.currentDirectory || state.currentDirectory,
-        isLoading: false,
-        error: null,
-        cache: nextCache,
-      };
-    }
-    case "CACHE_HIT":
-      return {
-        ...state,
-        currentPath: action.resolvedPath,
-        entries: action.entries,
-        isLoading: false,
-        error: null,
-        requestedPath: action.resolvedPath,
-      };
-    case "FAILURE":
-      return { ...state, isLoading: false, error: action.error };
-    case "TOGGLE_HIDDEN":
-      return { ...state, showHidden: !state.showHidden };
-  }
-}
-
-const INITIAL_STATE: State = {
-  currentPath: "",
-  entries: [],
-  homeDirectory: "",
-  currentDirectory: "",
-  showHidden: false,
-  isLoading: false,
-  error: null,
-  requestedPath: "",
-  cache: new Map(),
-};
-
-// ---------------------------------------------------------------------------
-// Path utilities
-// ---------------------------------------------------------------------------
-
-function buildSegments(path: string): PathSegment[] {
-  if (!path) return [];
-
-  const segments: PathSegment[] = [{ name: "/", path: "/" }];
-  const parts = path.split("/").filter(Boolean);
-  let accumulated = "";
-
-  for (const part of parts) {
-    accumulated += `/${part}`;
-    segments.push({ name: part, path: accumulated });
-  }
-
-  return segments;
-}
-
-function parentPath(path: string): string {
-  if (!path || path === "/") return "/";
-  const idx = path.lastIndexOf("/");
-  return idx <= 0 ? "/" : path.slice(0, idx);
-}
-
-// ---------------------------------------------------------------------------
-// Hook
-// ---------------------------------------------------------------------------
-
-/**
- * Behavior hook that drives a filesystem browser against a connected runner.
- *
- * Sends `ListDirectory` commands via the runner's bidi stream (through the
- * `sendCommand` unary RPC) and manages navigation state, breadcrumbs,
- * loading/error handling, and hidden file filtering.
- *
- * Designed for composition with {@link RunnerFileBrowser} but usable
- * standalone by platform builders who want custom rendering.
- *
- * @param runnerId - ID of the runner to browse. When `null`, the hook
- *   is inert (no requests are made, entries are empty).
- *
- * @example
- * ```tsx
- * function MyFilePicker({ runnerId }: { runnerId: string }) {
- *   const browser = useRunnerFileBrowser(runnerId);
- *
- *   return (
- *     <div>
- *       <p>Path: {browser.currentPath}</p>
- *       {browser.entries
- *         .filter(e => e.isDirectory)
- *         .map(e => (
- *           <button key={e.name} onClick={() => browser.navigateTo(e.name)}>
- *             {e.name}
- *           </button>
- *         ))}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useRunnerFileBrowser(
-  runnerId: string | null,
-): UseRunnerFileBrowserReturn {
-  const stigmer = useStigmer();
-  const [state, dispatch] = useReducer(reducer, INITIAL_STATE);
-  const requestIdRef = useRef(0);
-
-  const cacheRef = useRef(state.cache);
-  cacheRef.current = state.cache;
-
-  const fetchDirectory = useCallback(
-    async (path: string) => {
-      if (!runnerId) return;
-
-      const cached = cacheRef.current.get(path);
-      if (cached && Date.now() - cached.fetchedAt < CACHE_MAX_AGE_MS) {
-        dispatch({ type: "CACHE_HIT", resolvedPath: path, entries: cached.entries });
-        return;
-      }
-
-      const id = ++requestIdRef.current;
-      dispatch({ type: "NAVIGATE", path });
-
-      try {
-        const response = await stigmer.runner.sendCommand(
-          create(RunnerSendCommandInputSchema, {
-            runnerId,
-            command: {
-              case: "listDirectory",
-              value: create(ListDirectoryRequestSchema, { path }),
-            },
-          }),
-        );
-
-        if (id !== requestIdRef.current) return;
-
-        if (response.result.case === "error") {
-          dispatch({
-            type: "FAILURE",
-            error: new Error(response.result.value.message),
-          });
-          return;
-        }
-
-        if (response.result.case === "listDirectory") {
-          const listing = response.result.value;
-          dispatch({
-            type: "SUCCESS",
-            resolvedPath: listing.resolvedPath,
-            entries: listing.entries,
-            homeDirectory: listing.homeDirectory,
-            currentDirectory: listing.currentDirectory,
-          });
-        }
-      } catch (err) {
-        if (id !== requestIdRef.current) return;
-        dispatch({ type: "FAILURE", error: toError(err) });
-      }
-    },
-    [runnerId, stigmer],
-  );
-
-  // Initial load: fetch home directory when runnerId becomes available.
-  const initializedForRef = useRef<string | null>(null);
-
-  useEffect(() => {
-    if (!runnerId) {
-      initializedForRef.current = null;
-      return;
-    }
-
-    if (initializedForRef.current !== runnerId) {
-      initializedForRef.current = runnerId;
-      fetchDirectory("");
-    }
-  }, [runnerId, fetchDirectory]);
-
-  const navigateTo = useCallback(
-    (name: string) => {
-      const next =
-        state.currentPath === "/"
-          ? `/${name}`
-          : `${state.currentPath}/${name}`;
-      fetchDirectory(next);
-    },
-    [state.currentPath, fetchDirectory],
-  );
-
-  const navigateToPath = useCallback(
-    (path: string) => fetchDirectory(path),
-    [fetchDirectory],
-  );
-
-  const navigateUp = useCallback(
-    () => fetchDirectory(parentPath(state.currentPath)),
-    [state.currentPath, fetchDirectory],
-  );
-
-  const navigateHome = useCallback(
-    () => fetchDirectory(state.homeDirectory || "~"),
-    [state.homeDirectory, fetchDirectory],
-  );
-
-  const navigateCwd = useCallback(
-    () => {
-      if (state.currentDirectory) fetchDirectory(state.currentDirectory);
-    },
-    [state.currentDirectory, fetchDirectory],
-  );
-
-  const retry = useCallback(
-    () => fetchDirectory(state.requestedPath),
-    [state.requestedPath, fetchDirectory],
-  );
-
-  const toggleHidden = useCallback(() => dispatch({ type: "TOGGLE_HIDDEN" }), []);
-
-  const segments = buildSegments(state.currentPath);
-  const isAtRoot = state.currentPath === "/";
-
-  return {
-    currentPath: state.currentPath,
-    entries: state.entries,
-    segments,
-    homeDirectory: state.homeDirectory,
-    currentDirectory: state.currentDirectory,
-    showHidden: state.showHidden,
-    toggleHidden,
-    isLoading: state.isLoading,
-    error: state.error,
-    navigateTo,
-    navigateToPath,
-    navigateUp,
-    navigateHome,
-    navigateCwd,
-    retry,
-    isAtRoot,
-  };
-}

package/src/runner/useRunnerList.ts

@@ -1,106 +0,0 @@
-"use client";
-
-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 { useFetch, type UseFetchOptions } from "../internal/useFetch";
-
-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;
-  /**
-   * 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}. */
-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;
-  /** `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. */
-  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 includeSystemManaged = options?.includeSystemManaged ?? false;
-  const refetchInterval = options?.refetchInterval;
-
-  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 },
-  );
-
-  return { runners, isLoading, isRefetching, error, refetch };
-}

package/src/runner/useStopRunner.ts

@@ -1,92 +0,0 @@
-"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 };
-}