Skip to content

πŸ™Œ OpenHands: AI-Driven Development

15.7 KB
Raw Blame
/**
 * Renderer-side view of the DigitalOcean MARS bridge exposed by
 * `electron/preload-main.cjs`, plus the helpers that turn a connected MARS
 * session into an ordinary local backend.
 *
 * A session is reached over a port-forward tunnel on loopback. The far end
 * is a plain agent-server, so the backend is `kind: "local"`.
 *
 * `window.marsBridge` comes from Electron's preload in the desktop build, or
 * from the Agent Canvas server in the web build (src/api/mars/mars-web-bridge.ts,
 * installed before first render when the server hosts it). harness-api sends
 * no CORS headers and the token must live in a trusted process, so a page
 * with neither cannot offer MARS at all. Callers gate on `getMarsBridge()`
 * rather than catching per-call failures.
 */

import { ConversationSortOrder } from "@openhands/typescript-client";
import { ConversationClient } from "@openhands/typescript-client/clients";
import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
import {
  isDefinitiveLocalBackendError,
  validateLocalBackend,
} from "#/api/agent-server-compatibility";
import type { Backend } from "#/api/backend-registry/types";

export type MarsCredentialKind = "oauth" | "pat";

/** Non-secret description of a stored credential. Never carries the token. */
export interface MarsConnection {
  id: string;
  kind: MarsCredentialKind;
  label: string;
  teamName: string | null;
  /** ISO timestamp; OAuth grants expire after 30 days and cannot be refreshed. */
  expiresAt: string | null;
  isExpired: boolean;
}

export interface MarsAuthState {
  connections: MarsConnection[];
  active: MarsConnection | null;
  /** False when the OS keychain is unavailable, so tokens are session-only. */
  isPersistent: boolean;
  /** False when this build has no registered OAuth client; PAT still works. */
  canUseOAuth: boolean;
}

export interface MarsSession {
  session_id: string;
  name?: string | null;
  status?: string | null;
  agent_kind?: string | null;
  config_id?: string | null;
  repo_hint?: string | null;
  created_at?: string | null;
  last_event_at?: string | null;
}

export interface MarsSessionPage {
  sessions: MarsSession[];
  nextPageToken: string | null;
}

/**
 * Durable agent definition β€” what a user calls "an agent". One config has
 * many sessions. Not to be confused with `MarsSession.agent_kind`, which is
 * just an enum naming the coding agent inside the sandbox.
 */
export interface MarsAgentConfig {
  id: string;
  name?: string | null;
  created_by?: string | null;
  updated_at?: string | null;
  /**
   * The manifest's `agent` (e.g. `openhands`), lowercased. Filled in by the
   * main process; null when the manifest could not be read.
   */
  agent?: string | null;
}

const OPENHANDS_AGENT = "openhands";

/**
 * Whether a config's manifest declares `agent: openhands`. Manifests without
 * it are older specs that no longer launch, so an unknown agent never counts.
 */
export function isOpenHandsConfig(config: MarsAgentConfig): boolean {
  return config.agent === OPENHANDS_AGENT;
}

export interface NewMarsAgentInput {
  name: string;
  /**
   * Sandbox size slug from `listSandboxSizes`, written into the agent's
   * manifest so every session of the agent gets it. Omitted = DO's default.
   */
  size?: string;
}

/** One entry of DigitalOcean's sandbox size catalog. */
export interface MarsSandboxSize {
  slug: string;
  vcpus: number;
  memory_mb: number;
  price_per_hour_usd?: number | null;
  price_per_month_usd?: number | null;
}

/** harness-api's Agent Config name rule. */
const AGENT_NAME_PATTERN = /^[A-Za-z0-9]([A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$/;

export function isValidAgentName(name: string): boolean {
  return AGENT_NAME_PATTERN.test(name);
}

export interface MarsAgentConfigPage {
  configs: MarsAgentConfig[];
  nextPageToken: string | null;
}

/** Most recent failed upstream dial behind an otherwise healthy listener. */
export interface MarsUpstreamFailure {
  /** harness-api WebSocket close code (4001 / 4002 / 4011), if any. */
  closeCode: number | null;
  /** HTTP status when the upgrade itself was refused. */
  httpStatus: number | null;
  message: string;
}

/** How a connected session is reached. Only the loopback tunnel today. */
export type MarsTransport = "tunnel";

export interface MarsTunnelStatus {
  sessionId: string;
  status: "connecting" | "connected" | "error";
  transport?: MarsTransport;
  /** Base URL the renderer registers as the backend host. */
  host?: string;
  remotePort: number;
  /** Loopback listener port; only set over the tunnel. */
  localPort: number | undefined;
  error: string | undefined;
  upstreamFailure?: MarsUpstreamFailure | null;
}

export interface OpenMarsTunnelParams {
  sessionId: string;
  /** Re-request a specific local port, e.g. to revive a persisted backend. */
  localPort?: number;
}

interface ListOptions {
  pageSize?: number;
  pageToken?: string;
  status?: string;
}

export interface MarsBridge {
  getAuthState: () => Promise<MarsAuthState>;
  signInWithOAuth: () => Promise<MarsAuthState>;
  savePat: (payload: {
    token: string;
    label?: string;
  }) => Promise<MarsAuthState>;
  setActiveConnection: (id: string) => Promise<MarsAuthState>;
  signOut: (id?: string) => Promise<MarsAuthState>;
  listSessions: (options?: ListOptions) => Promise<MarsSessionPage>;
  listAgentConfigs: (
    options?: Omit<ListOptions, "status">,
  ) => Promise<MarsAgentConfigPage>;
  /** Empty means "no sessions yet", not "config is gone". */
  listConfigSessions: (
    configId: string,
    options?: ListOptions,
  ) => Promise<MarsSessionPage>;
  /** Static catalog, smallest first; every slug is valid for a new agent. */
  listSandboxSizes: () => Promise<MarsSandboxSize[]>;
  createOpenHandsAgent: (input: NewMarsAgentInput) => Promise<MarsAgentConfig>;
  /** Resolves once the new session is READY. */
  createSession: (configId: string, name: string) => Promise<MarsSession>;
  pauseSession: (sessionId: string) => Promise<void>;
  resumeSession: (sessionId: string) => Promise<void>;
  /** Ends the session and its sandbox for good; any live connection is dropped first. */
  destroySession: (sessionId: string) => Promise<void>;
  /** Soft-deletes the agent definition; only offered when none of its sessions is live. */
  deleteAgentConfig: (configId: string) => Promise<void>;
  openTunnel: (params: OpenMarsTunnelParams) => Promise<MarsTunnelStatus>;
  closeTunnel: (sessionId: string) => Promise<void>;
  getTunnel: (sessionId: string) => Promise<MarsTunnelStatus | undefined>;
}

declare global {
  interface Window {
    marsBridge?: MarsBridge;
  }
}

export function getMarsBridge(): MarsBridge | null {
  if (typeof window === "undefined") return null;
  return window.marsBridge ?? null;
}

export function requireMarsBridge(): MarsBridge {
  const bridge = getMarsBridge();
  if (!bridge) {
    throw new Error(
      "window.marsBridge is unavailable β€” Managed Agents need the Electron desktop build or an Agent Canvas server that hosts the MARS bridge.",
    );
  }
  return bridge;
}

/**
 * Connects to one MARS session over a port-forward tunnel, waking it if
 * paused. The listener port can change between connects, so callers read
 * the host from the returned status rather than reusing a remembered one.
 */
export function openMarsTunnel(
  params: OpenMarsTunnelParams,
): Promise<MarsTunnelStatus> {
  return requireMarsBridge().openTunnel(params);
}

const IPC_ERROR_PREFIX =
  /^Error invoking remote method '[^']+': (?:\w*Error: )?/;

/**
 * Message for a failed bridge call, without the wrapper Electron puts around
 * errors thrown in the main process.
 */
export function getMarsErrorMessage(error: unknown): string | null {
  const message = error instanceof Error ? error.message : null;
  return message ? message.replace(IPC_ERROR_PREFIX, "") : null;
}

export const SESSION_STATUS_READY = "SESSION_STATUS_READY";
export const SESSION_STATUS_PAUSED = "SESSION_STATUS_PAUSED";
export const SESSION_STATUS_DESTROYING = "SESSION_STATUS_DESTROYING";
export const SESSION_STATUS_DESTROYED = "SESSION_STATUS_DESTROYED";
export const SESSION_STATUS_FAILED = "SESSION_STATUS_FAILED";

/** Where a freshly connected MARS session lands. */
export const NEW_CHAT_PATH = "/conversations";

/** Statuses a session can never come back from. */
const TERMINAL_SESSION_STATUSES = new Set([
  SESSION_STATUS_DESTROYING,
  SESSION_STATUS_DESTROYED,
  SESSION_STATUS_FAILED,
]);

export type MarsSessionPhase =
  | "ready"
  | "paused"
  | "starting"
  | "ended"
  | "failed";

/**
 * Collapse `SESSION_STATUS_*` into the few states the UI treats differently.
 * Statuses are added server-side without a client release, so anything
 * unrecognised that is not terminal reads as "starting" (transitional).
 */
export function getSessionPhase(
  status: string | null | undefined,
): MarsSessionPhase {
  if (status === SESSION_STATUS_READY) return "ready";
  if (status === SESSION_STATUS_PAUSED) return "paused";
  if (status === SESSION_STATUS_FAILED) return "failed";
  if (TERMINAL_SESSION_STATUSES.has(status ?? "")) return "ended";
  return "starting";
}

/** READY or PAUSED β€” connecting resumes a paused session first. */
export function isConnectableSession(session: MarsSession): boolean {
  const phase = getSessionPhase(session.status);
  return phase === "ready" || phase === "paused";
}

const SESSION_NAME_MAX_STEM = 32;

/**
 * Name for a session launched from an agent: the agent it came from plus a
 * suffix to keep siblings apart, narrowed to the character set MARS's own
 * generated names use.
 */
export function buildNewSessionName(configName: string | null | undefined) {
  const stem =
    (configName ?? "")
      .toLowerCase()
      .replace(/[^a-z0-9]+/g, "-")
      .replace(/^-+|-+$/g, "")
      .slice(0, SESSION_NAME_MAX_STEM) || "agent";
  return `${stem}-${Math.random().toString(36).slice(2, 8)}`;
}

/**
 * The in-guest agent-server's session key is set by the sandbox template, not
 * by us. The DigitalOcean token is the authorization boundary instead:
 * dialing the tunnel requires it.
 */
export const MARS_GUEST_API_KEY = "";

/**
 * An idle-paused session cold-wakes on first traffic and the in-guest
 * agent-server needs a moment more before it answers, so early probes
 * legitimately fail.
 */
const AGENT_SERVER_WAIT_MS = 60_000;
const AGENT_SERVER_PROBE_TIMEOUT_MS = 5_000;
const AGENT_SERVER_PROBE_INTERVAL_MS = 2_000;
/**
 * A just-woken sandbox also closes 4002 while its agent-server boots, so only
 * a 4002 that outlasts this window means nothing will ever serve the port.
 */
const GUEST_PORT_CLOSED_GRACE_MS = 20_000;

const CLOSE_SESSION_UNAVAILABLE = 4001;
const CLOSE_GUEST_DIAL_FAILED = 4002;
const HTTP_UNAUTHORIZED = 401;
const HTTP_FORBIDDEN = 403;

export type MarsAttachFailureReason =
  /** The sandbox answers, but not with an OpenHands agent-server on :8000. */
  | "not-openhands"
  /** DigitalOcean refused the tunnel for this token or session. */
  | "refused";

/** A failure the UI can explain precisely instead of a generic timeout. */
export class MarsAttachError extends Error {
  readonly reason: MarsAttachFailureReason;

  constructor(reason: MarsAttachFailureReason, message: string) {
    super(message);
    this.name = "MarsAttachError";
    this.reason = reason;
  }
}

function isRefusal(failure: MarsUpstreamFailure): boolean {
  return (
    failure.closeCode === CLOSE_SESSION_UNAVAILABLE ||
    failure.httpStatus === HTTP_UNAUTHORIZED ||
    failure.httpStatus === HTTP_FORBIDDEN
  );
}

async function readUpstreamFailure(
  sessionId: string | undefined,
): Promise<MarsUpstreamFailure | null> {
  const bridge = getMarsBridge();
  if (!sessionId || !bridge) return null;
  try {
    return (await bridge.getTunnel(sessionId))?.upstreamFailure ?? null;
  } catch {
    return null;
  }
}

/**
 * Poll a freshly opened tunnel until the agent-server behind it answers.
 * When `sessionId` is given, the tunnel's own upstream failures cut the wait
 * short with a {@link MarsAttachError}; otherwise the last probe failure is
 * rethrown so the user sees why it never came up. A definitive probe failure
 * (rejected key, unsupported version) is rethrown at once.
 */
export async function waitForMarsAgentServer(
  host: string,
  {
    sessionId,
    budgetMs = AGENT_SERVER_WAIT_MS,
  }: { sessionId?: string; budgetMs?: number } = {},
): Promise<string | null> {
  const startedAt = Date.now();
  const deadline = startedAt + budgetMs;
  let guestPortClosedSince: number | null = null;
  for (;;) {
    try {
      return await validateLocalBackend(
        { host, apiKey: MARS_GUEST_API_KEY },
        AGENT_SERVER_PROBE_TIMEOUT_MS,
      );
    } catch (error) {
      // A rejected key or too-old server will not change by waiting.
      if (isDefinitiveLocalBackendError(error)) throw error;
      const failure = await readUpstreamFailure(sessionId);
      if (failure && isRefusal(failure)) {
        throw new MarsAttachError("refused", failure.message);
      }
      const now = Date.now();
      if (failure?.closeCode === CLOSE_GUEST_DIAL_FAILED) {
        guestPortClosedSince ??= now;
        if (now - guestPortClosedSince >= GUEST_PORT_CLOSED_GRACE_MS) {
          throw new MarsAttachError("not-openhands", failure.message);
        }
      } else {
        guestPortClosedSince = null;
      }
      if (now >= deadline) throw error;
      await new Promise((resolve) => {
        setTimeout(resolve, AGENT_SERVER_PROBE_INTERVAL_MS);
      });
    }
  }
}

const LATEST_CONVERSATION_TIMEOUT_MS = 10_000;

/**
 * Id of the most recently updated conversation on a session's agent-server,
 * read through an explicit host override so it cannot race the registry
 * switching the active backend. Best-effort: null on any failure, because
 * the caller can always fall back to a fresh chat.
 */
export async function fetchLatestMarsConversationId(
  host: string,
): Promise<string | null> {
  try {
    const page = await new ConversationClient(
      getAgentServerClientOptions({
        host,
        sessionApiKey: MARS_GUEST_API_KEY,
        timeout: LATEST_CONVERSATION_TIMEOUT_MS,
      }),
    ).searchConversations({
      limit: 1,
      sort_order: ConversationSortOrder.UPDATED_AT_DESC,
    });
    return page?.items?.[0]?.id ?? null;
  } catch {
    return null;
  }
}

export function buildMarsBackendHost(localPort: number): string {
  return `http://127.0.0.1:${localPort}`;
}

/**
 * The base URL a connection status says to register: the tunnel's loopback
 * listener. A status from a bridge that predates `host` is still honoured
 * through its `localPort`.
 */
export function getMarsConnectionHost(
  status: MarsTunnelStatus,
): string | undefined {
  if (status.host) return status.host;
  return status.localPort === undefined
    ? undefined
    : buildMarsBackendHost(status.localPort);
}

/**
 * Local port a persisted MARS backend's tunnel was listening on, so a
 * restore can ask for it again. Undefined for a host that is not a loopback
 * listener.
 */
export function getMarsBackendLocalPort(backend: Backend): number | undefined {
  try {
    const url = new URL(backend.host);
    if (url.hostname !== "127.0.0.1") return undefined;
    const port = Number.parseInt(url.port, 10);
    return Number.isInteger(port) && port > 0 ? port : undefined;
  } catch {
    return undefined;
  }
}

/**
 * Build the Backend record for a session that now answers at `host`. The far
 * end really is an ordinary agent-server, so this is a `kind: "local"`
 * backend like any other.
 */
export function buildMarsBackendInput({
  name,
  host,
  sessionId,
  configId,
  apiKey = MARS_GUEST_API_KEY,
}: {
  name: string;
  host: string;
  sessionId: string;
  configId?: string;
  apiKey?: string;
}): Omit<Backend, "id" | "connectionRevision"> {
  return {
    name,
    host,
    apiKey,
    kind: "local",
    authMode: "api-key",
    marsSessionId: sessionId,
    ...(configId ? { marsConfigId: configId } : {}),
  };
}