Skip to content

spec · jobspec · v0 · draft

JobSpec OpenAPI v0

The first conformance contract for 12-Factor AgentOps. A small HTTP surface: durable job submission, queue projection, ledger replay. Descriptive, not aspirational.

The 12 factors are the doctrine. JobSpec is the doctrine made executable.

Download openapi.yamlView rawSource
status: draft for commentversion: v0last reviewed: 2026-04-30ref impl: agentopsd

Why this exists

Agent runtimes are fragmenting. Claude, Codex, local workers, future tools — all need the same operational primitives:

  • · accept work durably
  • · return stable job and request ids
  • · expose status without faking success
  • · preserve event history
  • · recover from lost acks
  • · surface degraded state honestly
  • · let consumers read state without owning the underlying .agents storage

What v0 covers

JobSpec v0 covers current agentopsd behavior — nothing aspirational, no placeholder fields.

  • GET /v1/healthDaemon process health
  • GET /v1/readyLedger replay and projection readiness
  • GET /v1/statusQueue state and rebuilt projections
  • GET /v1/eventsDurable ledger replay
  • POST /v1/jobsLocal-token-protected durable job submission
  • POST /v1/jobs/cancelCooperative cancellation for non-terminal jobs
  • /openclaw/v1/*Read-only consumer projections and allowlisted triggers

Submit envelope (intentionally small):

{
  "request_id": "req_20260430_000001",
  "job_id": "job_rpi_000001",
  "job_type": "rpi.run",
  "idempotency_key": "rpi:demo:cycle-1",
  "payload": {
    "goal": "Run a bounded agent workflow"
  }
}

Accepted response (operationally explicit):

{
  "accepted": true,
  "request_id": "req_20260430_000001",
  "job_id": "job_rpi_000001",
  "status": "queued",
  "last_event_id": "evt_job.accepted_job_rpi_000001_000001",
  "projection_status": "current",
  "projection_lag": {
    "last_event_id": "evt_job.accepted_job_rpi_000001_000001",
    "event_count": 1,
    "corrupt_record_count": 0,
    "degraded": false
  },
  "idempotency_key": "rpi:demo:cycle-1"
}

The shape of the JSON isn’t the point. The promise is: a job is not accepted until the durable ledger append succeeds.

What v0 does not cover

Real topics, deliberately omitted. They need workload evidence before becoming public contracts.

  • — cross-host placement
  • — placement.affinity
  • — GPU scheduling
  • — provider capability negotiation
  • — multi-tenant access control
  • — retry policy configuration
  • — a new worker abstraction

Steelman: kernel, not scheduler

The omissions above aren’t gaps to fill later — they’re the boundary the spec publishes on purpose.

Claim

AgentOps isn’t a scheduler. agentopsd stays small on purpose.

Strongest critique

Why not just use Kubernetes, Airflow, or Temporal? Building yet another scheduler is the path every agent framework dies on.

Our answer

agentopsd is the kernel — durable ledger, idempotent submission, projection readiness. Retry policy, DLQ, placement, GPU scheduling are userspace; they belong in your orchestrator. JobSpec v0 publishes the boundary so you run the policy you want against the same conformant kernel.

Evidence: /spec/jobspec/v0/openapi.yaml ("What v0 Does Not Cover" section) + agentops/docs/rfcs/0002-jobspec-openapi-v0.md

Conformance levels

Implement any subset. Partial conformance is fine — be honest about what’s missing.

  1. 1

    Level 1: Observe

    Expose health, readiness, status, and event replay. Runtime need not execute jobs yet — but degraded state must report honestly.

  2. 2

    Level 2: Enqueue

    Accept jobs durably via POST /v1/jobs. Enforce local mutation auth. Recover idempotently by job_id or idempotency_key.

  3. 3

    Level 3: Execute

    Claim, heartbeat, complete, fail, cancel jobs. Expired leases reclaim cleanly without losing history.

  4. 4

    Level 4: Project

    Rebuild read models from the ledger. Serve consumer projections (e.g. OpenClaw) without giving consumers storage ownership.

Why this is 12-Factor AgentOps

Schema isn’t the product. The conformance program is — vendor-agnostic operational behavior for agent runtimes.

  • II. Track Everything in GitDurable, inspectable ledger events
  • III. One Agent, One JobStable ids, bounded payloads, and status
  • V. Validate ExternallyIndependent status and event inspection
  • VI. Lock Progress ForwardAccepted work survives restart and lost acks
  • VIII. Compound KnowledgeProjections feed future sessions and tools
  • XI. Supervise HierarchicallyWorkers claim jobs through leases

Request for comments

Four open questions. Default answer: publish v0 as current behavior, add golden compat tests, let real workload evidence shape v1.

  1. Should unversioned daemon route aliases be part of conformance or only compatibility conveniences?
  2. Should invalid job_type responses be preserved exactly in v0, or should v0 require a cleaner 400 before publication?
  3. Should OpenClaw consumer routes stay in the JobSpec profile, or become a separate consumer conformance profile?
  4. Should placement.affinity wait for JobSpec v1 after the mt-olympus cross-host shim soaks under real traffic?
← All specsRead the doctrine

Source: 12-factor-agentops/docs/reference/jobspec-openapi-v0-rfc.md (Codex draft, 2026-04-30); contract: agentops/docs/contracts/jobspec-openapi-v0.yaml · last synced: 2026-04-30