Skip to content

automations: explain waiting and skipped runs - #608

Draft
Connor Peet (connor4312) wants to merge 1 commit into
mainfrom
agents/agent-host-protocol-feedback
Draft

Connor Peet (connor4312) wants to merge 1 commit into
mainfrom
agents/agent-host-protocol-feedback

Conversation

@connor4312

Copy link
Copy Markdown
Member

Implements the "run lifecycle" half of #570. Instead of adding health and skipped to AutomationEntry, the explanation lives on AutomationRunLifecycle. It's already mirrored into AutomationRunSummary, so run history explains itself without new catalogue state.

What changed

  • Waiting runs: AutomationPendingRunLifecycle gains an optional waiting: { reason, message?, retryAt? } field. The host updates it with a pending → pending automationRun/lifecycleChanged. A run that won't retry still transitions to failed.
  • Skipped runs: a new terminal AutomationRunStatus.Skipped and an AutomationSkippedRunLifecycle variant, with { createdAt, completedAt, reason, message?, occurrenceCount? }.
    • A run is either created directly as skipped or moves there from pending (for example when an overlap policy merges it into another run).
    • occurrenceCount lets hosts merge consecutive skips into one record, so a long outage doesn't push real runs out of the bounded runs window.
  • Open reasons: both reason fields are open strings with documented common values, following the MessageAttachmentBase.displayKind pattern, so hosts can report causes specific to them.
    • Waiting reasons: capacity, concurrency, quota, authentication, targetBusy, retry, unavailable.
    • Skip reasons: misfire, overlap, quota.
  • Misfire and run-count rules:
    • Under the skip misfire policy, hosts SHOULD record dropped occurrences as one skipped run. Under runOnce, they MAY.
    • Runs created directly as skipped don't count toward runCount.
  • Supporting updates: the five language generators register the new types; the docs in docs/guide/automations.md and docs/specification/automation-run-channel.md are updated; two new example payloads (099, 100) are added under types/test-cases/round-trips/; and there's a changelog fragment.

Notes for reviewers

  • Breaking change: adding skipped to the @exhaustive AutomationRunStatus means older clients will reject the new value. The automation run channel is still at 1.0 "early development". Folding skips into cancelled would avoid the break but blur what "cancelled" means.
  • Not included: the proposal's per-automation health field (mostly redundant with nextRunAt, runs, and wait reasons) and the filtered skip reason (potentially very high volume, so it doesn't fit as run records).

Validation

npm run generate and npm run test pass, and so do the TypeScript, Go, Rust, Swift, .NET, and Kotlin client test suites (Kotlin run in podman).

Add an optional AutomationPendingRunLifecycle.waiting with a host-reported reason, message, and retry time, and a terminal skipped run status that records trigger occurrences the host dropped (misfire, overlap, quota), coalesced via occurrenceCount. Reasons are open strings with documented common values.

Refs #570

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant