Skip to content

πŸ™Œ OpenHands: AI-Driven Development

9.6 KB
Raw Blame
import {
  AUTOMATION_CATALOG,
  type AutomationTriggerKind,
  type RecommendedAutomation,
} from "@openhands/extensions/automations";
import {
  SKILLS_CATALOG,
  type SkillCatalogEntry,
} from "@openhands/extensions/skills";
import type { LucideIcon } from "lucide-react";
import { MANIFEST_ICON_BY_SLUG } from "#/components/features/manifest/manifest-icons";
import { interpolateValues } from "#/manifests/manifest-template";
import type { Automation } from "#/types/automation";

/**
 * Reading a published automation catalog entry.
 *
 * The catalog states each thing once and leaves the rest to be derived, so an
 * entry no longer carries its own launch command or a flat list of required
 * integration ids. This module is the single place that performs those
 * derivations, so the components consuming the catalog stay unaware of how it
 * is shaped.
 */

const SKILL_BY_NAME = new Map<string, SkillCatalogEntry>(
  SKILLS_CATALOG.map((skill) => [skill.name, skill]),
);

/**
 * The glyph a card shows in place of its integration logos, or null when it
 * has none to show and the logos speak for it.
 *
 * An entry naming the service it talks to is recognised by that service's
 * logo; one whose identity is the work itself declares a slug instead. The
 * lookup is a guard as much as a mapping β€” the catalog is published elsewhere,
 * so a slug this host has no artwork for falls back rather than rendering
 * nothing.
 */
export function getAutomationIcon(
  automation: RecommendedAutomation,
): LucideIcon | null {
  const slug = automation.icon;
  if (!slug) return null;
  return (
    (MANIFEST_ICON_BY_SLUG as Record<string, LucideIcon | undefined>)[slug] ??
    null
  );
}

/** Every integration the entry declares, in declaration order. */
export function getIntegrationIds(automation: RecommendedAutomation): string[] {
  return Object.keys(automation.requires.integrations);
}

/**
 * The integrations that gate this automation. One marked `required: false` can
 * be connected later, during setup, so it is still worth showing on the card
 * but must never stand between the user and a launch.
 */
export function getRequiredIntegrationIds(
  automation: RecommendedAutomation,
): string[] {
  return Object.entries(automation.requires.integrations)
    .filter(([, requirement]) => requirement.required !== false)
    .map(([id]) => id);
}

/**
 * Every integration a template is about, for filtering: the ones it declares
 * plus the git provider of any repository picker in its setup form. Several
 * GitHub templates declare no integration (their worker uses the connected
 * account's token) and are GitHub only by that picker.
 */
export function getTemplateIntegrationIds(
  automation: RecommendedAutomation,
): string[] {
  const ids = getIntegrationIds(automation);
  for (const field of Object.values(automation.setup?.form.args ?? {})) {
    if (
      field.type === "repo-picker" &&
      field.provider &&
      !ids.includes(field.provider)
    ) {
      ids.push(field.provider);
    }
  }
  return ids;
}

export type TemplateTriggerKind = AutomationTriggerKind;

const TEMPLATE_TRIGGER_KINDS: readonly TemplateTriggerKind[] = [
  "cron",
  "event",
];

function isTemplateTriggerKind(value: unknown): value is TemplateTriggerKind {
  return TEMPLATE_TRIGGER_KINDS.includes(value as TemplateTriggerKind);
}

/**
 * How a template runs once created. A setup form states it as the keys of
 * `setup.form.triggers`; an entry without one may state it as a top-level
 * `triggers` list, read off the raw entry because the pinned package may
 * predate the field. Empty when the catalog says nothing, so the card shows
 * no badge and only a trigger filter leaves it out.
 */
export function getTemplateTriggerKinds(
  automation: RecommendedAutomation,
): TemplateTriggerKind[] {
  const formTriggers = automation.setup?.form.triggers;
  if (formTriggers) {
    return Object.keys(formTriggers).filter(isTemplateTriggerKind);
  }
  const { triggers } = automation as unknown as Record<string, unknown>;
  return Array.isArray(triggers) ? triggers.filter(isTemplateTriggerKind) : [];
}

/**
 * Catalog entries an OpenHands Enterprise install does not offer: each one
 * overlaps a built-in integration, depends on a user-managed secret, or is
 * covered by the Create Automation UI. They stay in the catalog for OpenHands
 * Cloud and local backends.
 */
const SELF_HOSTED_HIDDEN_AUTOMATION_IDS: ReadonlySet<string> = new Set([
  "github-repo-monitor",
  "slack-standup-digest",
  "github-issue-triage",
  "github-delivery-watchdog",
  "github-stale-ci-pr-closer",
  "custom-automation",
]);

const NO_HIDDEN_AUTOMATION_IDS: ReadonlySet<string> = new Set();

/**
 * The catalog entries to hide for a backend reporting `deploymentMode` (the
 * cloud web-client config's `feature_flags.deployment_mode`). Only a
 * self-hosted (Enterprise) instance hides anything.
 */
export function getHiddenAutomationIds(
  deploymentMode: string | null | undefined,
): ReadonlySet<string> {
  return deploymentMode === "self_hosted"
    ? SELF_HOSTED_HIDDEN_AUTOMATION_IDS
    : NO_HIDDEN_AUTOMATION_IDS;
}

/**
 * The command that invokes this automation's skill, or null when that skill is
 * invoked by description instead.
 *
 * The command is declared once, in the owning skill's own `triggers`; the
 * catalog names that skill only where it differs from the entry id.
 */
export function findAutomationCommand(
  automation: Pick<RecommendedAutomation, "id" | "skill">,
): string | null {
  const skill = SKILL_BY_NAME.get(automation.skill ?? automation.id);
  return skill?.triggers[0] ?? null;
}

/**
 * What launching an automation card hands to the agent.
 *
 * The resolved command is passed through as-is: API routing (host, auth) is
 * discovered by the agent at runtime from `<RUNTIME_SERVICES>` in the system
 * prompt, and the skills themselves carry the instructions for reading that
 * block. An automation whose skill declares no command has the request spelled
 * out instead. Both are instructions to the agent rather than user-facing UI
 * copy, so they are intentionally in English and not localized.
 */
export function getAutomationLaunchPrompt(
  automation: RecommendedAutomation,
): string {
  return (
    findAutomationCommand(automation) ??
    `Set up the ${automation.name} automation`
  );
}

const CATALOG_ENTRY_BY_ID = new Map<string, RecommendedAutomation>(
  AUTOMATION_CATALOG.map((entry) => [entry.id, entry]),
);

/** Rejects markup the same way the catalog schema's copy rule does. */
const MARKUP_PATTERN = /<[A-Za-z/!]/;

/** Every `{{` an impact phrase opens must be the count placeholder. */
const FOREIGN_PLACEHOLDER_PATTERN = /\{\{(?!count\}\})/;

const COUNT_PLACEHOLDER = "{{count}}";

interface AutomationImpactCopy {
  one: string;
  other: string;
}

function isImpactPhrase(value: unknown): value is string {
  return (
    typeof value === "string" &&
    value.length > 0 &&
    !MARKUP_PATTERN.test(value) &&
    !FOREIGN_PLACEHOLDER_PATTERN.test(value)
  );
}

/**
 * The entry's `impact` value statement, or null when it declares none this
 * host can honor. The catalog is published elsewhere, so the field is read
 * off the raw entry and validated here rather than trusted from the package
 * types β€” which also keeps this module compiling against a pinned package
 * that predates the field. A basis other than `completed-runs` is a counter
 * this host does not know how to compute, so it renders nothing rather than
 * a number the phrase was not written for.
 */
function readImpactCopy(
  entry: RecommendedAutomation,
): AutomationImpactCopy | null {
  const { impact } = entry as unknown as Record<string, unknown>;
  if (typeof impact !== "object" || impact === null) return null;
  const { basis, one, other } = impact as Record<string, unknown>;
  if (basis !== "completed-runs") return null;
  if (!isImpactPhrase(one) || !isImpactPhrase(other)) return null;
  if (!other.includes(COUNT_PLACEHOLDER)) return null;
  return { one, other };
}

/**
 * The catalog entry an installed automation was created from, via the
 * `template` provenance its setup stored β€” the only join back to the catalog.
 * Null for automations without provenance: imports, agent-built ones, and
 * entries whose setup publishes no version.
 */
function getAutomationTemplateEntry(
  automation: Automation,
): RecommendedAutomation | null {
  const metadata = automation.preset_metadata;
  if (typeof metadata !== "object" || metadata === null) return null;
  const { template } = metadata as Record<string, unknown>;
  if (typeof template !== "object" || template === null) return null;
  const { id } = template as Record<string, unknown>;
  if (typeof id !== "string" || id.length === 0) return null;
  return CATALOG_ENTRY_BY_ID.get(id) ?? null;
}

/**
 * The value statement an automation card shows for its completed runs, or
 * null when there is nothing defensible to say: no template provenance, no
 * honored `impact` declaration, an unknown count (older service with more
 * history than the sample), or a count of zero β€” absence, never a zero-value
 * claim. Provenance persists across prompt edits, so a reworked automation
 * keeps its template's phrase; the phrases are run-shaped, which keeps them
 * true for as long as the automation runs at all.
 */
export function resolveAutomationImpactStatement(
  automation: Automation,
  completedTotal: number | null,
): string | null {
  if (completedTotal === null || completedTotal < 1) return null;
  const entry = getAutomationTemplateEntry(automation);
  if (!entry) return null;
  const copy = readImpactCopy(entry);
  if (!copy) return null;
  const phrase = completedTotal === 1 ? copy.one : copy.other;
  return interpolateValues(phrase, { count: completedTotal.toLocaleString() });
}