Automation Catalogue Channel

JSON Schema: state.schema.json

State Types

AutomationOperation

Operations the host currently permits for an automation.

The list on {@link AutomationState.operations} is authoritative and may change over time. Clients MUST NOT infer permission from capabilities alone: capabilities describe what the host implementation can support, while operations describe what is allowed for this particular automation now.

Member	Value	Description
Update	'update'	Replace editable fields using {@link AutomationUpdateRequestedAction | automation/updateRequested}.
Remove	'remove'	Permanently remove the automation using {@link AutomationRemovedAction | automation/removed}.
Run	'run'	Start a manual run using {@link RunAutomationParams | runAutomation}.

AutomationSchedule

A portable recurring schedule evaluated in a named time zone.

The expression uses exactly five whitespace-separated fields, in this order:

Field	Values
minute	0–59
hour	0–23
day of month	1–31
month	1–12 or JAN–DEC
day of week	0–7 or SUN–SAT; both 0 and 7 mean Sunday

Month and weekday names are ASCII and case-insensitive. Each field accepts *, a single value, an inclusive range (1-5), a comma-separated list of values or ranges (1,3,8-10), or a step applied to * or a range (for example, */15 or 1-30/2). A step MUST be a positive integer. AHP does not support seconds, years, macros such as @daily, or Quartz extensions such as ?, L, W, and #.

Minute, hour, and month must all match. When both day-of-month and day-of-week are restricted (not *), an occurrence matches when either day field matches, following Unix cron semantics.

Field	Type	Description
expression	string	Five-field AHP cron expression described by {@link AutomationSchedule}.
timeZone	string	IANA Time Zone Database identifier used to interpret the expression, for example "UTC" or "Europe/Berlin".

AutomationMisfirePolicy

How a host handles schedule occurrences missed while automatic execution was unavailable.

Member	Value	Description
Skip	'skip'	Discard missed occurrences and wait for the next future occurrence.
RunOnce	'runOnce'	Start at most one catch-up run when execution becomes available, regardless of how many occurrences were missed.

AutomationTriggerKind

Discriminant for automatic trigger definitions.

Member	Value	Description
Schedule	'schedule'	A portable recurring {@link AutomationSchedule}.
Event	'event'	A host-defined external event discovered from trigger definitions.

AutomationScheduleTrigger

Starts runs from a recurring cron schedule evaluated by the host.

Field	Type	Required	Description
id	string	Yes	Identifier unique and stable within this automation definition. Recorded in {@link AutomationTriggeredRunOrigin.triggerId} when this trigger creates a run.
kind	AutomationTriggerKind.Schedule	Yes
schedule	AutomationSchedule	Yes	Recurrence and time zone evaluated by the host.
misfirePolicy	AutomationMisfirePolicy	No	Policy for missed occurrences. Omission is equivalent to {@link AutomationMisfirePolicy.RunOnce}.

AutomationEventTrigger

Starts runs from events understood by the owning host.

Event trigger types, events, and configuration are discovered through {@link ListAutomationTriggerDefinitionsParams | listAutomationTriggerDefinitions}. The saved trigger includes the matching human-readable metadata so it remains displayable without repeating discovery.

Field	Type	Required	Description
id	string	Yes	Identifier unique and stable within this automation definition. Recorded in {@link AutomationTriggeredRunOrigin.triggerId} when this trigger creates a run.
kind	AutomationTriggerKind.Event	Yes
type	string	Yes	Matches {@link AutomationTriggerDefinition.type}.
title	string	Yes	Host-normalized human-readable trigger type name.
description	string	No	Optional host-normalized explanation of the trigger source.
events	AutomationTriggerEventDefinition[]	Yes	Selected events for this trigger type. Event ids carry the trigger semantics. Titles and descriptions are last-known display metadata and do not indicate current availability.
config	Record<string, unknown>	No	Values described by {@link AutomationTriggerDefinition.configSchema}. Clients MUST preserve unknown entries when editing other fields.

AutomationTrigger

An automatic trigger that can create runs for an enabled automation.

Manual execution is not represented as a trigger. An empty trigger list therefore means the automation is manual-only.

AutomationScheduleTrigger | AutomationEventTrigger

AutomationTriggerEventDefinition

Describes one host-defined trigger event.

Field	Type	Required	Description
id	string	Yes	Stable event id.
title	string	Yes	Human-readable event name.
description	string	No	Optional longer explanation of when this event fires.

AutomationTriggerDefinition

Describes one host-defined event trigger type available for a prospective automation session template.

Trigger definitions are discovery metadata, not durable automation state. Hosts may return different definitions for different providers, working directories, or session configuration.

Field	Type	Required	Description
type	string	Yes	Stable type id stored in {@link AutomationEventTrigger.type}.
title	string	Yes	Human-readable trigger type name.
description	string	No	Optional longer explanation of the trigger source.
events	AutomationTriggerEventDefinition[]	Yes	Events available for selection. Saved triggers retain their selected event descriptors.
configSchema	ConfigSchema	No	Optional schema for {@link AutomationEventTrigger.config}.

AutomationSessionTemplate

Template from which the host creates a fresh session for each automation run.

The host revalidates every selection when the run starts. Definitions never carry credentials, confirmation decisions, or durable permission grants.

Field	Type	Required	Description
provider	string	No	Provider id matching {@link AgentInfo.provider}. Omit to use the host's default provider.
model	ModelSelection	No	Optional model selection resolved when a run starts. Its {@link ModelSelection.id} matches a {@link SessionModelInfo.id} advertised by the selected provider.
agent	AgentSelection	No	Optional custom agent selection identified by {@link AgentSelection.uri}.
workingDirectories	URI[]	No	Ordered working-directory URIs for each created session, equivalent to {@link CreateSessionParams.workingDirectories}. Absence means a workspace-less session.
config	Record<string, unknown>	No	Session configuration values equivalent to {@link CreateSessionParams.config}, normally obtained from {@link ResolveSessionConfigResult.values}.

AutomationDefinition

Durable, client-editable definition of an automation.

A definition combines the initial automation message, the session template used for each run, and zero or more automatic triggers. Run history, timestamps, and currently allowed operations live on {@link AutomationState} rather than in the definition.

Field	Type	Required	Description
title	string	Yes	Human-readable automation name.
message	Message	Yes	Initial message sent to every newly created run session. Its {@link Message.origin} kind MUST be {@link MessageKind.Automation}.
session	AutomationSessionTemplate	Yes	Template used to create fresh sessions for each run.
enabled	boolean	Yes	Whether automatic triggers may create runs. Manual runs remain available whenever {@link AutomationOperation.Run} is advertised.
triggers	AutomationTrigger[]	Yes	Automatic triggers. An empty list means manual-only.
_meta	Record<string, unknown>	No	Opaque implementation-defined metadata. Clients MUST preserve unknown entries when updating the definition.

AutomationState

Authoritative state of one automation in the {@link AutomationCatalogState.automations} catalogue.

The host owns trigger evaluation, run claims, run retention, and operation availability. Clients render this state and submit actions or commands; they never run a fallback scheduler for a host-owned definition.

Field	Type	Required	Description
resource	URI	Yes	Stable ahp-automation:/<id> resource identifier.
definition	AutomationDefinition	Yes	Current durable definition.
nextRunAt	string	No	Earliest schedule occurrence awaiting evaluation, as an ISO 8601 timestamp. It may be in the past while catch-up is pending.
runs	AutomationRunSummary[]	Yes	Newest-first retained run summaries. This is a bounded window; use {@link FetchAutomationRunsParams | fetchAutomationRuns} when {@link AutomationState.runsNextCursor} is present.
runsNextCursor	string	No	Opaque cursor passed as {@link FetchAutomationRunsParams.cursor} for the next older run-history page.
operations	AutomationOperation[]	Yes	Operations currently permitted for this automation.
createdAt	string	Yes	Creation timestamp in ISO 8601 format.
modifiedAt	string	Yes	Last definition modification timestamp in ISO 8601 format.
_meta	Record<string, unknown>	No	Opaque host-defined state metadata.

AutomationCatalogState

Authoritative automation catalogue exposed on the ahp-automations:// channel.

A subscription snapshot contains every automation visible to the client. Subsequent {@link AutomationSetAction | automation/set} and {@link AutomationRemovedAction | automation/removed} actions keep the catalogue synchronized and participate in normal reconnect replay.

Field	Type	Required	Description
automations	AutomationState[]	Yes	Full automation states keyed by {@link AutomationState.resource}.
_meta	Record<string, unknown>	No	Opaque host-defined catalogue metadata.

Actions

JSON Schema: actions.schema.json

automation/createRequested

Ask the host to create a durable automation at a client-chosen resource.

Clients may dispatch this action only when the host advertises its create automation capability. {@link AutomationCreateRequestedAction.resource | resource} MUST use the ahp-automation: scheme and MUST NOT already identify an unrelated automation.

This side-effect request leaves optimistic catalogue state unchanged. The host validates trigger ids and configuration, normalizes event-trigger titles and descriptions, persists the definition, then publishes the authoritative result with {@link AutomationSetAction | automation/set}. Rejections leave the catalogue unchanged.

Field	Type	Description
type	ActionType.AutomationCreateRequested
resource	URI	Client-chosen ahp-automation: URI that becomes {@link AutomationState.resource}.
definition	AutomationDefinition	Complete initial {@link AutomationState.definition}.

automation/updateRequested

Ask the host to update editable fields of an existing automation.

Clients may dispatch this action only while the target advertises {@link AutomationOperation.Update}. The host revalidates that operation and the client's authorization.

This side-effect request leaves optimistic catalogue state unchanged. The host applies accepted patches to its current authoritative definition in action order, revalidates and normalizes affected event triggers, then publishes the result with {@link AutomationSetAction | automation/set}. Omitted fields remain unchanged; when accepted actions replace the same field, the later action in server order wins.

Field	Type	Description
type	ActionType.AutomationUpdateRequested
resource	URI	Target {@link AutomationState.resource}.
changes	AutomationDefinitionPatch	Editable {@link AutomationDefinition} fields to replace.

automation/set

Add or replace one full automation state in {@link AutomationCatalogState.automations}.

Existing entries are matched by {@link AutomationState.resource} and replaced in place. A previously unseen resource is appended.

Field	Type	Description
type	ActionType.AutomationSet
automation	AutomationState	Full new or replacement automation state.

automation/removed

Remove one automation from {@link AutomationCatalogState.automations}.

Clients may dispatch this action only while the target advertises {@link AutomationOperation.Remove}. The host revalidates that operation before permanently deleting the automation. A rejected action leaves the authoritative catalogue and durable definition unchanged.

Removing an unknown resource is a no-op.

Field	Type	Description
type	ActionType.AutomationRemoved
resource	URI	{@link AutomationState.resource} to remove.

Commands

JSON Schema: commands.schema.json

listAutomationTriggerDefinitions

Discover event-trigger types available for a prospective session template.

Hosts may vary definitions by provider, workspace, and session configuration. Schedule triggers are protocol-defined and therefore do not appear in this result. The result describes current authoring and validation choices. Saved {@link AutomationEventTrigger} values retain their selected event descriptors for display but do not establish current availability.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
channel	'ahp-root://'	Yes	Trigger definitions are discovered from the root channel.
provider	string	No	Prospective provider id matching {@link AgentInfo.provider}, or omitted for the host default.
workingDirectories	URI[]	No	Prospective {@link AutomationSessionTemplate.workingDirectories}.
sessionConfig	Record<string, unknown>	No	Prospective resolved {@link AutomationSessionTemplate.config}.

Result:

Field	Type	Description
items	AutomationTriggerDefinition[]	Available event trigger definitions.

---

runAutomation

Start a manual run of an automation.

Manual execution is independent of {@link AutomationDefinition.enabled}. The host persists the run before beginning session side effects.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Description
channel	'ahp-automations://'	Manual runs are scoped to the catalogue channel.
automation	URI	Target {@link AutomationState.resource}.
requestId	string	Durable client-generated idempotency key. Retrying with the same key and automation MUST return the original run URI rather than create another run.

Result:

Field	Type	Description
resource	URI	Subscribable ahp-automation-run: URI matching {@link AutomationRunState.resource}.

---

fetchAutomationRuns

Load one older page into a catalogued automation's run-history state.

The response only acknowledges the request. The updated full state arrives through {@link AutomationSetAction | automation/set} on the ahp-automations:// channel, keeping all catalogue subscribers synchronized through the normal action stream.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
channel	'ahp-automations://'	Yes	Run-history loading is scoped to the catalogue channel.
automation	URI	Yes	Target {@link AutomationState.resource}.
cursor	string	No	Cursor previously received as {@link AutomationState.runsNextCursor}. Omit to request the first page not already included by the snapshot.

Result:

(empty object)

---