Skip to main content
Glama

Awaitless

CI PyPI Python

Adaptive durable execution for coding agents.

Run commands through one execution layer. Quick work returns inline; longer or queued work becomes durable across local, SSH, and Slurm. Your workload stays on infrastructure you already own.

Agents submit work. Awaitless owns execution.

Awaitless is the adaptive durable execution layer between coding agents and the compute they use. It gives agents one stable job contract while reusing your local machine, SSH hosts, and Slurm clusters underneath.

简体中文 · Documentation · Benchmarks · PyPI

One job lifecycle across your existing compute

Coding agent → submit work → Awaitless owns the job lifecycle → Local / SSH / Slurm

Durable jobs

Named scarce-resource queues

Completion and recovery

Stable IDs, state, cancellation, bounded logs, and Artifacts survive client disconnects.

Durable FIFO admission prevents too many jobs from entering a named resource at once.

Exit codes and results remain available by Job ID or replayable completion cursor.

Awaitless owns the job lifecycle, not the hardware. It does not discover resources, understand GPU topology, allocate multiple resources, or replace a cluster scheduler. Operators name queues and set fixed concurrency; Slurm continues to handle requests such as --gpus 2 --mem 64G and all physical cluster scheduling.

Awaitless SSH submit, disconnect, resume, and Artifact demo

Related MCP server: script-runner

Your coding agent should write code, not babysit jobs

An agent can write its own run → sleep → check loop. The harder problem is making job identity, disconnect recovery, queue admission, cancellation, and result delivery reliable across long workloads and changing sessions. Without that execution layer, the agent repeatedly pulls the same growing log back into its context:

ssh gpu 'run_benchmark > job.log 2>&1 &'
ssh gpu 'tail -n 200 job.log'  # again...
ssh gpu 'tail -n 200 job.log'  # and again...

Awaitless turns that lifecycle into one adaptive execution call and one result boundary:

awaitless run --json --host gpu --artifact results.json -- ./run_benchmark
# quick: {"state":"succeeded","delivery":"inline","exit_code":0,...}
# longer: {"job_id":"job_019F...","state":"running","delivery":"detached",...}

awaitless wait job_019F... --json
# {"state":"succeeded","exit_code":0,"parsed_results":{...}}

Detached JSON also includes job_state, wait_state, delivery_state, and a ready-to-copy next_command. A client-side wait timeout is not a workload failure: use awaitless wait --last --json for the most recently detached Job, or use the returned command with its stable Job ID. To inspect benchmark lines without reading a large tail, use awaitless logs <job-id> --grep 'PASS|FAIL|median|CV'.

Every run is durable before launch. Finishing within the inline window looks like an ordinary command result; crossing it only detaches the waiter. Interrupt the waiter, close the MCP client, or start a fresh agent session: the Job keeps running and its stable ID recovers the result.

Queue work before a named resource is free

Create a durable FIFO queue once, then submit every command immediately:

awaitless queue create gpu0 --concurrency 1

awaitless submit --queue gpu0 -- python train_a.py
awaitless submit --queue gpu0 -- python train_b.py
awaitless submit --queue gpu0 -- python train_c.py

The first command runs and the others report queued. Each starts automatically when capacity becomes available. This is durable admission control for a named scarce resource: fixed concurrency and FIFO ordering, with no priority or preemption. Awaitless never kills running work to make room for a later job.

Operators can also bind adaptive runs to a queue globally or per host:

[hosts.gpu]
hostname = "gpu.example.com"
queue = "gpu0"

The Agent can then call run without choosing a queue or probing the GPU first.

This queue does not discover resources, understand GPU topology, dynamically allocate devices, issue leases, or combine requests such as two GPUs plus 64 GB of memory. Use Slurm or another scheduler for those responsibilities; Awaitless provides the Agent-facing job lifecycle around that scheduler.

Consume whichever job finishes next

v0.7 adds completions ... --drain --json for consuming a small parallel set in one call without client-side cursor bookkeeping. Long jobs can emit structured heartbeat updates with wait --progress-interval 30s. Use --capture-log PATH for command-owned logs and --resource gpu=0 or --device 0 for explicit exclusive admission; terminal results freeze bounded logs, diagnostics, timing, environment, and a SHA-256 identified snapshot.

Submit independent work up front, keep every Job ID, then wait at one durable completion boundary:

awaitless completions job_A job_B job_C --json
# {"completions":[...],"next_cursor":"cmp_...","active_job_ids":[...]}

awaitless completions job_A job_B job_C --after cmp_... --json

The first call returns already-finished work immediately or blocks until at least one selected Job completes. Process the batch before advancing to next_cursor; reusing an older cursor safely replays the same completion IDs. If the client disappears, a new session can continue from the saved cursor. Awaitless makes continuation results durably available—it does not run the agent's next reasoning step or require a resident notification service.

The v0.8 evidence suite replaces historical call-count demos with four questions: does an Agent choose the protocol correctly, does a Job survive faults without duplicate launch, does Awaitless keep execution-management state out of the reasoning loop, and does adaptive run preserve low friction for short commands? See the v0.8 evidence plan.

v0.8 evidence status

Release evidence is model- and commit-specific. The checked-in suite does not carry numbers from earlier versions or from a different model. Run the v0.8 benchmarks, inspect every raw record, then publish a dated report with model, config hash, git commit, skipped workloads, and all failures in the denominator. The reviewed v0.8 evidence report includes the complete raw records and analysis summaries rather than a selected score.

Try the recovery story in 30 seconds

Linux, Python 3.10+, and Bash are required. Run the built-in demo without a persistent install:

uvx --from awaitless-runner awaitless demo --json

The demo submits two local jobs, terminates their first completion waiter, then uses new clients to consume both bounded results and JSON Artifacts by cursor.

For regular CLI use:

uv tool install awaitless-runner
awaitless doctor --json

pip install awaitless-runner works too.

Give it to your coding agent

Add one stdio MCP server to your client's configuration (adapt the outer key to your client):

{
  "mcpServers": {
    "awaitless": {
      "command": "uvx",
      "args": ["awaitless-runner"]
    }
  }
}

The preferred run tool returns quick commands inline and automatically gives longer or queued work a durable handle. Tasks-aware clients can still use run_job, while low-level clients retain submit_job and wait_for_job. Retrying an expensive submission with the same client_request_id cannot launch a duplicate job. For parallel work, every client can use wait_for_completions regardless of MCP Tasks support. The normative identity, lifecycle, continuation, completion, Artifact, and compatibility contract is Awaitless Agent Job Protocol.

Codex plugin

This repository is also a Codex plugin. Its manifest bundles the Awaitless agent skill with the stdio MCP server, which Codex launches through uvx. Install the repository from a local Codex marketplace, then start a new Codex task so the skill and MCP tools are loaded together.

The plugin requires uvx on PATH; the first MCP launch downloads awaitless-runner from PyPI if it is not already cached.

For direct CLI use, the whole loop is:

awaitless run --json --name tests -- python -m pytest -q
# If delivery is detached, save the returned job_id, then:
awaitless wait <job-id> --json
# Or recover the most recent detached job:
awaitless wait --last --json

One interface, three places to run

Backend

What Awaitless adds

Local

Durable process-group tracking, cancellation, bounded logs, and transactional named queues.

SSH

The same job contract plus queues coordinated on the target host, with no remote daemon.

Slurm

Real sbatch scheduling plus durable Slurm IDs, queue/accounting state, exit codes, logs, cancellation, and Artifacts.

Use --backend, --host, or configuration defaults to switch targets without changing how the agent submits and collects work.

Why not just use a shell or tmux?

Tool

Best at

What the agent still has to build

Blocking shell call

Quick inspection and interactive work

Lifecycle management once an engineering command runs longer than expected.

Shell polling / nohup

Keeping a basic command alive

IDs, status, exit-code recovery, bounded logs, cancellation, deduplication, and result parsing.

tmux

Humans detaching from interactive shells, REPLs, and TUIs

A reliable non-interactive job protocol and wrapper glue.

Awaitless

Agent-run builds, tests, benchmarks, remote jobs, and cluster work

Only the command and, optionally, the JSON Artifact to return.

Awaitless does not replace interactive terminals or Slurm. It gives coding agents durable fixed-concurrency queues on local/SSH machines and delegates cluster resource scheduling to Slurm.

How it works

flowchart LR
    A["Coding agent"] -->|"run"| B["Awaitless MCP / CLI"]
    B --> C[("SQLite job record")]
    C --> Q["Optional queue admission"]
    Q -->|"capacity available"| D{"Backend"}
    D --> L["Local process"]
    D --> S["SSH host"]
    D --> H["Slurm allocation"]
    L --> I{"Finished inline?"}
    S --> I
    H --> I
    I -->|"yes: result"| A
    I -->|"no: durable handle"| A
    A -. "reconnect with stable ID" .-> C
    C --> E["Durable completion cursor"]
    E -->|"state + exit code + bounded logs + Artifacts"| A

There is no Awaitless daemon, HTTP service, or hosted sandbox. Each invocation opens the same SQLite store; submitted runners and scheduler jobs outlive the stdio server that created them. Full logs remain on disk while only bounded tails enter the agent context.

Documentation

License

MIT

Available Tools

11 tools
cancel_jobA

Cancel a durable job without relying on a client-side process handle.

Inputs: job_id (required), grace_seconds. Returns: object

create_queueA

Create an immutable named FIFO queue with a fixed concurrency limit.

Inputs: name (required), concurrency (required). Returns: object

get_job_logsA

Inspect bounded stdout and stderr tails for a known failed or stalled job.

Use after a terminal wait reports failure, timeout, stall, or loss and its bounded result needs focused diagnostics. Do not use as a progress stream, do not repeatedly tail a running healthy Job, and do not use it instead of wait_for_job to learn that work completed.

Inputs: job_id (required), tail, max_bytes. Returns: object

get_job_statusA

Get one immediate, non-waiting state snapshot for a known job_id.

Use only when the caller needs current status now. Do not use this to wait for completion or build a polling loop; use wait_for_job for one Job or wait_for_completions for several. This tool never starts or retries work.

Inputs: job_id (required). Returns: object

list_jobsB

List recent durable jobs, optionally filtered by state or host.

Inputs: host, limit, queue, state. Returns: object

list_queuesA

List named queues and their current queued/active job counts.

Inputs: no named parameters. Returns: object

runA

Default tool for starting one non-interactive command of uncertain duration.

Every command is a durable Job from launch. Commands that finish within the inline timeout return their ordinary bounded result. Longer or queued work returns a detached Job handle without cancelling the workload. Omit queue to use an operator-configured default queue for the selected target.

Do not use this tool for explicit fire-and-forget or batch fan-out; use submit_job. Do not use it when an MCP Tasks handle is explicitly required; use run_job. Do not use it to resume an existing job_id; wait for or inspect that job instead. If a detached handle is returned, keep its job_id and call wait_for_job once when the result is needed rather than polling status.

Inputs: command (required), cwd, env, host, +11 more. Returns: object

run_jobA

MCP Tasks compatibility entry point for explicitly creating a Task handle.

A client declaring io.modelcontextprotocol/tasks receives a Task handle immediately. Older clients block and receive the ordinary final tool result. The stable client_request_id makes a lost creation response safe to retry.

Do not choose this for ordinary command execution: use run. Do not choose it for generic asynchronous submission or fan-out: use submit_job. Only retry a lost Task creation with the same client_request_id and identical arguments.

Inputs: command (required), client_request_id (required), cwd, env, +10 more. Returns: object

submit_jobA

Explicitly submit one asynchronous or fan-out job without waiting.

Omitted backend and host values use the Awaitless configuration defaults. Reuse client_request_id only when retrying the same logical submission; an identical retry returns the original job and a conflicting retry is rejected. A named queue provides FIFO, non-preemptive admission for local or SSH work. Slurm options may contain account, constraint, cpus_per_task, gres, mem, nodes, ntasks, partition, qos, or time. Cluster config supplies defaults.

Do not use this as the default for a single command with uncertain duration; use run. Do not use it for MCP Tasks creation; use run_job. Do not resubmit merely because a client disconnected or a wait timed out: keep the original job_id, or retry the identical logical submission with the same client_request_id if the creation response was lost.

Inputs: command (required), cwd, env, host, +10 more. Returns: object

wait_for_completionsA

Collect durable terminal results across multiple known jobs after a cursor.

Existing completions return immediately. Otherwise the call waits until at least one selected job completes or the optional call-level timeout expires. Reusing the same cursor replays results; advancing to next_cursor consumes the returned batch. A timeout never cancels a managed job.

Submit all independent jobs before calling this tool. Treat delivery as at-least-once: process and deduplicate by completion_id before advancing the cursor. Do not use this for one job, do not poll get_job_status between continuation calls, and never resubmit active jobs after a waiter disconnects.

Inputs: job_ids (required), limit, after_cursor, timeout_seconds. Returns: object

wait_for_jobA

Wait once for a known job_id and consume its durable terminal result.

Returns state, exit code, bounded logs, and declared Artifacts. A client-side timeout or disconnect does not cancel the Job; call this tool again later with the same job_id. Do not use it to start work, do not poll it repeatedly, and use wait_for_completions instead when collecting several independent Jobs.

Inputs: job_id (required), timeout_seconds. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: run for default single command, submit_job for async/fan-out, run_job for MCP Tasks compatibility, wait_for_job for single job waiting, wait_for_completions for multiple jobs, get_job_status for snapshots, get_job_logs for diagnostics, plus cancel/list/queue tools. Descriptions explicitly cross-reference when not to use each, eliminating ambiguity.

    Naming Consistency5/5

    All 11 tools follow a consistent verb_noun snake_case pattern (run, submit_job, wait_for_job, wait_for_completions, get_job_status, get_job_logs, cancel_job, list_jobs, create_queue, list_queues). No style mixing or vague verbs.

    Tool Count5/5

    11 tools cover the job lifecycle and queue management without excess. Each tool has a clear role, and the count is appropriate for a job orchestration server—neither too thin nor bloated.

    Completeness5/5

    The surface covers the full lifecycle: creation (run, submit_job, run_job), waiting and collection (wait_for_job, wait_for_completions), status (get_job_status), logs (get_job_logs), cancel (cancel_job), listing (list_jobs), and queue management (create_queue, list_queues). No obvious gaps for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers