Skip to content

πŸ™Œ OpenHands: AI-Driven Development

4.2 KB
Raw Blame
import { useQuery } from "@tanstack/react-query";
import AcpService, {
  type AcpAuthStatus,
} from "#/api/acp-service/acp-service.api";
import { useActiveBackend } from "#/contexts/active-backend-context";

export type { AcpAuthStatus };

/**
 * Probe whether the selected ACP provider is already authenticated on the
 * (local) agent-server β€” by a subscription login (Claude Pro/Max, ChatGPT,
 * Google) or a pre-set API key.
 *
 * Detection is entirely client-side: {@link AcpService.getAuthStatus} runs the
 * provider's own status command (Claude: ``claude auth status``; Codex:
 * ``codex login status``; Gemini: a credentials-file check) through the
 * agent-server bash endpoint and classifies the output β€” no dedicated
 * endpoint, no prompt, no model tokens. Anything it can't classify (CLI not
 * installed, unexpected output, the bash call failing) is ``unknown``.
 */
async function probeAcpAuth(providerKey: string): Promise<AcpAuthStatus> {
  try {
    return await AcpService.getAuthStatus(providerKey);
  } catch {
    // The bash endpoint is unreachable or errored: fall back to "unknown" so
    // the caller shows the API-key fields rather than falsely claiming
    // "not logged in".
    return "unknown";
  }
}

interface UseAcpAuthStatusOptions {
  /**
   * Gate the probe to when the consuming surface is actually visible β€” the
   * onboarding modal mounts every slide at once, so without this the probe
   * would fire (and spin a subprocess) before the user reaches the step and
   * before the backend is confirmed connected. Defaults to ``true``.
   */
  enabled?: boolean;
}

/**
 * React Query wrapper around {@link probeAcpAuth}.
 *
 * Gated to **local backends only**: the detection command runs wherever the
 * agent-server runs, and a provider CLI / credentials file is only reliably
 * present on the user's own machine. On a remote/cloud backend they're ~never
 * there, so we skip the probe, return ``"unknown"``, and let the caller fall
 * back to the (already optional) API-key fields.
 *
 * Eligibility is intentionally *not* tied to whether the provider has API-key
 * fields: subscription/OAuth providers (e.g. Gemini) are detectable too, and an
 * unknown ``providerKey`` simply classifies as ``"unknown"``. The caller renders
 * this hook only for ACP providers, so any local backend is probeable.
 *
 * The probe runs a subprocess on the agent-server, so the result is cached for
 * the session (``staleTime: Infinity``, no refetch on focus/mount) β€” one probe
 * per provider per backend.
 */
export function useAcpAuthStatus(
  providerKey: string | null | undefined,
  options: UseAcpAuthStatusOptions = {},
) {
  const { enabled = true } = options;
  const active = useActiveBackend();
  const isLocal = active.backend.kind === "local";
  const isSupported = isLocal;
  const queryEnabled = enabled && isSupported && !!providerKey;

  const query = useQuery<AcpAuthStatus, Error>({
    // ``providerKey`` both discriminates the cache (so switching providers
    // re-probes) and parameterizes the probe β€” ``queryEnabled`` guarantees it
    // is non-empty whenever the query runs.
    queryKey: ["acp-auth-status", active.backend.id, providerKey],
    queryFn: () => probeAcpAuth(providerKey as string),
    enabled: queryEnabled,
    // ``staleTime: Infinity`` = never re-probe while the result stays cached;
    // ``gcTime`` then bounds that to ~15 min after the hook unmounts. So a
    // user who dismisses and reopens onboarding >15 min later re-probes β€”
    // intentional: it's a cheap one-off and their login state may have changed.
    staleTime: Infinity,
    gcTime: 1000 * 60 * 15,
    // ``probeAcpAuth`` always resolves (it catches internally β†’ "unknown"), so
    // this is redundant today β€” kept as a guard so the probe still never retries
    // if that inner catch is ever removed.
    retry: false,
    refetchOnWindowFocus: false,
    refetchOnMount: false,
  });

  return {
    status: query.data ?? "unknown",
    /** True while the first probe for this provider is in flight. */
    isChecking: queryEnabled && query.isFetching && query.data === undefined,
    /** Whether a probe can run at all on this backend (local backends only). */
    isSupported,
  };
}