Skip to content

πŸ™Œ OpenHands: AI-Driven Development

10.7 KB
Raw Blame
import { useQuery } from "@tanstack/react-query";
import axios from "axios";
import { isSdkHttpError } from "#/api/agent-server-compatibility";
import BashService from "#/api/bash-service/bash-service.api";
import { useActiveBackend } from "#/contexts/active-backend-context";
import type { SandboxStatus } from "#/api/conversation-service/agent-server-conversation-service.types";
import { useCloudSandbox } from "./use-cloud-sandbox";
import { useUserConversation } from "./use-user-conversation";

export const BASH_COMMAND_LOGS_QUERY_KEY = ["bash-command-logs"] as const;

/**
 * Reasons the modal can't fetch logs from a cloud sandbox, in priority
 * order. The hook surfaces at most one of these so the UI can render a
 * targeted message instead of a raw error.
 */
export type SandboxIssue =
  | "missing" // sandbox has been deleted (or conversation has no runtime URL)
  | "paused" // sandbox is paused β€” needs resuming
  | "starting" // sandbox is still booting
  | "errored" // sandbox is in a terminal error state
  | "unreachable"; // bash query attempted and failed at the network layer

interface UseBashCommandLogsOptions {
  /**
   * The agent-server conversation that hosts the bash command. Used to
   * resolve `conversation_url` and `session_api_key` for cloud
   * backends, and to gate the query on `sandbox_status` so we don't
   * fire requests at known-unreachable sandboxes.
   */
  conversationId: string | null | undefined;
  /**
   * The cloud sandbox that ran the command. Script automations never
   * create a conversation, so on cloud backends this is the only handle
   * to their agent-server: its `AGENT_SERVER` exposed URL and
   * `session_api_key` stand in for the conversation's `conversation_url`
   * and `session_api_key`. Ignored when a conversation id is given, and
   * on local backends.
   */
  sandboxId?: string | null;
  bashCommandId: string | null | undefined;
  enabled?: boolean;
}

/** Name of the agent-server entry in a cloud sandbox's `exposed_urls`. */
const AGENT_SERVER_EXPOSED_URL_NAME = "AGENT_SERVER";

/** The agent-server that holds the command's events, however it was found. */
interface RuntimeTarget {
  url: string | null;
  sessionApiKey: string | null;
  sandboxStatus: SandboxStatus | null;
}

/**
 * Map a cloud sandbox status to a stable issue code (or null when the
 * sandbox is healthy enough to attempt the fetch).
 */
function sandboxIssueFromStatus(
  status: SandboxStatus | null | undefined,
): SandboxIssue | null {
  switch (status) {
    case "MISSING":
      return "missing";
    case "PAUSED":
      return "paused";
    case "STARTING":
      return "starting";
    case "ERROR":
      return "errored";
    case "RUNNING":
    case null:
    case undefined:
    default:
      return null;
  }
}

/**
 * Detect "the runtime is unreachable" errors from the cloud proxy. The
 * proxy itself returns 5xx when the upstream sandbox is gone; runtimes
 * return 4xx/5xx for various ephemeral states. We classify 5xx and
 * network errors as "unreachable" so the modal can render the
 * sandbox-gone state instead of dumping a raw error. Cloud calls go
 * through the shared TypeScript client and throw its `HttpError`;
 * axios-shaped errors are still recognized as well.
 */
function classifyFetchError(error: unknown): SandboxIssue | null {
  const status = axios.isAxiosError(error)
    ? error.response?.status
    : isSdkHttpError(error)
      ? (error as { status: number }).status
      : undefined;
  if (status !== undefined) {
    // Treat 502/503/504 (proxy can't reach upstream) and 404 (sandbox or
    // resource no longer exists) as the sandbox being gone. We do not
    // collapse 401/403 here β€” those are auth bugs we want to surface.
    return status === 404 || status >= 500 ? "unreachable" : null;
  }
  // No status β†’ the request never got a response. Axios reports these as
  // response-less errors; fetch (the shared client) throws `TypeError`
  // for network failures and `AbortError`/`TimeoutError` for timeouts,
  // sometimes wrapped in a plain `Error` with the original as `cause`.
  if (axios.isAxiosError(error) || error instanceof TypeError) {
    return "unreachable";
  }
  if (error instanceof Error) {
    const causeName = error.cause instanceof Error ? error.cause.name : null;
    if (
      error.name === "AbortError" ||
      error.name === "TimeoutError" ||
      causeName === "AbortError" ||
      causeName === "TimeoutError"
    ) {
      return "unreachable";
    }
  }
  return null;
}

/**
 * Search `BashOutput` events for an automation run's bash command.
 *
 * - **Local backend**: the query fires as soon as the modal opens and
 *   we have a `bash_command_id`. The conversation lookup runs in
 *   parallel; if it resolves with `session_api_key`/`conversation_url`
 *   those are passed through (`BashService` still searches at server
 *   level, where the automation's command runs), but a missing/stale
 *   conversation does not block the bash query (the local agent-server
 *   hosts events under a single root).
 * - **Cloud backend**: the run's agent-server is found through its
 *   conversation when it has one, and through its sandbox otherwise
 *   (script automations never create a conversation). Either lookup
 *   pre-checks the sandbox status and the existence of a runtime URL
 *   before firing β€” paused, starting, errored, or missing sandboxes
 *   report a `sandboxIssue` and skip the request entirely (saves a
 *   doomed round-trip and gives the UI a targeted empty state). A run
 *   with neither handle reports `missing` at once. If the request does
 *   fire and fails with a 5xx / network error / 404 we re-classify it
 *   as `unreachable`.
 */
export function useBashCommandLogs(options: UseBashCommandLogsOptions) {
  const { conversationId, sandboxId, bashCommandId, enabled = true } = options;
  const active = useActiveBackend();
  const isCloud = active.backend.kind === "cloud";

  // Only resolve the runtime when the modal is open. RunLogsModal mounts
  // (closed) for every activity-log row, so an unconditional lookup would fire
  // one /api/conversations request per row on page load. Passing null when
  // disabled trips each lookup hook's own `!!id` gate.
  const viaConversation = enabled && !!conversationId;
  const viaSandbox = enabled && isCloud && !viaConversation && !!sandboxId;
  const conversationQuery = useUserConversation(
    viaConversation ? (conversationId as string) : null,
  );
  const sandboxQuery = useCloudSandbox(viaSandbox ? sandboxId : null);
  const conversation = conversationQuery.data;

  let runtime: RuntimeTarget | null = null;
  let isResolvingRuntime = false;
  let conversationMissing = false;
  let preflightIssue: SandboxIssue | null = null;

  if (!isCloud) {
    // Local backends don't carry sandbox_status, and the agent-server hosts
    // events under a single root so there's nothing to gate on.
    runtime = {
      url: conversation?.conversation_url ?? null,
      sessionApiKey: conversation?.session_api_key ?? null,
      sandboxStatus: null,
    };
  } else if (viaConversation) {
    // `isLoading`, not `isPending`: a query that is disabled β€” including
    // when `useUserConversation` disables itself β€” stays `pending` forever
    // without ever fetching, and reporting that as "resolving" is what left
    // the modal loading with no request in flight.
    isResolvingRuntime = conversationQuery.isLoading;
    if (conversationQuery.isFetched) {
      if (!conversation) {
        conversationMissing = true;
      } else {
        runtime = {
          url: conversation.conversation_url ?? null,
          sessionApiKey: conversation.session_api_key ?? null,
          sandboxStatus: conversation.sandbox_status ?? null,
        };
      }
    }
  } else if (viaSandbox) {
    isResolvingRuntime = sandboxQuery.isLoading;
    if (sandboxQuery.isFetched) {
      const sandbox = sandboxQuery.data;
      if (sandboxQuery.isError) {
        preflightIssue = "unreachable";
      } else if (!sandbox) {
        // Deleted, or created by someone else: the lookup only returns the
        // caller's own sandboxes.
        preflightIssue = "missing";
      } else {
        runtime = {
          url:
            sandbox.exposed_urls?.find(
              (exposed) => exposed.name === AGENT_SERVER_EXPOSED_URL_NAME,
            )?.url ?? null,
          sessionApiKey: sandbox.session_api_key,
          sandboxStatus: sandbox.status,
        };
      }
    }
  } else if (enabled) {
    // Neither a conversation nor a sandbox to ask: nothing to load, and
    // nothing to wait for.
    preflightIssue = "missing";
  }

  if (isCloud && runtime && !preflightIssue) {
    preflightIssue =
      sandboxIssueFromStatus(runtime.sandboxStatus) ??
      (!runtime.url ? "missing" : null);
  }

  const runtimeUrl = runtime?.url ?? null;
  const sessionApiKey = runtime?.sessionApiKey ?? null;

  // Cloud needs the runtime URL before it can talk to the agent-server;
  // local does not.
  const hasRequiredAuth = isCloud ? !!runtimeUrl : true;
  const canFire =
    enabled &&
    !!bashCommandId &&
    hasRequiredAuth &&
    !preflightIssue &&
    !conversationMissing;

  const query = useQuery({
    queryKey: [
      ...BASH_COMMAND_LOGS_QUERY_KEY,
      bashCommandId,
      runtimeUrl,
      sessionApiKey,
      active.backend.id,
      active.orgId,
    ],
    queryFn: () =>
      BashService.listOutputs(
        runtimeUrl,
        sessionApiKey,
        bashCommandId as string,
      ),
    enabled: canFire,
    // Completed-run logs don't change β€” cache long enough that reopening
    // the modal is instant but not forever.
    staleTime: 60 * 1000,
    gcTime: 5 * 60 * 1000,
    retry: false,
  });

  // If the request fired and failed in a way that suggests the
  // sandbox is gone/unreachable, surface it as a sandbox issue so the
  // modal can render the matching empty state instead of a raw error.
  const fetchIssue = isCloud ? classifyFetchError(query.error) : null;
  const sandboxIssue: SandboxIssue | null = preflightIssue ?? fetchIssue;

  return {
    data: query.data,
    /**
     * Set only when the request actually fired and failed AND the
     * failure isn't already classified as a sandbox issue. The modal
     * should render `sandboxIssue` first and only fall back to this.
     */
    error: fetchIssue ? null : query.error,
    isFetching: query.isFetching,
    isPending: query.isPending,
    /**
     * True while we're still resolving the runtime URL through the
     * conversation or, failing that, the sandbox.
     */
    isResolvingConversation: isResolvingRuntime,
    /** Cloud-only: conversation lookup failed (deleted or no access). */
    conversationMissing,
    /**
     * Reason the bash query couldn't / didn't usefully complete. Always
     * null for healthy cloud sandboxes and for local backends.
     */
    sandboxIssue,
  };
}