Step Job (`:job`)

Quick Answer

Use flow/step :job to submit external work into Breyta's jobs control plane,
read durable job state, and await terminal job or batch results from workers
running through breyta jobs worker run.

Use this when the flow should orchestrate external execution but keep the
workflow boundary explicit in the step graph.

Canonical Shape

Core fields:

Field	Type	Required	Notes
`:type`	keyword	Yes	Must be `:job`
`:op`	keyword/string	Yes	One of `:submit`, `:submit-batch`, `:get`, `:get-batch`, `:await`, `:await-batch`

Per-op fields:

Op	Required fields	Optional fields	Notes
`:submit`	`:job-type`	`:payload`, `:metadata`, `:max-attempts`	Create one queued job
`:submit-batch`	`:job-type`, `:jobs`	`:metadata`, `:max-attempts`	Create one queued batch
`:get`	`:job-id`	none	Read the latest state of one job
`:get-batch`	`:batch-id`	`:include-jobs?`, `:limit`	Read the latest state of one batch
`:await`	`:job-id`	`:interval`, `:timeout`, `:max-attempts`, `:backoff`	Wait for one job to reach a terminal state
`:await-batch`	`:batch-id`	`:interval`, `:timeout`, `:max-attempts`, `:backoff`, `:include-jobs?`, `:limit`	Wait for one batch to reach a terminal state

Canonical Examples

Submit and await one job:

(let [queued-job (flow/step :job :submit-review
                   {:op :submit
                    :job-type "agent-review"
                    :payload {:surface "flows-api"}})
      final-job (flow/step :job :await-review
                  {:op :await
                   :job-id (:job-id queued-job)
                   :timeout "5m"})]
  final-job)

Submit and await one batch:

(let [queued-batch (flow/step :job :submit-review-batch
                      {:op :submit-batch
                       :job-type "codex-security-review"
                       :jobs [{:payload {:surface "flows-api"}}
                              {:payload {:surface "runtime"}}]})
      final-batch (flow/step :job :await-review-batch
                     {:op :await-batch
                      :batch-id (:batch-id queued-batch)
                      :timeout "45m"
                      :include-jobs? true})]
  final-batch)

Terminal Statuses

Job terminal statuses:

"succeeded"
"no_changes"
"failed"
"cancelled"
"timed_out"

Batch terminal statuses:

"completed"
"failed"
"partially_failed"
"cancelled"

Worker Contract

The :job step orchestrates the control plane only. Worker setup and result
construction live on the CLI worker side. For the worker contract, artifacts,
and resource attachments, see
Jobs Control Plane.