π OpenHands: AI-Driven Development
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;
}