Skip to content

πŸ™Œ OpenHands: AI-Driven Development

20.2 KB
Raw Blame
import {
  getAcpProvider as getClientAcpProvider,
  type ACPModelInfo,
} from "@openhands/typescript-client";
import type { BackendKind } from "#/api/backend-registry/types";
import { I18nKey } from "#/i18n/declaration";

export type ACPProviderIcon =
  | "claude-code"
  | "codex"
  | "gemini"
  | "pi"
  | "opencode"
  | "cli-generic";

export const ACP_PROVIDER_FALLBACK_ICON: ACPProviderIcon = "cli-generic";

// Sentinel ``agent.llm.model`` returned by older SDKs for ACP conversations
// in lieu of a real model. Suppressed at every consumer that resolves a
// display string.
//
// NB: ``"default"`` is NOT a placeholder. claude-agent-acp 0.44+ exposes
// ``default`` ("Default (recommended)") as a real, selectable model in its
// configOptions select β€” the server reports it as ``currentModelId`` and lists
// it in ``availableModels`` β€” so it must surface like any other model id.
export const ACP_MANAGED_SENTINEL = "acp-managed";

/**
 * Filter for "real" ACP model strings β€” non-empty and not the legacy
 * ``acp-managed`` sentinel. Returns the trimmed value on success, ``null``
 * otherwise.
 */
function realAcpModel(value: unknown): string | null {
  if (typeof value !== "string") return null;
  const trimmed = value.trim();
  if (!trimmed) return null;
  if (trimmed === ACP_MANAGED_SENTINEL) return null;
  return trimmed;
}

/**
 * Single source of truth for resolving the model string to surface for an
 * ACP conversation/settings context. Consumed by the conversation adapter
 * (chip text), the conversation-creation path (concrete ``acp_model``
 * payload), the Settings β†’ Agent form (initial value), and the chat-input
 * model label.
 *
 * Precedence: SDK runtime fields β†’ user-configured ``acp_model`` β†’
 * legacy ``agent.llm.model`` β†’ provider default (when ``providerDefault``
 * is passed). Pass ``providerDefault`` only on surfaces that should
 * silently substitute the registry default; omit it for the conversation
 * chip, which must distinguish "no concrete model" from "default".
 */
export function resolveEffectiveAcpModel(inputs: {
  runtimeName?: string | null;
  runtimeId?: string | null;
  configured?: string | null;
  sdkLlm?: string | null;
  providerDefault?: string | null;
}): string | null {
  for (const candidate of [
    inputs.runtimeName,
    inputs.runtimeId,
    inputs.configured,
    inputs.sdkLlm,
  ]) {
    const value = realAcpModel(candidate);
    if (value) return value;
  }
  return inputs.providerDefault ?? null;
}

/**
 * Shape of a built-in ACP (Agent Client Protocol) provider as Canvas consumes
 * it. The data fields (display name, launch command) are sourced at module
 * load from ``@openhands/typescript-client``'s ACP
 * registry β€” the generated mirror of the Python source of truth
 * ``openhands.sdk.settings.acp_providers``. This config only adds the
 * Canvas-specific UI fields ({@link ACPProviderConfig.icon} +
 * {@link ACPProviderConfig.description_key}); see {@link ACP_PROVIDER_UI}.
 */
export interface ACPProviderConfig {
  /** Stable registry key, also stored on conversations as ``tags.acpserver``. */
  key: string;
  /** Human-readable name shown in dropdowns and conversation chips. */
  display_name: string;
  /**
   * Tokens passed to the agent-server as ``acp_command`` when this preset
   * is picked. Each entry must be a real ACP-protocol stdio server β€” the
   * SDK validates this against the {@link ACPProviderConfig.key}.
   *
   * NB: ``npx -y @openai/codex acp`` looks plausible but is **not** an
   * ACP server β€” the codex CLI has no ``acp`` subcommand and exits with
   * ``Error: stdin is not a terminal`` when spawned without a TTY, which
   * silently deadlocks the agent-server's ACP handshake. Use
   * ``@agentclientprotocol/codex-acp`` (the codex ACP wrapper) instead.
   */
  default_command: string[];
  /**
   * i18n key for the one-line provider description rendered under the
   * onboarding tile. Stored on the registry so adding a new ACP
   * provider only requires editing this file (not the onboarding tile
   * list separately).
   */
  description_key: I18nKey;
  /**
   * Serializable icon key used by UI surfaces that render provider
   * choices. Kept as a string so the SDK mirror check can continue to
   * parse this registry without importing React components.
   */
  icon?: ACPProviderIcon;
  /** Offered only on local backends; Cloud runs a fixed set of providers. */
  local_only?: boolean;
}

export interface ACPModelOption {
  /** Exact model ID sent as ``acp_model``. */
  id: string;
  /** Human-readable label shown in Settings -> Agent. */
  label: string;
}

// Canvas-only UI metadata per built-in provider, keyed by the ACP registry
// key. The display name and launch command come from the typescript-client
// registry below; models come from the agent itself. Adding a provider
// happens upstream in the SDK; Canvas only owns the brand icon and the
// onboarding-tile description here. Its keys are the harnesses Canvas
// offers β€” see {@link SURFACED_ACP_PROVIDERS}.
const ACP_PROVIDER_UI: Record<
  string,
  { icon: ACPProviderIcon; description_key: I18nKey; local_only?: boolean }
> = {
  "claude-code": {
    icon: "claude-code",
    description_key: I18nKey.ONBOARDING$AGENT_CLAUDE_CODE_DESCRIPTION,
  },
  codex: {
    icon: "codex",
    description_key: I18nKey.ONBOARDING$AGENT_CODEX_DESCRIPTION,
  },
  "gemini-cli": {
    icon: "gemini",
    description_key: I18nKey.ONBOARDING$AGENT_GEMINI_CLI_DESCRIPTION,
  },
  pi: {
    icon: "pi",
    description_key: I18nKey.ONBOARDING$AGENT_PI_DESCRIPTION,
    local_only: true,
  },
  opencode: {
    icon: "opencode",
    description_key: I18nKey.ONBOARDING$AGENT_OPENCODE_DESCRIPTION,
    local_only: true,
  },
};

/**
 * The ACP harnesses Canvas surfaces β€” its own declaration of what it offers,
 * independent of what the SDK registry happens to contain. Registering a
 * harness upstream is a no-op here: nothing in Canvas enumerates the registry,
 * so there is no list to keep in step with it.
 */
export const SURFACED_ACP_PROVIDERS: readonly string[] =
  Object.keys(ACP_PROVIDER_UI);

// Built-in ACP providers Canvas surfaces, built by enriching each upstream
// registry record (``@openhands/typescript-client`` β†’ Python SDK) with the
// Canvas UI metadata above.
export const ACP_PROVIDERS: ACPProviderConfig[] = Object.entries(
  ACP_PROVIDER_UI,
).map(([key, ui]) => {
  const info = getClientAcpProvider(key);
  return {
    key,
    display_name: info?.display_name ?? key,
    default_command: info ? [...info.default_command] : [],
    description_key: ui.description_key,
    icon: ui.icon,
    local_only: ui.local_only,
  };
});

/** The built-in ACP providers a backend of ``kind`` can launch. */
export function getAcpProvidersForBackend(
  kind: BackendKind,
): ACPProviderConfig[] {
  return kind === "cloud"
    ? ACP_PROVIDERS.filter((provider) => !provider.local_only)
    : ACP_PROVIDERS;
}

export const ACP_CUSTOM_PRESET_KEY = "custom";

/**
 * A credential an ACP provider authenticates with, surfaced during onboarding
 * so the user can populate it without leaving the flow. The {@link name} is
 * both the global-secret name and the environment variable the agent-server
 * exports into the ACP subprocess β€” keeping them identical is what makes a
 * saved secret actually reach the provider CLI.
 */
export interface ACPProviderSecretField {
  /** Secret name and env var (e.g. ``"ANTHROPIC_API_KEY"``). Must satisfy the
   * secret-name pattern ``^[a-zA-Z][a-zA-Z0-9_]{0,63}$``. */
  name: string;
  /** Render as a masked password input (API keys, OAuth tokens, credential
   * blobs) rather than a plain-text input (base URLs, project IDs). Doubles as
   * "this is an actual credential": when the onboarding step is required, only
   * a ``secret`` field satisfies it β€” a base URL or GCP scalar alone can't
   * authenticate anything. */
  secret?: boolean;
  /** Render as a multi-line textarea rather than a single-line input. Set for
   * file-content credentials the user pastes verbatim (Codex ``auth.json``,
   * Gemini Vertex service-account / ADC JSON) β€” the ones the SDK materialises
   * to disk, which a cloud backend can't consume yet (agent-canvas#1016). */
  multiline?: boolean;
  /** i18n key for the one-line helper text under the field. */
  hint_key: I18nKey;
  /**
   * Interpolation values for {@link hint_key} (e.g. ``{ file: "~/.codex/auth.json" }``
   * for the shared "paste the file contents" hint). Omitted for hints that
   * take no parameters.
   */
  hint_values?: Record<string, string>;
}

/**
 * Container credentials β€” beyond the registry's API key / base URL β€” that
 * canvas collects per provider so a *containerized* agent-server (no host login
 * state) can authenticate the ACP CLI: subscription tokens plus the file-content
 * blobs and Vertex config the SDK's ``acp_file_secrets`` materialisation
 * consumes (agent-canvas#1013/#1014). They have no registry env-var entry
 * because they're a deployment concern, not a model registry field. The Gemini
 * project/location/flag are plain config, not secrets β€” grouped here because
 * they travel with the SA blob.
 *
 * The blob *names* (``CODEX_AUTH_JSON`` / ``GOOGLE_APPLICATION_CREDENTIALS_JSON``)
 * duplicate the SDK registry's ``file_secrets`` specs; derive them from the
 * client registry once the pinned ``@openhands/typescript-client`` mirrors that
 * field (same bump that unblocks ``acp_isolate_data_dir``, see #1019).
 */
const ACP_RESERVED_CREDENTIALS: Record<string, ACPProviderSecretField[]> = {
  codex: [
    {
      name: "CODEX_AUTH_JSON",
      secret: true,
      multiline: true,
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_FILE_BLOB_HINT,
      hint_values: { file: "~/.codex/auth.json" },
    },
  ],
  "claude-code": [
    {
      name: "CLAUDE_CODE_OAUTH_TOKEN",
      secret: true,
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_OAUTH_TOKEN_HINT,
    },
  ],
  "gemini-cli": [
    {
      name: "GOOGLE_APPLICATION_CREDENTIALS_JSON",
      secret: true,
      multiline: true,
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_FILE_BLOB_HINT,
      hint_values: {
        file: "~/.config/gcloud/application_default_credentials.json",
      },
    },
    {
      name: "GOOGLE_CLOUD_PROJECT",
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_GCP_PROJECT_HINT,
    },
    {
      name: "GOOGLE_CLOUD_LOCATION",
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_GCP_LOCATION_HINT,
    },
    {
      name: "GOOGLE_GENAI_USE_VERTEXAI",
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_VERTEXAI_FLAG_HINT,
    },
  ],
  pi: [
    {
      name: "PI_AUTH_JSON",
      secret: true,
      multiline: true,
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_FILE_BLOB_HINT,
      hint_values: { file: "~/.pi/agent/auth.json" },
    },
  ],
  opencode: [
    {
      name: "OPENCODE_AUTH_CONTENT",
      secret: true,
      multiline: true,
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_AUTH_CONTENT_HINT,
      hint_values: { file: "~/.local/share/opencode/auth.json" },
    },
  ],
};

/**
 * Credential pairs that break each other at runtime, keyed by provider β€”
 * mirrors the SDK's ``_ENV_CONFLICT_MAP`` (software-agent-sdk#3588). Claude's
 * OAuth token (``CLAUDE_CODE_OAUTH_TOKEN``) authenticates against Anthropic
 * directly, so when it is set the SDK strips:
 *   - ``ANTHROPIC_API_KEY``  β€” otherwise it takes precedence and silently
 *     bypasses the subscription;
 *   - ``ANTHROPIC_BASE_URL`` β€” otherwise it proxies the bearer to an endpoint
 *     that rejects it (see docs/ACP_AGENTS.md).
 * Either one set alongside the token is silently ignored at runtime, so warn.
 */
const ACP_CREDENTIAL_CONFLICTS: Record<string, Array<[string, string]>> = {
  "claude-code": [
    ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"],
    ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_BASE_URL"],
  ],
};

/**
 * The ``[credential, conflicting]`` pairs the user currently has set for
 * ``providerKey``. ``hasValue`` should cover both typed and already-saved
 * values, since a previously saved secret conflicts just the same.
 */
export function getAcpCredentialConflicts(
  key: string | null | undefined,
  hasValue: (name: string) => boolean,
): Array<[string, string]> {
  if (!key) return [];
  return (ACP_CREDENTIAL_CONFLICTS[key] ?? []).filter(
    ([credential, conflicting]) =>
      hasValue(credential) && hasValue(conflicting),
  );
}

/**
 * Vertex AI-safe ``acp_model`` for Gemini.
 *
 * Left unset, gemini-cli falls back to its own internal default β€” a preview
 * flash model that 404s on Google Cloud projects without preview access. And a
 * ``*-flash`` id is no safer to pin: gemini-cli re-resolves flash ids at
 * generation time to its *current default* flash (software-agent-sdk#3532), so
 * a pinned ``gemini-2.5-flash`` still ran ``gemini-3-flash``. Only a non-flash
 * id sticks; ``gemini-2.5-pro`` is broadly available on Vertex and the
 * API-key / Google-login paths, so canvas preselects it. Kept as a named
 * constant so every model-default consumer agrees.
 */
export const ACP_VERTEX_SAFE_MODEL = "gemini-2.5-pro";

/**
 * The ``acp_model`` canvas substitutes for ``providerKey`` wherever no concrete
 * model is configured β€” settings seeding (onboarding, Settings β†’ Agent), the
 * {@link buildAcpAgentSettingsDiff} fallback, and the start-request fallback
 * for a saved ``null``. ``null`` lets the agent use its own default; only
 * Gemini's own default is unsafe (see {@link ACP_VERTEX_SAFE_MODEL}).
 */
export function getAcpPreferredDefaultModel(
  key: string | null | undefined,
): string | null {
  return key === "gemini-cli" ? ACP_VERTEX_SAFE_MODEL : null;
}

/**
 * List the credentials Canvas should prompt for when onboarding the given ACP
 * provider. The API-key and base-URL field *names* track the SDK registry's
 * ``api_key_env_var`` / ``base_url_env_var`` (mirrored via
 * ``@openhands/typescript-client``) so they can't drift as providers are added
 * or renamed; the per-provider container credentials (subscription / Vertex
 * blobs) come from {@link ACP_RESERVED_CREDENTIALS}, since those are a
 * containerized-deployment concern with no model-registry entry. Each field
 * name equals the env var the agent-server exports into the provider subprocess
 * (which is what makes a saved secret reach the CLI). On the wire none of this
 * is special β€” every saved credential travels uniformly as a ``LookupSecret``.
 *
 * Field order is: container subscription/Vertex credentials β†’ API key β†’
 * optional base URL. Every field is optional at the UI level β€” the step is
 * skippable, and a subscription / OAuth login on the backend takes precedence
 * over a key at runtime. (Whether the *step* is required is a
 * backend-capability decision the onboarding modal makes; see
 * ``backendRequiresAcpCredentials``.)
 *
 * NB: the base URL is rendered plain-text (not ``secret``), so it never counts
 * toward a required credential step β€” setting ``ANTHROPIC_BASE_URL`` alongside
 * a ``CLAUDE_CODE_OAUTH_TOKEN`` breaks the token's bearer auth, which the forms
 * surface via {@link getAcpCredentialConflicts}.
 *
 * Returns ``[]`` for OpenHands, the ``"custom"`` preset, any unknown key, and a
 * future OAuth-only provider whose registry entry has no ``api_key_env_var`` β€”
 * callers treat an empty list as "no credentials step for this provider".
 */
export function getAcpProviderSecrets(
  key: string | null | undefined,
): ACPProviderSecretField[] {
  if (!key) return [];
  // Surfaced providers only. The client registry grows with every harness the
  // SDK adds, so reading it directly would offer credential fields for one
  // Canvas never lists.
  if (!getAcpProvider(key)) return [];
  const info = getClientAcpProvider(key);
  if (!info) return [];
  // Subscription / Vertex credentials first β€” they're the primary auth path for
  // ACP providers (Claude Pro/Max OAuth token, Codex ChatGPT auth.json), with
  // the API key as the fallback below.
  const fields: ACPProviderSecretField[] = [
    ...(ACP_RESERVED_CREDENTIALS[key] ?? []),
  ];
  if (info.api_key_env_var) {
    fields.push({
      name: info.api_key_env_var,
      secret: true,
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_API_KEY_HINT,
    });
  }
  if (info.base_url_env_var) {
    fields.push({
      name: info.base_url_env_var,
      hint_key: I18nKey.ONBOARDING$ACP_SECRET_BASE_URL_HINT,
    });
  }
  return fields;
}

/**
 * Look up a built-in ACP provider config by its registry key.
 *
 * Returns ``undefined`` for an empty / null key, for the ``"custom"`` preset
 * (which has no registry entry), and for any forward-compatible key Canvas's
 * registry doesn't know about yet. Centralizes the ``ACP_PROVIDERS.find(...)``
 * lookup shared by the resolvers below and by the adapter / settings surfaces
 * so the key-comparison shape lives in one place.
 */
export function getAcpProvider(
  key: string | null | undefined,
): ACPProviderConfig | undefined {
  if (!key) return undefined;
  return ACP_PROVIDERS.find((provider) => provider.key === key);
}

/**
 * Resolve an ACP provider registry key (the value stored under
 * ``tags.acpserver`` on a conversation) to a human display name for the
 * sidebar chip.
 *
 * Returns ``null`` for an empty / null key and for keys not in
 * {@link ACP_PROVIDERS} β€” most notably ``"custom"`` (the user-supplied
 * command preset has no canonical brand name) and any forward-compatible
 * value Canvas's registry doesn't know about yet. Callers should fall
 * back to a generic ``"ACP"`` label in that case so the chip still
 * communicates "this is an ACP conversation".
 *
 * Kept separate from {@link buildAcpAgentSettingsDiff}'s lookup so the
 * conversation-card render path can resolve display names without
 * importing the settings-payload builder.
 */
export function getAcpProviderDisplayName(
  key: string | null | undefined,
): string | null {
  const found = getAcpProvider(key);
  return found ? found.display_name : null;
}

/**
 * Resolve an ACP provider registry key to the icon discriminator the
 * conversation chip should render alongside the model text.
 *
 * Falls back to {@link ACP_PROVIDER_FALLBACK_ICON} for ``"custom"``,
 * unknown keys, or a missing key β€” the chip then shows a neutral
 * terminal glyph that still communicates "this is an ACP conversation"
 * without claiming a brand identity we don't know.
 */
export function resolveAcpProviderIcon(
  key: string | null | undefined,
): ACPProviderIcon {
  return getAcpProvider(key)?.icon ?? ACP_PROVIDER_FALLBACK_ICON;
}

/**
 * The label the agent gave ``modelId`` in ``models``, else the raw ID. Returns
 * ``null`` only when there is no model to show, letting the conversation chip
 * display the provider name instead.
 */
export function labelForAcpModel(
  modelId: string | null | undefined,
  models: readonly ACPModelOption[] = [],
): string | null {
  if (!modelId) return null;
  return models.find(({ id }) => id === modelId)?.label ?? modelId;
}

/** Picker options for the models an ACP server reported. */
export function toAcpModelOptions(
  models: readonly ACPModelInfo[] | null | undefined,
): ACPModelOption[] {
  return (models ?? [])
    .filter(({ model_id }) => model_id)
    .map(({ model_id, name }) => ({
      id: model_id,
      label: name?.trim() || model_id,
    }));
}

/**
 * Build the ``agent_settings_diff`` payload PATCH /api/settings expects
 * for the agent-kind/provider choice the user just made.
 *
 * Returns ``null`` for an unknown ACP provider key β€” the caller can skip
 * the save (the UI shouldn't surface unknown options, but the defensive
 * path keeps a buggy preset list from corrupting settings).
 */
export function buildAcpAgentSettingsDiff(
  providerKey: string,
): Record<string, unknown> | null {
  if (providerKey === "openhands") {
    // Switching back to OpenHands. The agent-server's ``Settings.update``
    // applies a fresh ``{'agent_kind': ...}`` base whenever the kind
    // flips, so any ``acp_*`` fields would be discarded before
    // validation. Send the kind alone.
    return { agent_kind: "openhands" };
  }

  const isCustom = providerKey === ACP_CUSTOM_PRESET_KEY;
  if (!isCustom && !getAcpProvider(providerKey)) {
    return null;
  }

  // ``acp_args: []`` resets any API-set ``acp_args`` that would
  // otherwise survive and concatenate to ``acp_command`` at spawn time
  // (the agent-server merges the two before exec).
  return {
    agent_kind: "acp",
    acp_server: providerKey,
    acp_command: [],
    acp_args: [],
    acp_model: getAcpPreferredDefaultModel(providerKey) ?? null,
  };
}