Skip to content

πŸ™Œ OpenHands: AI-Driven Development

9.6 KB
Raw Blame
export interface AutomationTrigger {
  /**
   * Trigger kind. Known values are the schedule aliases "cron" / "schedule"
   * (time-based) and "event" (webhook/event-driven). Kept as `string` rather
   * than a closed union on purpose: the backend emits more than one
   * scheduled-trigger alias and may introduce new kinds, so UI code branches
   * on `type === "event"` and treats every other value as a schedule.
   */
  type: string;
  /** Cron expression (schedule triggers only). */
  schedule?: string;
  /** Human-readable schedule description (schedule triggers only). */
  schedule_human?: string;
  /** IANA timezone name (schedule triggers only). */
  timezone?: string;
  /** Event source, e.g. "github" (event triggers only). */
  source?: string;
  /** Event key pattern(s) to match, e.g. "pull_request.opened" or ["push", "release.*"]. */
  on?: string | string[];
  /** JMESPath filter expression evaluated against the raw webhook payload. */
  filter?: string;
}

/**
 * A repository an automation clones before it runs, as the preset API stores
 * it in `preset_metadata.repos[]` (the SDK's `RepoSource`).
 */
export interface AutomationRepository {
  /** Full git URL, or the `owner/repo` shorthand. */
  url: string;
  /** Branch, tag or commit to check out; absent uses the default branch. */
  ref?: string;
  /** Git provider that authenticates the clone; required for the shorthand. */
  provider?: string;
}

export type AutomationState = "ACTIVE" | "INACTIVE" | "DRAFT";

export interface Automation {
  id: string;
  name: string;
  trigger: AutomationTrigger;
  enabled: boolean;
  /** Backend automation lifecycle state. Prefer this over deprecated `enabled` when present. */
  state?: AutomationState | string | null;
  /**
   * Human-readable reason the automation was last disabled (the latest
   * disablement event overwrites this). Mirrors the automation service's
   * `AutomationResponse.disabled_reason`. `null`/absent for enabled automations
   * or an automation service older than the release that started recording it.
   */
  disabled_reason?: string | null;
  /**
   * Structured disablement metadata from the automation service
   * (`AutomationResponse.disabled_detail`): `{reason, source, run_id, ...}`
   * plus rule-specific fields (threshold, consecutive counts, status_detail).
   * Used to tell user-initiated ("manual") disables from automatic ones
   * (consecutive failures, permanent config faults).
   */
  disabled_detail?: {
    reason?: string;
    source?: string;
    run_id?: string | null;
    [key: string]: unknown;
  } | null;
  /** UTC timestamp the automation was last disabled. */
  disabled_at?: string | null;
  /**
   * UUID of the user who created this automation. The backend returns it in
   * `AutomationResponse.user_id`; the frontend uses it to implement the
   * "creator escape hatch" β€” a member (view-only) may still edit their own
   * automations even without `manage_automations`.
   */
  user_id?: string;
  /**
   * Single repository in the import/export file's shape. The automation
   * service does not return it; read `repositories` for what an automation
   * clones.
   */
  repository?: string;
  /** Saved agent profile controlling model, tools, and selected secrets. */
  agent_profile_id?: string | null;
  /** LLM/model profile name used when no agent profile is selected. */
  model?: string | null;
  /**
   * Maximum run time in seconds. `null`/omitted uses the server default
   * (600s, 10 min); the deployment reports the maximum it accepts.
   */
  timeout?: number | null;

  created_at: string;
  updated_at: string;
  prompt: string | null;
  /**
   * Shell command the automation service runs in the unpacked bundle's root
   * (e.g. `python main.py`). Mirrors `AutomationResponse.entrypoint`; the
   * detail page uses it to point out which bundle file is the script.
   */
  entrypoint?: string;
  /** Service-owned upload identifier/path for custom automation bundles. */
  tarball_path?: string | null;
  /** Optional setup script path inside the custom automation bundle. */
  setup_script_path?: string | null;
  branch?: string;
  /**
   * Every repository the automation clones. The service layer derives it on
   * read from `preset_metadata.repos` (or the top-level `repository`/`branch`
   * when there is no metadata); the service has no top-level field for it.
   */
  repositories?: AutomationRepository[];
  /**
   * Plugin sources (e.g. `github:owner/repo`). The service layer fills it on
   * read from `preset_metadata.plugins[].source`; a record without that
   * metadata keeps its own list.
   */
  plugins?: string[];
  notification?: string;
  timezone?: string;
  last_triggered_at?: string | null;
  /**
   * Service-owned preset state, returned verbatim. The GUI reads the
   * `template` provenance block inside it ({id, version, config}, written at
   * setup time) only through the guarded helper in
   * `#/utils/automation-catalog`, and `repos`/`plugins` only through
   * `#/utils/automation-preset-sources`.
   */
  preset_metadata?: Record<string, unknown> | null;
}

export type AutomationSpec = Omit<
  Automation,
  | "id"
  | "created_at"
  | "updated_at"
  | "last_triggered_at"
  | "preset_metadata"
  | "repositories"
  | "entrypoint"
  | "disabled_reason"
  | "disabled_detail"
  | "disabled_at"
>;

/** The envelope constants come from the interface manifest's import/export spec. */
export interface AutomationExportFile {
  version: number;
  kind: string;
  spec: AutomationSpec;
}

export interface AutomationsResponse {
  automations: Automation[];
  total: number;
}

/**
 * Mirrors the list endpoint's `created_by` query param: the caller's
 * automations (`me`) or the rest of the org's (`others`).
 */
export type AutomationCreatedByFilter = "me" | "others";

/** Mirrors `RunStatus` in the automation service's OpenAPI schema. */
export enum AutomationRunStatus {
  PENDING = "PENDING",
  RUNNING = "RUNNING",
  COMPLETED = "COMPLETED",
  FAILED = "FAILED",
  CANCELLED = "CANCELLED",
  SKIPPED = "SKIPPED",
}

export type AutomationTaskOutcomeStatus =
  | "success"
  | "partial_success"
  | "blocked"
  | "failed"
  | "unknown";

export interface AutomationFinishToolResponse {
  status?: AutomationTaskOutcomeStatus | string;
  outcome_summary?: string;
  [key: string]: unknown;
}

export interface AutomationRunMetadata {
  finish_tool_response?: AutomationFinishToolResponse | string | null;
  [key: string]: unknown;
}

export interface AutomationRunStatusDetail {
  phase?: string;
  kind?: string;
  detail?: string;
  formatted_detail?: string;
  transient?: boolean;
  source?: string;
  operation?: string;
  code?: string;
  status_code?: number;
  [key: string]: unknown;
}

export interface AutomationRun {
  id: string;
  status: AutomationRunStatus;
  conversation_id: string | null;
  /**
   * ID of the bash command that ran the automation inside the agent-server
   * sandbox. Used to fetch run logs from
   * `/api/bash/bash_events/{bash_command_id}` and the matching
   * `BashOutput` events. Null when the run failed before a command was
   * dispatched (e.g. sandbox provisioning errors).
   */
  bash_command_id: string | null;
  /**
   * ID of the cloud sandbox that hosted the run. Script (deterministic)
   * automations never create a conversation, so on cloud backends this is
   * the only handle to the agent-server holding their logs. Null when the
   * run failed before a sandbox was provisioned; absent entirely against an
   * automation service that predates the field.
   */
  sandbox_id?: string | null;
  error_detail: string | null;
  status_detail?: AutomationRunStatusDetail | null;
  run_metadata?: AutomationRunMetadata | null;
  /**
   * Accumulated LLM cost of the run in USD, reported by the SDK in the
   * completion callback. `null` means unknown β€” the run predates cost
   * tracking, or ended without a callback (cancelled, watchdog timeout).
   * Absent entirely when the automation service is older than the release
   * that added the field, hence optional.
   */
  cost?: number | null;
  /**
   * User-facing live phase from automation β‰₯1.9.0. Free-form text the
   * service already sanitised for the dashboard β€” not a translation key.
   * `null` means nothing has been reported; absent entirely against a
   * service older than phase reporting.
   */
  current_phase?: string | null;
  started_at: string;
  completed_at: string | null;
}

export interface AutomationRunsResponse {
  runs: AutomationRun[];
  total: number;
  /**
   * Lifetime run counts by status, unaffected by pagination. Sparse β€” a
   * status with no runs has no key, so when the field is present a missing
   * key means zero. Absent entirely when the automation service is older
   * than the release that added it.
   */
  status_counts?: Partial<Record<AutomationRunStatus, number>>;
}

export type ActivityLogExportFormat = "json" | "csv";

/** Client-built Activity Log export row (from list runs + automation detail). */
export interface AutomationRunExportRow {
  run_id: string;
  automation_id: string;
  automation_name: string;
  trigger: AutomationTrigger | Record<string, unknown>;
  start_time: string | null;
  end_time: string | null;
  duration_seconds: number | null;
  status: AutomationRunStatus;
  conversation_id: string | null;
  conversation_url: string | null;
  error: string | null;
  /**
   * Accumulated LLM cost in USD, or null when unknown. Unlike
   * `AutomationRun["cost"]` this is always present: the row normalizes a
   * missing field to null so every exported record has the same shape.
   */
  cost: number | null;
  /**
   * The run's `current_phase` as stored. Null only when the run has no phase.
   */
  phase: string | null;
}