Async executions

Long-running agent work runs through the async execution queue. Operators and integrators can list, pause, resume, and cancel executions — the same surfaces HumanOS uses when a human must approve before work continues.

Overview

Async executions are first-class jobs with cursor-paginated listing and explicit lifecycle verbs. Pausing is how you hold the line at an approval gate without tearing down the run.

Implementation:

• Public API — apps/api/src/routes/async-executions.ts
• Queue logic — apps/api/src/control-plane/async-jobs.ts

Shipped endpoints

Verb	Path
List	GET /v1/async-executions?status=&agent_id=&limit=&cursor=
Get	GET /v1/async-executions/:id
Pause	POST /v1/async-executions/:id/pause
Resume	POST /v1/async-executions/:id/resume
Cancel	POST /v1/async-executions/:id/cancel
Awaiter status	POST /v1/async-executions/:id/awaiter-status

Statuses include queued, running, paused, completed, failed, cancelled (see route filters in async-executions.ts).

Try it

HITL integration pattern

Typical approval loop:

1. Agent queues async execution for a high-risk step.
2. Runtime or operator pauses with reason referencing the approval ticket.
3. Human responds on POST /v1/approvals/:id/respond or Command Plane escalations.
4. Integrator resumes the same execution id — queue state and provenance stay linked.

See Human-in-the-Loop for approval inbox details.

Cooperative cancel (multi-replica)

Workers honor cooperative cancel flags so pause/cancel propagate across replicas. Operational detail: docs/runbooks/cooperative-cancel-multi-replica.md.

Use cases

• Invoice pipeline — pause before payment rail; resume after /v1/approvals respond.
• Bulk import — cancel queued executions when operator aborts from Console.
• Companion long tasks — surface pause/resume in admin UI tied to execution id.

Security considerations

See also

• Human-in-the-Loop
• Multi-Agent Workflow
• Community: Controlling execution lifecycle
• Runbook: Cooperative cancel multi-replica