automations: feat: add shared automations protocol

[Ulugbek Abdullaev (ulugbekna)]

Summary

Add shared, host-owned Automations to Agent Host Protocol.

The protocol represents:

• durable automation definitions and optimistic revisions;
• manual, schedule, and host-defined event triggers;
• task-level runs with lifecycle, blockers, artifacts, and cancellation;
• one or more linked ordinary AHP sessions;
• durable automation/run provenance on created sessions;
• host capabilities for execution lifetime, creation, schedules, cancellation,
  preview, and retained history;
• idempotent, cutover-safe imports from legacy schedulers.

Multiple clients connected to one authority can share one catalogue, scheduler,
run claim, and history instead of independently scheduling duplicate sessions.

Resource model

ahp-automation:

Owns the reusable definition:

• title and initial user message;
• provider, model, custom agent, working directories, and session config;
• enabled state and trigger collection;
• revision and next occurrence;
• retained run summaries and permitted operations.

ahp-automation-run:

Owns one invocation:

• manual or trigger provenance;
• pending, running, blocked, completed, failed, or cancelled lifecycle;
• blocker summary;
• linked sessions and primary session;
• run-scoped artifacts and permitted operations.

Ordinary session/chat channels remain authoritative for transcripts, tools,
confirmations, and changes.

Triggers and execution

• Schedule triggers use one portable five-field cron expression plus an IANA
  time zone.
• The grammar covers numeric/named fields, wildcards, ranges, lists, steps, and
  Unix day-of-month/day-of-week matching.
• Event triggers use authority-defined types, actions, and schema-defined
  configuration discovered through listAutomationTriggerDefinitions.
• execution.lifetime distinguishes interactive hostLifetime scheduling from
  independently managed authorities.
• runAutomation.requestId is a durable idempotency key.

Cutover-safe imports

createAutomation.import carries a stable source, batch, and item identity.
It may also carry each schedule trigger's next unevaluated source occurrence.

• Imported definitions must be created disabled.
• The host persists supplied occurrences while the definition is disabled.
• After the client removes the legacy scheduler-visible copy and enables the
  host definition, overdue work follows the trigger's misfire policy.
• A host must durably claim a due occurrence with its run record before external
  execution, preventing restart from dispatching the same catch-up twice.

This supports a migration with no interval where both old and new schedulers can
run the same definition.

Commands and synchronization

Adds:

• listAutomations;
• listAutomationTriggerDefinitions;
• createAutomation;
• updateAutomation;
• disposeAutomation;
• runAutomation;
• fetchAutomationRuns;
• previewAutomationSchedule;
• root catalogue notifications;
• definition/run-summary reducer actions;
• run lifecycle/session/artifact reducer actions;
• client-dispatchable run cancellation.

Presence capabilities use optional objects rather than booleans so they can gain
feature-specific details without changing capability detection.

Generated surfaces

The contract is propagated through JSON Schema, reference documentation,
TypeScript, Rust, Go, Swift, Kotlin, reducer fixtures, and round-trip fixtures.
The guide documents authority, cron semantics, imports, revisions, lifecycle,
cancellation, retention, reconciliation, and security.

Deliberate boundaries

• Sharing is within one authority; AHP does not replicate independent hosts.
• Event types remain authority-defined.
• Run-history deletion is not part of this revision.
• Local and managed/cloud execution can be represented by separate authorities.
• Session-list promotion is not modeled here yet; immutable automation
  provenance must not be cleared to change client presentation.

Main merge

Merged current AHP main through d6bf47d2, preserving its scoped
customization-enablement model. Additive generated-client conflicts were
resolved by updating the Rust generator and regenerating every client/schema.

Validation

• npm run generate
• npm run test
• cargo test --workspace under clients/rust
• npm run docs:build
• 100% reducer branch coverage
• change-fragment and release-metadata verification

Companion implementation

Companion VS Code draft PR:
microsoft/vscode#330463

[Connor Peet (connor4312)]

Do we expect these to be the only kinds of actions for automations? If yes, are they actually going to vary by automation or should then just be capabilities at the e.g. host level?

We have ChangesetOperation already which is a richer/more flexible type. When read "AutomationOperation" I initially assume that should be following the same pattern.

[Ulugbek Abdullaev (ulugbekna)]

We're at early stage of automations, so a bit hard to say if we expect other actions in future.

are they actually going to vary by automation or should then just be capabilities at the e.g. host level?

If we in future support automations to come for plugins, I would expect those would need to miss the "update" operation? (or any time when we would like an automation to be un-updatable/un-deletable, eg admin policy-driven automations)

[Connor Peet (connor4312)]

Would we want additional information from the AutomationTriggerDefinition/AutomationTriggerEventDefinition to aid in display here? Since looking them up again required a ListAutomationTriggerDefinitionsParams method call and potentially some enumeration under the hood...

[Connor Peet (connor4312)]

I'm unclear on how this is used. Automations already have their own session.workingDirectories, how is this different?

[Connor Peet (connor4312)]

this does not appear to actually be used

[Connor Peet (connor4312)]

I'm unconvinced we need a whole protocol method for this. I would not be opposed to including a test case for cron scheduling in client libraries in this repo (like action tests, we should have a JSON assertion file and then have each language test against that fixture for consistency)

[Connor Peet (connor4312)]

We have the notion of origin's already for message and chat provenance, I suggest we use the same terminology here

Suggested change

	export type AutomationRunCause =
	export type AutomationRunOrigin =

[Connor Peet (connor4312)]

Same Q on operations here -- is this a capability or open ended operation

[Connor Peet (connor4312)]

1. I don't see any notion of artifact actions in this PR
2. These should be unique already by ContentRef.uri, no need for another ID

[Connor Peet (connor4312)]

It seems in these we kind of reinvent/mirror the SessionInputRequest / SessionStatus but use slightly different terminology/interfaces. Can we consilidate these?