feat(coven): read one automation run by id and filter occurrences by automation

[BunsDev]

Part of #80 (Phase 1: getRun(runId) and occurrences(automationId, …)).

The producer landed in OpenCoven/coven#1156 at 552d827e0decebfc96181d31c5504113ac5e5c6f (closes coven#1155):

• coven.automations.run.get.v1 { id } returns { run } with its attempts, read from one snapshot. It uses the same projection as occurrence.get.v1's runs, and returns { run: null } when the run is absent.
• coven.automations.occurrence.list.v1 accepts an optional automationId. It is applied inside each view's query, so limit bounds that automation's rows. For eligible, it is applied inside the scheduler's own eligibility query.

SDK

• automations.getRun(runId, operationOptions?) calls the exact advertised action. It validates the run with the same rules as an occurrence detail's nested runs:

  • exact run id, and the existing runsPayload checks;
  • at most ten attempts;
  • occurrenceId, revision, nullable digest, authority profile and timeout;
  • no cancellation projection.

  The occurrence-run field checks are now one shared function, so getOccurrence and getRun cannot drift.

• automations.occurrences({ view, limit?, automationId? }) sends the trimmed filter.

  • The SDK refuses a filtered page that names any other automation.
  • An empty, blank or non-string filter is rejected before capability or transport I/O.
  • The allowlist in definitionReadBytes admits the new action and the optional field and nothing else.

• Older producers. Both reads are capability-gated. A producer that does not advertise run.get.v1 yields capability_unsupported, never a fallback to another action.

• Also: the README section is updated, CovenAutomationRunResult is exported, the packed API baseline is updated (exactly these additions), and a minor Changeset for @opencoven/coven-client is included.

Tests

tests/coven-automations.spec.ts covers:

• the filtered request, with the trimmed filter sent;
• refusal of a mixed page when filtered, while the same page is accepted unfiltered;
• five malformed filters rejected before transport;
• getRun success and explicit absence;
• eight malformed-run cases: another id, no automation, no occurrence, bad revision, non-string digest or profile, a cancellation projection, and too many attempts;
• no read when the action is not advertised.

Mutation check: disabling the filtered-page check fails its test.

Validation: full pnpm verify passes, 3003 passed and 2 skipped.

This does not change the frozen cd10a3f candidate, and it does not authorize publication.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Transport parity coverage and the README action allowlist still need updating.

Review effort: Lite
Findings: 1

Open (1)

• Update README action allowlist and count for run.get.v1 · New

What changed in this PR

Adds capability-gated run lookup and per-automation occurrence filtering to the Coven SDK.

Changes:

• Adds getRun() with validation and absence handling.
• Adds trimmed automationId filtering and response checks.
• Updates exports, documentation, API baseline, tests, and Changeset.

File	Summary
tests/​coven-automations.spec.ts	Tests filtering, run reads, validation, and capability gating.
packages/​coven/​src/​index.ts	Exports the new run result type.
packages/​coven/​src/​automations.ts	Implements client operations; moderate review note (1 vote) requests transport parity coverage.
packages/​coven/​src/​automations-occurrences.ts	Adds filtering and shared run validation.
packages/​coven/​src/​automations-definitions.ts	Updates request encoding and response decoding.
packages/​coven/​README.md	Documents the new APIs; nit review note (2 votes) requests updating the action allowlist and count.
api-baselines/​coven.d.ts	Updates the public API baseline.
.changeset/​coven-get-run-occurrence-filter.md	Records the package release change.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.