Core concepts

Workers

A worker is a specific running instance of the Looping Louie runtime. It maps an API project to a configured local checkout, advertises its available Harnesses, and claims compatible Pipeline runs. It is not a new kind of Pipeline, Activity, or Activity run.

Provisioning And Heartbeats

The API provisions a worker_id for each configured project. The runtime stores that identity in its project mapping and sends a heartbeat before each project poll. The API permits a Pipeline run claim only when that worker has sent a heartbeat within the active heartbeat window and advertises the run’s frozen Harness.

Provisioning answers which durable worker identity may act in a project. A heartbeat answers whether that identity is currently available. A Pipeline-run lease answers whether that worker may mutate one specific run. They remain independent: a heartbeat does not extend a lease, and a lease expires normally even when a worker stops heartbeating.

The API persists a project-scoped worker identity, recent heartbeat, and its currently observed Harnesses. Every heartbeat replaces the capability set. A worker always advertises louie; it advertises codex_cli when the configured executable and local login checks succeed, and copilot_cli when the configured executable responds to --version. Workers do not advertise models: model policy belongs to the API, while acceptance by an authenticated CLI account is an execution-time result.

sequenceDiagram
    participant Runtime as Runtime worker
    participant API as API scheduler
    participant Run as PipelineRun
    participant Child as ActivityRun

    Runtime->>API: Heartbeat with current Harnesses
    Runtime->>API: List claimable PipelineRuns
    Runtime->>API: Claim run with worker_id and ETag
    API->>Run: Persist worker_id, lease_token, and expiry
    API->>Child: Create or select runtime ActivityRun
    API-->>Runtime: Child run and lease token
    Runtime->>Child: Continue checkpoints using lease
    Runtime->>API: Continue PipelineRun using lease

Heartbeats And Leases

A heartbeat must not extend a Pipeline-run lease. They have different failure semantics.

Pull-Based Claiming

The system uses pull-based scheduling. The API does not select a worker; workers poll for available work and the API admits or rejects each atomic claim.

worker polls
  -> API lists work compatible with that active worker
  -> worker attempts ETag-protected claim
  -> API verifies:
      provisioned and heartbeat fresh
      authorized for project
      capable of the selected runtime Activity
  -> API issues the normal run lease

The runtime owns polling and local execution, while the API remains the scheduler and source of truth.

Capabilities

Capabilities describe current local Harness health, not every Activity type or model that might be accepted. The heartbeat declaration is:

{
  "harnesses": [
    {"kind": "louie", "version": "v1", "config": {}},
    {"kind": "codex_cli", "version": "v1", "config": {}},
    {"kind": "copilot_cli", "version": "v1", "config": {}}
  ]
}

The API compares that declaration with the frozen selected Activity snapshot. It must never treat approval or quiz as worker capabilities: they use the human executor and are not runtime work. A valid Pipeline run remains queued while no active worker advertises its Harness. After, for example, codex login succeeds, a later heartbeat adds codex_cli and normal polling can claim the existing run without user intervention.

Human Activity Runs

Workers do not execute human Activity runs. A dependency-ready human Activity run enters waiting for a person to submit its decision; workers do not claim it. This keeps worker capabilities limited to runtime-executable Harnesses.