Durable jobs and agent capabilities

Deliver the control primitive RFD 1 names: persisted jobs that agents lease over HTTPS polling, with explicit capability advertisement and agent-local policy. The first job type is deliberately harmless, an on-demand inventory collection, so the whole path (request, authorization, lease, execution, events, audit) can ship and harden before any operation that changes a host.

An optional Phoenix Channels connection may later notify agents that work is waiting. It never carries jobs itself, so polling stays the only correctness path.

A capability is a named, versioned operation an agent can perform, written name@version, for example inventory.collect@1. The existing capabilities list on check-ins and agents keeps its meaning. Entries without a version (today’s host.inventory) describe what an agent reports, not jobs it accepts.

Each capability has a risk class fixed by its definition, not by configuration:

An agent advertises a job capability only when it is compiled in and enabled by local policy. Local policy lives in the agent’s configuration file, not in Renga:

A fresh installation enables its observe capabilities, so on-demand collection works without a configuration change; an operator can disable any of them in [jobs]. operate and interactive capabilities are never enabled by default, and Renga cannot enable them remotely. The agent re-checks its policy when it leases a job, so a job created against an advertisement that has since been withdrawn is refused rather than run.

Server-side authorization is independent: an organization setting lists which capabilities may be targeted at all, and a user’s role decides which they may request. A new organization allows every observe capability and no operate or interactive one; owners change the list. Owners and admins may request observe jobs. Requesting operate and interactive jobs needs grants that RFDs 13 and 14 define. Neither side’s check substitutes for the other.

jobs is an organization-scoped table. Each job targets one agent and carries:

States are queued, leased, running, succeeded, failed, cancelled, expired, and uncertain. uncertain means the job may have taken effect but Renga cannot tell; only an imperative job can end there, and only a person or a later reconciliation resolves it. A request that fans out to many agents creates one job per agent sharing a batch_id. Batches have no size cap. Instead, job creation is rate-limited per organization (initially 10,000 jobs a minute), and agents lease their own work, so a large batch spreads across the fleet’s check-in intervals rather than arriving at once.

job_events is append-only and is the job’s history: created, leased, started, progress, output, succeeded, failed, cancel_requested, cancelled, lease_lost, expired, uncertain, and resolved, each with its actor (user, agent, or system), time, and a bounded payload. A trigger rejects updates and deletes on events. The job row is a projection kept in step with its events by one context module that writes both in the same transaction.

Output is bounded per job (initially 64 KiB of events in total), so a job can never become an unbounded log sink. Jobs and their events are kept for 90 days by default; retention is an organization setting.

Polling is the correctness path. All three endpoints use the existing intake authentication (RFD 3) and record contact like any other request.

A server worker, following the existing periodic-worker pattern, sweeps expired leases and records a lease_lost event for each. What happens next depends on how far the job got and its capability’s retry class:

Expired and abandoned work therefore never stays running forever.

Jobs run on their own worker thread with a concurrency of one at first, so they can never delay lease check-ins or scheduled inventory. Each capability has a fixed timeout, and the agent checks for cancellation between steps and on every event post. A job that outlives its timeout is reported as failed, not left running.

Before running a job, the agent writes its job ID to a bounded record in its state directory, and it adds the outcome once the job ends. When the same job is delivered again, after a lost final post or a re-lease, the agent re-sends the recorded outcome instead of running the job again. A job that is recorded as started but has no outcome (the agent crashed mid-run) is reported as uncertain if it is imperative, and otherwise run again under its retry class. The record outlives the longest lease and retry window. It is a guard against duplicates, not the source of truth, which stays in Renga.

inventory.collect@1 runs the normal collection, delivers the observation through the on-disk queue, and returns the observation ID as its result. It proves the path without adding any new power over the host.

A later phase adds a per-installation channel authenticated like the HTTPS API. The server pushes jobs_waiting when it queues a job for a connected agent, and the agent then calls the same lease endpoint. The channel never delivers job content, results, or authority. If the socket drops or is never established, the agent behaves exactly as it would without it.

Streaming interactive output (RFD 13) may later use the channel. That is that RFD’s decision, not a reason to route ordinary jobs through it.

Later RFDs need work that spans several jobs: RFD 14's power operations wait for approval, act, wait for the VM to settle, verify, and hand an uncertain outcome to a person; fan-out batches are tracked until they complete; reconciliation retries and remediation runbooks follow. That coordination is a workflow, and workflows sit above jobs.

Jobs and leases are the fixed execution layer. A workflow engine coordinates jobs but never leases them: agents sit behind NAT and pull work over HTTPS with their intake key (RFD 3), so no engine can call into them, and giving agents credentials for an engine’s own workers would replace Renga’s trust boundary and move the job history out of its tenant-scoped, append-only records.

The adapter boundary is a Renga.Workflows.Engine behaviour that starts a run, delivers job events to it, cancels it, and reports its status. It does not expose an engine’s replay or determinism rules, so capabilities and the job context stay engine-agnostic.

The engine behaviour and its first adapters are designed in their own RFD, once RFD 14's workflow is written against this boundary.

An intake key authenticates an organization, and the installation ID is a correlation identifier, not proof of identity (RFD 3). Anyone holding a key can therefore lease jobs addressed to any installation in that organization. That is acceptable for observe jobs, which reveal no more than the same key could already submit.

It is not acceptable for operate or interactive jobs. Those require per-installation credentials that a leaked shared key cannot impersonate. Designing them (enrollment-time key pairs, mutual TLS, or signed lease requests) is a prerequisite of RFDs 13 and 14 and is out of scope here.

Progress is tracked in the implementation checklist.