Documentation Index
Fetch the complete documentation index at: https://docs.awaithumans.dev/llms.txt
Use this file to discover all available pages before exploring further.
awaithumans ships small surface area on purpose. A few things on the roadmap are big enough that they make better community projects than founder-built features — well-bounded, self-contained, and meaty enough to be a real systems-design exercise.
If one of these resonates, comment on the linked issue with a short proposal (your read on the open questions, a rough split into PR-sized chunks). We’ll iterate, agree on the shape, and merge in stages so a contributor isn’t blocked on one giant PR review.
Local task book — durable resumption without an orchestrator
Status: open · Issue: #64 · Effort: ~1–2 weeks Today direct-modeawait_human() is resumable across agent restarts as long as your runtime re-invokes it (we ship the idempotent-recovery primitive on the server side — see Idempotency). Workflow engines like Temporal and LangGraph automate that re-invocation via their own state management; users not on either currently have to wire up a supervisor or queue themselves.
This feature builds the smallest possible “client-side workflow state” into the SDK: a local SQLite task book that records each in-flight call, plus a decorator + boot-time recovery scan that re-invokes registered handlers automatically. End result: your if decision.approved: block runs after a crash without you having to think about retry loops.
Picking this up means designing the persistence shape (where state lives, how handlers are identified, how args round-trip), the recovery semantics (auto vs. explicit, single-process vs. multi-process), and the cross-language story (Python first, TypeScript follow-up). Full design space and open questions in the issue.
This is exactly the kind of thing that’s a good portfolio piece: real systems-design tradeoffs, a self-contained subsystem you don’t have to refactor the server for, and direct user impact for the long tail of agent builders running on FastAPI / cron / serverless.
Multi-approval primitive — parallel and quorum approvals
Status: open · Issue: #76 · Effort: ~1–2 weeks Today the server is strictly first-writer-wins —assign_to=["alice@team.com", "bob@team.com"] means “first to claim,” not “both must approve.” Sequential approval (lead → manager) already works by chaining two await_human() calls, but parallel and quorum patterns (“two-of-two sign-off,” “any 2 of 3 reviewers approve”) have no first-class primitive. Compliance-heavy domains — fintech sign-offs, healthcare consent, legal review, two-key approvals — need this to be expressible without serializing what should be parallel.
This feature adds an approval_policy knob ("all_of", {"quorum": N}) so a single await_human() call can require multiple humans to approve before the agent unblocks. Server-side: a per-approver completion accumulator, threshold checks, and audit rows for every approver’s decision. Dashboard: per-approver progress indicators. Channels: each assignee notified independently with their own completion state.
Picking this up means weighing real design questions — what does “approved” mean when approvers disagree, do rejections short-circuit, how do per-approver verifiers interact with each other, what’s the right shape for the agent’s return value (aggregate vs. list of decisions). Full policy matrix and open questions in the issue.
This pairs naturally with the Judgment Wall — the case where human accountability matters most is exactly the case where one signature isn’t enough.
Other “help wanted” issues land here as they’re scoped. If you have something in mind that isn’t listed, open a GitHub Discussion — we’d rather talk shape than code review a surprise.
Workforce marketplace
Status: reserved for Phase 3 · Tracking issue: #1 Theassign_to={"marketplace": True, ...} shape is reserved for the post-Phase-2 workforce marketplace, where tasks can be sourced from external reviewers (not just your own team).
Today, calling await_human() with marketplace=True raises MarketplaceNotAvailableError. The error exists so the API surface is forward-compatible — when the marketplace ships, agent code can opt in by flipping a flag, no rewrites.
Why it’s not in v0.1: the open-source core is built around teams that own their reviewers. The marketplace adds a third party (the worker pool), payments, capability matching, and SLAs. That’s a different product surface — it sits on top of the same await_human() primitive but ships separately so the core stays small.
If you’re interested in helping shape the marketplace before it ships, comment on the tracking issue with your use case (what task types, what reviewer capabilities you’d source externally, what your QA story would look like). We’re scoping the first design partner cohort for late-2026.
Versioning & release notes
Every public release is documented at github.com/awaithumans/awaithumans/releases with version highlights, breaking changes, and migration notes. Version pinning recommendation: pin to a minor (awaithumans>=0.1,<0.2) until v1.0 cuts.