feat: an async client, and the lessons a turn was prepared with

[hugo8xx]

Groundwork for a CrewAI package, and useful on its own.

Why

Every agent framework worth integrating is async. A blocking client on an event loop either stalls it or grows a thread pool to hide the stall — so each integration rewrites this transport instead of using one. Our own CrewAI runtime carries a 209-line copy for exactly that reason, and its docstring says so outright.

async with AsyncKhwan(api_key="kwk_live_xxx", core="acme", user_id="Web") as kw:
    turn   = await kw.prepare("what did we decide about billing?")
    answer = await your_model(turn.messages)
    await kw.record(turn, answer)

Behind an optional extra — pip install "khwan[async]" — so a sync user does not pay for httpx, and a missing import names the install that fixes it.

One rule set, not two

The retry policy moved to module level rather than being copied into the new client. A retry rule that drifts between two clients is a bug nobody notices until a duplicate record lands in production. Behaviour is unchanged; one test that reached for the old private method now asserts on the shared rule.

aclose() waits

asyncio keeps only a weak reference to a task, so a fire-and-forget record can be collected before it is sent — losing a turn silently, which is the one failure that mode must not have. Background writes are held and awaited on close, which async with does for you.

Turn.lessons

What synthesis distilled, next to the raw sources. Both were already inside messages, but a caller building its own context — a recall tool, a subagent brief — could not take the rules without replaying the whole prompt.

Tests

httpx driven through a MockTransport, so no network:

✓ policy: shared module-level rules, honoured by both clients
✓ loop: prepare → record, with core and sub-brain headers on both
✓ background: the write lands, and aclose() waits for it
✓ background swallows failure; blocking raises it
✓ retry: 503 retried, and the loop kept running while it waited
✓ missing httpx names the install that fixes it

The two existing suites still pass. Built and twine checked; verified that a
sync-only install (no httpx) imports fine and only fails — clearly — when
AsyncKhwan is actually constructed.

Version → 0.3.0. Not published — that is yours to run.