Automation Run Channel
JSON Schema: state.schema.json
State Types
AutomationRunStatus
Lifecycle status of one automation run.
completed, failed, and cancelled are terminal. A run remains running while any linked session awaits input or client-side work; linked session state is authoritative for those interactions.
| Member | Value | Description |
|---|---|---|
Pending | 'pending' | The durable run record exists but execution has not started. |
Running | 'running' | One or more linked sessions are executing or awaiting interaction. |
Completed | 'completed' | Execution finished successfully. |
Failed | 'failed' | Execution ended with an error. |
Cancelled | 'cancelled' | Execution ended because cancellation was accepted. |
AutomationRunOriginKind
Discriminant describing what created an automation run.
| Member | Value | Description |
|---|---|---|
Manual | 'manual' | A client explicitly invoked {@link RunAutomationParams | runAutomation}. |
Trigger | 'trigger' | An automatic schedule or event trigger fired. |
AutomationManualRunOrigin
Origin recorded for a client-requested manual run.
| Field | Type | Description |
|---|---|---|
kind | AutomationRunOriginKind.Manual |
AutomationTriggeredRunOrigin
Origin recorded for a run created by one of the automation's triggers.
| Field | Type | Required | Description |
|---|---|---|---|
kind | AutomationRunOriginKind.Trigger | Yes | |
triggerId | string | Yes | Matches the stable {@link AutomationScheduleTrigger.id} or {@link AutomationEventTrigger.id} in the definition. |
scheduledFor | string | No | Intended schedule occurrence as an ISO 8601 timestamp. Present for schedule triggers and normally absent for event triggers. |
catchUp | boolean | No | true when this is a catch-up run created by {@link AutomationMisfirePolicy.RunOnce}. |
event | Record<string, unknown> | No | Host-defined, non-secret event provenance suitable for display or audit. This is descriptive context, not an input that clients replay. |
AutomationRunOrigin
Immutable provenance describing why a run was created.
AutomationManualRunOrigin | AutomationTriggeredRunOrigin
AutomationPendingRunLifecycle
A durable run exists but has not begun external execution.
| Field | Type | Description |
|---|---|---|
status | AutomationRunStatus.Pending | |
createdAt | string | Run creation timestamp in ISO 8601 format. |
AutomationRunningRunLifecycle
The run is executing linked sessions or awaiting interaction on them.
Linked {@link SessionState.status} and {@link SessionState.inputNeeded} remain authoritative for whether user attention or client-side work is required.
| Field | Type | Description |
|---|---|---|
status | AutomationRunStatus.Running | |
createdAt | string | Run creation timestamp in ISO 8601 format. |
startedAt | string | First execution start timestamp in ISO 8601 format. |
AutomationCompletedRunLifecycle
Terminal lifecycle for a successfully completed run.
| Field | Type | Required | Description |
|---|---|---|---|
status | AutomationRunStatus.Completed | Yes | |
createdAt | string | Yes | Run creation timestamp in ISO 8601 format. |
startedAt | string | Yes | First execution start timestamp in ISO 8601 format. |
completedAt | string | Yes | Completion timestamp in ISO 8601 format. |
usage | UsageInfo | No | Optional aggregate model usage across all linked sessions. |
AutomationFailedRunLifecycle
Terminal lifecycle for a run that ended with an error.
startedAt is absent when failure occurred before execution began, such as session-template validation or workspace preparation.
| Field | Type | Required | Description |
|---|---|---|---|
status | AutomationRunStatus.Failed | Yes | |
createdAt | string | Yes | Run creation timestamp in ISO 8601 format. |
startedAt | string | No | First execution start timestamp in ISO 8601 format, when execution began. |
completedAt | string | Yes | Failure timestamp in ISO 8601 format. |
error | ErrorInfo | Yes | Stable machine-readable and human-readable failure information. |
AutomationCancelledRunLifecycle
Terminal lifecycle for a cancelled run.
startedAt is absent when cancellation completed while the run was still pending.
| Field | Type | Required | Description |
|---|---|---|---|
status | AutomationRunStatus.Cancelled | Yes | |
createdAt | string | Yes | Run creation timestamp in ISO 8601 format. |
startedAt | string | No | First execution start timestamp in ISO 8601 format, when execution began. |
completedAt | string | Yes | Cancellation completion timestamp in ISO 8601 format. |
AutomationRunLifecycle
Discriminated lifecycle of an automation run.
AutomationPendingRunLifecycle | AutomationRunningRunLifecycle | AutomationCompletedRunLifecycle | AutomationFailedRunLifecycle | AutomationCancelledRunLifecycle
AutomationRunSummary
Lightweight projection of a run retained in its automation's history.
A summary contains enough information to render run history without subscribing to every ahp-automation-run: resource.
| Field | Type | Required | Description |
|---|---|---|---|
resource | URI | Yes | Subscribable ahp-automation-run: URI matching {@link AutomationRunState.resource}. |
automation | URI | Yes | Owning ahp-automation: URI matching {@link AutomationRunState.automation}. |
origin | AutomationRunOrigin | Yes | Immutable provenance matching {@link AutomationRunState.origin}. |
lifecycle | AutomationRunLifecycle | Yes | Current or terminal lifecycle snapshot matching {@link AutomationRunState.lifecycle}. |
primarySession | URI | No | Session matching {@link AutomationRunState.primarySession}, when selected. |
sessionCount | number | Yes | Number of entries in {@link AutomationRunState.sessions}. |
_meta | Record<string, unknown> | No | Opaque host-defined summary metadata. |
AutomationRunState
Authoritative state of one subscribed ahp-automation-run: resource.
The run channel owns task-level lifecycle, provenance, and linked-session membership. Linked session and chat channels remain authoritative for transcripts, tools, interaction requirements, changesets, and per-session lifecycle.
| Field | Type | Required | Description |
|---|---|---|---|
resource | URI | Yes | URI of this automation-run channel. |
automation | URI | Yes | Owning ahp-automation: URI matching {@link AutomationState.resource}. |
origin | AutomationRunOrigin | Yes | Immutable provenance describing how this run was created. |
lifecycle | AutomationRunLifecycle | Yes | Current or terminal lifecycle. |
sessions | URI[] | Yes | Ordered, unique session URIs belonging to this run, each matching {@link SessionState.resource}. Entries may represent retries, parallel workers, or delegated attempts. |
primarySession | URI | No | Member of {@link AutomationRunState.sessions} that the host recommends opening first. |
_meta | Record<string, unknown> | No | Opaque host-defined run metadata. |
Actions
JSON Schema: actions.schema.json
automationRun/lifecycleChanged
Replace the run lifecycle.
The host dispatches this action for every lifecycle transition.
| Field | Type | Description |
|---|---|---|
type | ActionType.AutomationRunLifecycleChanged | |
lifecycle | AutomationRunLifecycle | Complete replacement {@link AutomationRunState.lifecycle}. |
automationRun/sessionSet
Add a session to {@link AutomationRunState.sessions}.
Session URIs are unique. Setting an existing URI is a no-op.
| Field | Type | Description |
|---|---|---|
type | ActionType.AutomationRunSessionSet | |
session | URI | Session URI to append to {@link AutomationRunState.sessions} when not already linked. |
automationRun/sessionRemoved
Remove a linked session from the run.
Removing the current primary session also clears {@link AutomationRunState.primarySession}. An unknown URI is a no-op.
| Field | Type | Description |
|---|---|---|
type | ActionType.AutomationRunSessionRemoved | |
session | URI | Entry in {@link AutomationRunState.sessions} to remove. |
automationRun/primarySessionChanged
Select or clear the session clients should open first for this run.
| Field | Type | Required | Description |
|---|---|---|---|
type | ActionType.AutomationRunPrimarySessionChanged | Yes | |
primarySession | URI | No | New {@link AutomationRunState.primarySession}, or omitted to clear the selection. |
automationRun/cancelRequested
Ask the host to cancel this run.
This is the only client-dispatchable automation-run action. It is a side-effect request and deliberately leaves optimistic state unchanged. The client may dispatch it only when the host advertises its runCancellation capability and the current lifecycle is pending or running. The host revalidates that the run is non-terminal. The authoritative outcome arrives later through {@link AutomationRunLifecycleChangedAction}: cancellation may transition to cancelled, or the run may complete or fail before cancellation takes effect.
| Field | Type | Description |
|---|---|---|
type | ActionType.AutomationRunCancelRequested |