@stigmer/react 0.0.100 → 0.1.0

package/src/agent/useAgentCount.ts

@@ -29,7 +29,7 @@ export interface UseAgentCountReturn {
   /** `true` while the count fetch is in flight. */
   readonly isLoading: boolean;
   /** Error message from the last failed fetch, or `null` when healthy. */
-  readonly error: string | null;
+  readonly error: Error | null;
   /** Re-fetch the count with the same parameters. */
   readonly refetch: () => void;
 }

package/src/agent/useAgentList.ts

@@ -36,8 +36,8 @@ export interface UseAgentListReturn {
   readonly currentPage: number;
   /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
-  /** Error message from the last failed request, or `null` when healthy. */
-  readonly error: string | null;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
   /** Discard cached data and re-fetch the current page from the server. */
   readonly refetch: () => void;
 }

package/src/agent/useDefaultAgent.ts

@@ -1,11 +1,21 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
+import { useEffect, useRef } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { GetDefaultAgentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
+
+/**
+ * Milliseconds the cached result can age before a visibility change
+ * triggers a background refetch. Keeps the hook quiet during fast
+ * window switches while ensuring fresh data after real idle periods.
+ */
+const STALE_THRESHOLD_MS = 30_000;
+
+const RETRY_DELAY_MS = 1_000;
+const MAX_RETRIES = 1;
 
 /** Return value of {@link useDefaultAgent}. */
 export interface UseDefaultAgentReturn {
@@ -13,6 +23,8 @@ export interface UseDefaultAgentReturn {
   readonly agent: Agent | 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 the default agent from the server. */
@@ -27,8 +39,10 @@ export interface UseDefaultAgentReturn {
  * start a conversation without choosing an agent.
  *
  * Pass `null` for `org` to skip fetching (stable no-op). The hook
- * fetches once on mount and caches the result — the default agent
- * rarely changes within a session.
+ * fetches once on mount and caches the result, then automatically
+ * refetches when the document becomes visible after being hidden for
+ * longer than {@link STALE_THRESHOLD_MS}. Transient failures are
+ * retried once before surfacing an error.
  *
  * @example
  * ```tsx
@@ -40,42 +54,60 @@ export interface UseDefaultAgentReturn {
  */
 export function useDefaultAgent(org: string | null): UseDefaultAgentReturn {
   const stigmer = useStigmer();
-  const [agent, setAgent] = useState<Agent | null>(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
+  const lastFetchedAt = useRef(0);
+
+  const fetchFn = org
+    ? async () => {
+        const doFetch = () =>
+          stigmer.agent.getDefault(
+            create(GetDefaultAgentRequestSchema, { org }),
+          );
+        const result = await fetchWithRetry(doFetch, MAX_RETRIES, RETRY_DELAY_MS);
+        lastFetchedAt.current = Date.now();
+        return result;
+      }
+    : null;
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+  const { data: agent, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [org, stigmer],
+    null,
+  );
 
   useEffect(() => {
-    if (!org) {
-      setAgent(null);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
+    if (typeof document === "undefined") return;
 
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
+    const onVisible = () => {
+      if (document.visibilityState !== "visible") return;
+      if (Date.now() - lastFetchedAt.current >= STALE_THRESHOLD_MS) {
+        refetch();
+      }
+    };
 
-    stigmer.agent.getDefault(create(GetDefaultAgentRequestSchema, { org })).then(
-      (result) => {
-        if (cancelled.current) return;
-        setAgent(result);
-        setIsLoading(false);
-      },
-      (err) => {
-        if (cancelled.current) return;
-        setError(toError(err));
-        setIsLoading(false);
-      },
-    );
+    document.addEventListener("visibilitychange", onVisible);
+    return () => document.removeEventListener("visibilitychange", onVisible);
+  }, [refetch]);
 
-    return () => {
-      cancelled.current = true;
-    };
-  }, [org, stigmer, fetchKey]);
+  return { agent, isLoading, isRefetching, error, refetch };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
 
-  return { agent, isLoading, error, refetch };
+/**
+ * Retries `fn` up to `retries` times with a fixed delay between attempts.
+ */
+async function fetchWithRetry<T>(
+  fn: () => Promise<T>,
+  retries: number,
+  delayMs: number,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (retries <= 0) throw err;
+    await new Promise((r) => setTimeout(r, delayMs));
+    return fetchWithRetry(fn, retries - 1, delayMs);
+  }
 }

package/src/agent-instance/useAgentInstance.ts

@@ -1,10 +1,9 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
 import type { ResourceRef } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useAgentInstance}. */
 export interface UseAgentInstanceReturn {
@@ -12,6 +11,8 @@ export interface UseAgentInstanceReturn {
   readonly agentInstance: AgentInstance | 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 the agent instance from the server. */
@@ -47,46 +48,21 @@ export function useAgentInstance(
   ref: ResourceRef | null,
 ): UseAgentInstanceReturn {
   const stigmer = useStigmer();
-  const [agentInstance, setAgentInstance] = useState<AgentInstance | 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 org = ref?.org;
   const slug = ref?.slug;
   const version = ref?.version;
 
-  useEffect(() => {
-    if (!org || !slug) {
-      setAgentInstance(null);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.agentInstance.getByReference({ org, slug, version }).then(
-      (result) => {
-        if (cancelled.current) return;
-        setAgentInstance(result);
-        setIsLoading(false);
-      },
-      (err) => {
-        if (cancelled.current) return;
-        setError(toError(err));
-        setIsLoading(false);
-      },
-    );
+  const fetchFn =
+    org && slug
+      ? () => stigmer.agentInstance.getByReference({ org, slug, version })
+      : null;
 
-    return () => {
-      cancelled.current = true;
-    };
-  }, [org, slug, version, stigmer, fetchKey]);
+  const { data: agentInstance, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [org, slug, version, stigmer],
+    null,
+  );
 
-  return { agentInstance, isLoading, error, refetch };
+  return { agentInstance, isLoading, isRefetching, error, refetch };
 }

package/src/agent-instance/useAgentInstanceList.ts

@@ -1,11 +1,11 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useRef } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
 import { ListAgentInstancesRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/io_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useAgentInstanceList}. */
 export interface UseAgentInstanceListReturn {
@@ -15,6 +15,8 @@ export interface UseAgentInstanceListReturn {
   readonly totalCount: number;
   /** `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 the list from the server. */
@@ -45,11 +47,6 @@ export function useAgentInstanceList(
   labels?: Record<string, string>,
 ): UseAgentInstanceListReturn {
   const stigmer = useStigmer();
-  const [agentInstances, setAgentInstances] = useState<AgentInstance[]>([]);
-  const [totalCount, setTotalCount] = useState(0);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
   const labelsRef = useRef(labels);
   if (
@@ -60,46 +57,33 @@ export function useAgentInstanceList(
   }
   const stableLabels = labelsRef.current;
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+  const fetchFn = org
+    ? async () => {
+        const result = await stigmer.agentInstance.list(
+          create(ListAgentInstancesRequestSchema, {
+            org,
+            labels: stableLabels ?? {},
+          }),
+        );
+        return {
+          agentInstances: result.items as AgentInstance[],
+          totalCount: result.totalCount,
+        };
+      }
+    : null;
 
-  useEffect(() => {
-    if (!org) {
-      setAgentInstances([]);
-      setTotalCount(0);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
+  const { data, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [org, stableLabels, stigmer],
+    { agentInstances: [] as AgentInstance[], totalCount: 0 },
+  );
 
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.agentInstance
-      .list(
-        create(ListAgentInstancesRequestSchema, {
-          org,
-          labels: stableLabels ?? {},
-        }),
-      )
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setAgentInstances(result.items);
-          setTotalCount(result.totalCount);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [org, stableLabels, stigmer, fetchKey]);
-
-  return { agentInstances, totalCount, isLoading, error, refetch };
+  return {
+    agentInstances: data.agentInstances,
+    totalCount: data.totalCount,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  };
 }

package/src/api-key/useApiKeyList.ts

@@ -1,9 +1,8 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import type { ApiKey } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useApiKeyList}. */
 export interface UseApiKeyListReturn {
@@ -11,6 +10,8 @@ export interface UseApiKeyListReturn {
   readonly apiKeys: readonly ApiKey[];
   /** `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 the key list from the server. */
@@ -38,36 +39,12 @@ export interface UseApiKeyListReturn {
  */
 export function useApiKeyList(): UseApiKeyListReturn {
   const stigmer = useStigmer();
-  const [apiKeys, setApiKeys] = useState<ApiKey[]>([]);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+  const { data: apiKeys, isLoading, isRefetching, error, refetch } = useFetch(
+    () => stigmer.apiKey.findAll().then((r) => [...r.entries]),
+    [stigmer],
+    [] as ApiKey[],
+  );
 
-  useEffect(() => {
-    const cancelled = { current: false };
-
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.apiKey.findAll().then(
-      (result) => {
-        if (cancelled.current) return;
-        setApiKeys([...result.entries]);
-        setIsLoading(false);
-      },
-      (err) => {
-        if (cancelled.current) return;
-        setError(toError(err));
-        setIsLoading(false);
-      },
-    );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [stigmer, fetchKey]);
-
-  return { apiKeys, isLoading, error, refetch };
+  return { apiKeys, isLoading, isRefetching, error, refetch };
 }

package/src/composer/ComposerToolbar.tsx

@@ -4,7 +4,6 @@ import { cn } from "@stigmer/theme";
 import { ContextPopover } from "./ContextPopover";
 import { ConfigureMenu, type ConfigureMenuItem } from "./ConfigureMenu";
 import { ModelSelector } from "../models/ModelSelector";
-import { RunnerPicker } from "../runner/RunnerPicker";
 import {
   PaperclipIcon,
   WorkspaceIcon,
@@ -41,13 +40,6 @@ export interface ComposerToolbarProps {
   /** Render the picker content for a given configure panel id. */
   readonly renderConfigPanel: (itemId: string) => React.ReactNode;
 
-  // -- Runner picker --------------------------------------------------------
-
-  readonly showRunner: boolean;
-  readonly runnerOrg: string;
-  readonly runnerId: string | null;
-  readonly onRunnerIdChange: (runnerId: string | null) => void;
-
   // -- Model selector -------------------------------------------------------
 
   readonly showModelSelector: boolean;
@@ -86,17 +78,13 @@ export function ComposerToolbar({
   configActivePanel,
   onConfigActivePanelChange,
   renderConfigPanel,
-  showRunner,
-  runnerOrg,
-  runnerId,
-  onRunnerIdChange,
   showModelSelector,
   modelId,
   onModelChange,
 }: ComposerToolbarProps) {
   const hasTier1 = showAttach || showWorkspace;
   const hasTier2 = configureItems.length > 0;
-  const hasExecParams = showRunner || showModelSelector;
+  const hasExecParams = showModelSelector;
 
   return (
     <div className="flex items-center justify-between gap-2 border-t border-border-muted px-3 py-2">
@@ -161,15 +149,6 @@ export function ComposerToolbar({
           <div className="mx-0.5 h-4 w-px bg-border/50" aria-hidden="true" />
         )}
 
-        {showRunner && (
-          <RunnerPicker
-            org={runnerOrg}
-            value={runnerId}
-            onChange={onRunnerIdChange}
-            disabled={disabled}
-          />
-        )}
-
         {showModelSelector && (
           <ModelSelector
             value={modelId}

package/src/composer/ContextChip.tsx

@@ -4,7 +4,7 @@ import { ChipSpinner, XIcon } from "./icons";
 export interface ChipItem {
   key: string;
   label: string;
-  type: "agent" | "workspace" | "mcp" | "skill" | "secret";
+  type: "agent" | "workspace" | "mcp" | "skill" | "secret" | "runner";
   onRemove: () => void;
   /** Drives visual variant: amber for `needsSetup`, muted+spinner for `loading`/`submitting`. */
   status?: "loading" | "needsSetup" | "submitting" | "ready";
@@ -20,6 +20,7 @@ const CHIP_TYPE_LABELS: Record<ChipItem["type"], string> = {
   mcp: "MCP",
   skill: "Skill",
   secret: "1-time",
+  runner: "Runner",
 };
 
 export function ContextChip({