{
  "markdown": "# Awaitless\n\n<!-- mcp-name: io.github.xpluspro/awaitless -->\n\n[![CI](https://github.com/xpluspro/Awaitless/actions/workflows/ci.yml/badge.svg)](https://github.com/xpluspro/Awaitless/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/awaitless-runner.svg)](https://pypi.org/project/awaitless-runner/)\n[![Python](https://img.shields.io/pypi/pyversions/awaitless-runner.svg)](https://pypi.org/project/awaitless-runner/)\n\n**Adaptive durable execution for coding agents.**\n\nRun commands through one execution layer. Quick work returns inline; longer or\nqueued work becomes durable across local, SSH, and Slurm. Your workload stays\non infrastructure you already own.\n\n> **Agents submit work. Awaitless owns execution.**\n\nAwaitless is the adaptive durable execution layer between coding agents and the\ncompute they use. It gives agents one stable job contract while reusing your local\nmachine, SSH hosts, and Slurm clusters underneath.\n\n[简体中文](README.zh-CN.md) · [Documentation](docs/README.md) ·\n[Benchmarks](metric/README.md) · [PyPI](https://pypi.org/project/awaitless-runner/)\n\n## One job lifecycle across your existing compute\n\n```text\nCoding agent → submit work → Awaitless owns the job lifecycle → Local / SSH / Slurm\n```\n\n| Durable jobs | Named scarce-resource queues | Completion and recovery |\n|---|---|---|\n| 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. |\n\nAwaitless owns the **job lifecycle**, not the hardware. It does not discover\nresources, understand GPU topology, allocate multiple resources, or replace a\ncluster scheduler. Operators name queues and set fixed concurrency; Slurm\ncontinues to handle requests such as `--gpus 2 --mem 64G` and all physical\ncluster scheduling.\n\n![Awaitless SSH submit, disconnect, resume, and Artifact demo](https://raw.githubusercontent.com/xpluspro/Awaitless/main/assets/awaitless-demo.gif)\n\n## Your coding agent should write code, not babysit jobs\n\nAn agent can write its own `run → sleep → check` loop. The harder problem is\nmaking job identity, disconnect recovery, queue admission, cancellation, and\nresult delivery reliable across long workloads and changing sessions. Without\nthat execution layer, the agent repeatedly pulls the same growing log back into\nits context:\n\n```bash\nssh gpu 'run_benchmark > job.log 2>&1 &'\nssh gpu 'tail -n 200 job.log'  # again...\nssh gpu 'tail -n 200 job.log'  # and again...\n```\n\nAwaitless turns that lifecycle into one adaptive execution call and one result\nboundary:\n\n```bash\nawaitless run --json --host gpu --artifact results.json -- ./run_benchmark\n# quick: {\"state\":\"succeeded\",\"delivery\":\"inline\",\"exit_code\":0,...}\n# longer: {\"job_id\":\"job_019F...\",\"state\":\"running\",\"delivery\":\"detached\",...}\n\nawaitless wait job_019F... --json\n# {\"state\":\"succeeded\",\"exit_code\":0,\"parsed_results\":{...}}\n```\n\nDetached JSON also includes `job_state`, `wait_state`, `delivery_state`, and a\nready-to-copy `next_command`. A client-side wait timeout is not a workload\nfailure: use `awaitless wait --last --json` for the most recently detached Job,\nor use the returned command with its stable Job ID. To inspect benchmark lines\nwithout reading a large tail, use `awaitless logs <job-id> --grep 'PASS|FAIL|median|CV'`.\n\nEvery `run` is durable before launch. Finishing within the inline window looks\nlike an ordinary command result; crossing it only detaches the waiter. Interrupt\nthe waiter, close the MCP client, or start a fresh agent session: the Job keeps\nrunning and its stable ID recovers the result.\n\n## Queue work before a named resource is free\n\nCreate a durable FIFO queue once, then submit every command immediately:\n\n```bash\nawaitless queue create gpu0 --concurrency 1\n\nawaitless submit --queue gpu0 -- python train_a.py\nawaitless submit --queue gpu0 -- python train_b.py\nawaitless submit --queue gpu0 -- python train_c.py\n```\n\nThe first command runs and the others report `queued`. Each starts automatically\nwhen capacity becomes available. This is durable admission control for a named\nscarce resource: fixed concurrency and FIFO ordering, with no priority or\npreemption. Awaitless never kills running work to make room for a later job.\n\nOperators can also bind adaptive runs to a queue globally or per host:\n\n```toml\n[hosts.gpu]\nhostname = \"gpu.example.com\"\nqueue = \"gpu0\"\n```\n\nThe Agent can then call `run` without choosing a queue or probing the GPU first.\n\nThis queue does not discover resources, understand GPU topology, dynamically\nallocate devices, issue leases, or combine requests such as two GPUs plus 64 GB\nof memory. Use Slurm or another scheduler for those responsibilities; Awaitless\nprovides the Agent-facing job lifecycle around that scheduler.\n\n## Consume whichever job finishes next\n\nv0.7 adds `completions ... --drain --json` for consuming a small parallel set\nin one call without client-side cursor bookkeeping. Long jobs can emit\nstructured heartbeat updates with `wait --progress-interval 30s`. Use\n`--capture-log PATH` for command-owned logs and `--resource gpu=0` or\n`--device 0` for explicit exclusive admission; terminal results freeze bounded\nlogs, diagnostics, timing, environment, and a SHA-256 identified snapshot.\n\nSubmit independent work up front, keep every Job ID, then wait at one durable\ncompletion boundary:\n\n```bash\nawaitless completions job_A job_B job_C --json\n# {\"completions\":[...],\"next_cursor\":\"cmp_...\",\"active_job_ids\":[...]}\n\nawaitless completions job_A job_B job_C --after cmp_... --json\n```\n\nThe first call returns already-finished work immediately or blocks until at\nleast one selected Job completes. Process the batch before advancing to\n`next_cursor`; reusing an older cursor safely replays the same completion IDs.\nIf the client disappears, a new session can continue from the saved cursor.\nAwaitless makes continuation results durably available—it does not run the\nagent's next reasoning step or require a resident notification service.\n\nThe v0.8 evidence suite replaces historical call-count demos with four\nquestions: does an Agent choose the protocol correctly, does a Job survive\nfaults without duplicate launch, does Awaitless keep execution-management state\nout of the reasoning loop, and does adaptive `run` preserve low friction for\nshort commands? See the [v0.8 evidence plan](metric/README.md#v08-evidence-suite).\n\n## v0.8 evidence status\n\nRelease evidence is model- and commit-specific. The checked-in suite does not\ncarry numbers from earlier versions or from a different model. Run the v0.8\nbenchmarks, inspect every raw record, then publish a dated report with model,\nconfig hash, git commit, skipped workloads, and all failures in the denominator.\nThe reviewed [v0.8 evidence report](metric/results/v0.8-report.md) includes the\ncomplete raw records and analysis summaries rather than a selected score.\n\n## Try the recovery story in 30 seconds\n\nLinux, Python 3.10+, and Bash are required. Run the built-in demo without a\npersistent install:\n\n```bash\nuvx --from awaitless-runner awaitless demo --json\n```\n\nThe demo submits two local jobs, terminates their first completion waiter, then\nuses new clients to consume both bounded results and JSON Artifacts by cursor.\n\nFor regular CLI use:\n\n```bash\nuv tool install awaitless-runner\nawaitless doctor --json\n```\n\n`pip install awaitless-runner` works too.\n\n## Give it to your coding agent\n\nAdd one stdio MCP server to your client's configuration (adapt the outer key to\nyour client):\n\n```json\n{\n  \"mcpServers\": {\n    \"awaitless\": {\n      \"command\": \"uvx\",\n      \"args\": [\"awaitless-runner\"]\n    }\n  }\n}\n```\n\nThe preferred `run` tool returns quick commands inline and automatically gives\nlonger or queued work a durable handle. Tasks-aware clients can still use\n`run_job`, while low-level clients retain `submit_job` and `wait_for_job`.\nRetrying an expensive submission with the same\n`client_request_id` cannot launch a duplicate job. For parallel work, every\nclient can use `wait_for_completions` regardless of MCP Tasks support.\nThe normative identity, lifecycle, continuation, completion, Artifact, and\ncompatibility contract is [Awaitless Agent Job Protocol](JOB_PROTOCOL.md).\n\n### Codex plugin\n\nThis repository is also a Codex plugin. Its manifest bundles the Awaitless agent\nskill with the stdio MCP server, which Codex launches through `uvx`. Install the\nrepository from a local Codex marketplace, then start a new Codex task so the\nskill and MCP tools are loaded together.\n\nThe plugin requires `uvx` on `PATH`; the first MCP launch downloads\n`awaitless-runner` from PyPI if it is not already cached.\n\nFor direct CLI use, the whole loop is:\n\n```bash\nawaitless run --json --name tests -- python -m pytest -q\n# If delivery is detached, save the returned job_id, then:\nawaitless wait <job-id> --json\n# Or recover the most recent detached job:\nawaitless wait --last --json\n```\n\n## One interface, three places to run\n\n| Backend | What Awaitless adds |\n|---|---|\n| **Local** | Durable process-group tracking, cancellation, bounded logs, and transactional named queues. |\n| **SSH** | The same job contract plus queues coordinated on the target host, with no remote daemon. |\n| **Slurm** | Real `sbatch` scheduling plus durable Slurm IDs, queue/accounting state, exit codes, logs, cancellation, and Artifacts. |\n\nUse `--backend`, `--host`, or configuration defaults to switch targets without\nchanging how the agent submits and collects work.\n\n## Why not just use a shell or tmux?\n\n| Tool | Best at | What the agent still has to build |\n|---|---|---|\n| Blocking shell call | Quick inspection and interactive work | Lifecycle management once an engineering command runs longer than expected. |\n| Shell polling / `nohup` | Keeping a basic command alive | IDs, status, exit-code recovery, bounded logs, cancellation, deduplication, and result parsing. |\n| `tmux` | Humans detaching from interactive shells, REPLs, and TUIs | A reliable non-interactive job protocol and wrapper glue. |\n| **Awaitless** | Agent-run builds, tests, benchmarks, remote jobs, and cluster work | Only the command and, optionally, the JSON Artifact to return. |\n\nAwaitless does not replace interactive terminals or Slurm. It gives coding\nagents durable fixed-concurrency queues on local/SSH machines and delegates\ncluster resource scheduling to Slurm.\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[\"Coding agent\"] -->|\"run\"| B[\"Awaitless MCP / CLI\"]\n    B --> C[(\"SQLite job record\")]\n    C --> Q[\"Optional queue admission\"]\n    Q -->|\"capacity available\"| D{\"Backend\"}\n    D --> L[\"Local process\"]\n    D --> S[\"SSH host\"]\n    D --> H[\"Slurm allocation\"]\n    L --> I{\"Finished inline?\"}\n    S --> I\n    H --> I\n    I -->|\"yes: result\"| A\n    I -->|\"no: durable handle\"| A\n    A -. \"reconnect with stable ID\" .-> C\n    C --> E[\"Durable completion cursor\"]\n    E -->|\"state + exit code + bounded logs + Artifacts\"| A\n```\n\nThere is no Awaitless daemon, HTTP service, or hosted sandbox. Each invocation\nopens the same SQLite store; submitted runners and scheduler jobs outlive the\nstdio server that created them. Full logs remain on disk while only bounded\ntails enter the agent context.\n\n## Documentation\n\n- [Documentation index](docs/README.md)\n- [Product positioning and evolution principles](docs/PRD.zh-CN.md)\n- [v0.6 adaptive run](docs/v0.6.zh-CN.md)\n- [v0.7 immutable completion snapshots](docs/v0.7.zh-CN.md)\n- [v0.5 durable completion feed](docs/v0.5.zh-CN.md)\n- [CLI, configuration, SSH, Slurm, persistence, Artifacts, and troubleshooting](docs/REFERENCE.md)\n- [MCP Tasks protocol and compatibility](docs/MCP_TASKS.md)\n- [Benchmark definitions, methodology, and interpretation](metric/README.md)\n- [Real MCP → Slurm disconnect evidence](docs/REFERENCE.md#real-mcp--slurm-disconnect-evidence)\n- [Architecture and design rationale](docs/REFERENCE.md#architecture-and-runtime-model)\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 12008,
  "sha": "41adca7520c27bda214596d73e25b96377114e9039cb51efa39b4d5b93df3c67",
  "repo_slug": "xpluspro/awaitless",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xpluspro_awaitless_fd5a9101/readme"
}