awask 0.1.0__py3-none-any.whl

awask/__init__.py

@@ -0,0 +1,79 @@
+"""awask — your agent asks you a question, and acts on your answer.
+
+A coding agent that needs a human has exactly one channel today: prose in a
+terminal. That channel loses. The important sentence sits in paragraph four of a
+dense block, the owner is in another window, and the run sits idle for forty
+minutes because nobody knew it was waiting.
+
+awask inverts that. The agent writes a small, structured artifact — headline,
+what you need to know, the options, the recommendation, what happens if you say
+nothing — into a durable store. Every surface then renders the SAME card: the
+terminal, a desktop window, a chat DM, a phone.
+
+Three properties are load-bearing, and each is a rule rather than a nicety:
+
+1. **The card is durable and out-of-process.** It lives in ``~/.aither/decisions``,
+   not in a transcript. A card outlives the run that raised it, so closing the
+   laptop does not lose the question, and a process in another terminal can raise
+   one without this process cooperating at all.
+
+2. **A card always states its default.** "What happens if you ignore this" is the
+   field that makes a card safe to ignore. An agent that cannot name a default is
+   not blocked on a decision — it is blocked on doing its own thinking.
+
+3. **Answering closes the loop.** The answer is written back to the raising run's
+   steering mailbox, which its hooks drain. A card a human answers into a void is
+   worse than no card at all, because it reports a resolution that reached nobody.
+
+Zero dependencies — standard library only, on purpose. The store is a directory of
+JSON files, so `pip install awask` is the whole setup: no server, no login, no
+network, and nothing to run before it works.
+
+Quickstart
+----------
+
+    awask ask "Ship the migration now, or hold for review?" \\
+        --summary "Tests pass; the rollback path is untested." \\
+        --fact "312 rows affected" \\
+        --option "ship|Ship it|goes live in ~2 min, rollback unproven" \\
+        --option "hold|Hold|no risk, blocks the release" \\
+        --recommend hold --default hold
+
+    awask list                 # what is waiting
+    awask answer <id> ship     # pick an option
+    awask steer <id> "do X first"   # free-form guidance, card stays open
+
+To make cards fire automatically inside Claude Code — including carrying your
+answer back into the running session — install the hooks::
+
+    awask install-hooks
+
+See ``awask install-hooks --help`` for what it writes and where.
+"""
+
+from __future__ import annotations
+
+from awask.store import (
+    STATUS_ANSWERED,
+    STATUS_CANCELLED,
+    STATUS_EXPIRED,
+    STATUS_OPEN,
+    DecisionCard,
+    DecisionOption,
+    DecisionStore,
+    get_store,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "STATUS_ANSWERED",
+    "STATUS_CANCELLED",
+    "STATUS_EXPIRED",
+    "STATUS_OPEN",
+    "DecisionCard",
+    "DecisionOption",
+    "DecisionStore",
+    "__version__",
+    "get_store",
+]

awask/_doctor.py

@@ -0,0 +1,139 @@
+"""Stack-aware `doctor` for awask.
+
+GENERATED BY gen_aw_doctor.py -- DO NOT EDIT.
+Regenerate it with the generator named above; a hand-edit here is reverted by
+the next run and fails the parity gate.
+
+Why a doctor exists at all: the aw* bricks are designed to COMPOSE, so the
+interesting failures live BETWEEN them. "awask is installed" is not the useful
+fact -- "awask is installed and the thing it pairs with is not" is. This reports
+the whole stack, not just itself.
+
+stdlib only, on purpose: a diagnostic that cannot run because a dependency is
+missing is worthless precisely when you need it.
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+
+#: Frozen from AitherOS/config/ecosystem.yaml at generation time. A shipped
+#: package cannot read the registry, and a doctor that guessed at the family
+#: would go stale in silence. Regenerate to update.
+SELF = 'awask'
+FAMILY = ['awbac', 'awbrowse', 'awdit', 'awevolve', 'awfind', 'awgit', 'awgraph', 'awiam', 'awkno', 'awm', 'awmail', 'awnboard', 'awnest', 'awnet', 'awnode', 'awpredict', 'awprism', 'awreason', 'awrecover', 'awrecurse', 'awrelay', 'awrena', 'awrepl', 'awresearch', 'awrise', 'awrun', 'awseal', 'awshare', 'awtunnel', 'awwall']
+PAIRS_WITH = ['adk', 'awmail', 'awnest', 'awrelay']
+
+#: This brick's OWN config, read out of its source at generation time.
+#: ENV_REQUIRED is `os.environ["X"]` -- absent, that is a KeyError the moment
+#: the line runs. ENV_OPTIONAL is `os.getenv("X")`, which returns None and lets
+#: the caller cope. Only this brick's namespace is listed: reporting the
+#: platform-wide vars it also touches would be noise, and a doctor that floods
+#: gets ignored.
+ENV_REQUIRED = []
+ENV_OPTIONAL = ['AWASK_NOTIFY_COOLDOWN', 'AWASK_NOTIFY_TTL', 'AWASK_STOP_WAIT']
+
+
+def _installed(mod: str) -> "str | None":
+    """Version if importable, else None. Never raises -- a broken sibling must
+    not take the diagnostic down with it."""
+    try:
+        if importlib.util.find_spec(mod) is None:
+            return None
+    except (ImportError, ValueError):
+        return None
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version(mod)
+        except PackageNotFoundError:
+            return "installed"
+    except Exception:
+        return "installed"
+
+
+def report(out=None) -> int:
+    """Print the stack picture. 0 = this brick and its pairs are present."""
+    out = out or sys.stdout
+    print(f"{SELF} doctor", file=out)
+
+    mine = _installed(SELF)
+    print(f"  self       {SELF} {mine or 'NOT IMPORTABLE'}", file=out)
+    shim = shutil.which(SELF)
+    print(f"  command    {shim or 'not on PATH'}", file=out)
+
+    # The stack. Siblings this brick pairs with are called out separately,
+    # because a missing pair is a REASON, while a missing unrelated brick is
+    # just a fact about your machine.
+    missing_pairs, present = [], []
+    for name in FAMILY:
+        v = _installed(name)
+        if v:
+            present.append(name)
+        elif name in PAIRS_WITH:
+            missing_pairs.append(name)
+    print(f"  stack      {len(present)}/{len(FAMILY)} aw* packages installed",
+          file=out)
+    if present:
+        print(f"             {' '.join(sorted(present))}", file=out)
+
+    missing_req = [v for v in ENV_REQUIRED if not os.environ.get(v)]
+    if ENV_REQUIRED or ENV_OPTIONAL:
+        have = sum(1 for v in ENV_REQUIRED + ENV_OPTIONAL if os.environ.get(v))
+        total = len(ENV_REQUIRED) + len(ENV_OPTIONAL)
+        print(f"  config     {have}/{total} of this brick's own vars set", file=out)
+        if missing_req:
+            # Not a preference. os.environ[...] raises the moment it runs.
+            print(f"             MISSING REQUIRED: {' '.join(missing_req)}", file=out)
+
+    local = _local_checks()
+    for line in local:
+        print(f"  {line}", file=out)
+
+    if mine is None:
+        print(f"\nverdict: {SELF} itself is not importable. Reinstall it before "
+              f"anything else here means much.", file=out)
+        return 1
+    if missing_req:
+        print(f"\nverdict: {SELF} is missing required config "
+              f"({', '.join(missing_req)}). Those are read with os.environ[...], "
+              f"so the code path that needs them raises rather than degrades.",
+              file=out)
+        return 1
+    if missing_pairs:
+        print(f"\nverdict: {SELF} works, but pairs with "
+              f"{', '.join(sorted(missing_pairs))} which "
+              f"{'is' if len(missing_pairs) == 1 else 'are'} not installed. "
+              f"That is a capability you are missing, not an error.", file=out)
+        return 0
+    print(f"\nverdict: {SELF} and everything it pairs with are present.", file=out)
+    return 0
+
+
+def _local_checks() -> "list[str]":
+    """Per-brick checks, if this package defines them.
+
+    Kept as a HOOK rather than generated guesses: the generator knows the family
+    from the registry, but it does not know what awask needs at runtime, and a
+    doctor that invented config requirements would be confidently wrong. A
+    package supplies `_doctor_local()` returning display lines; absent, the
+    stack picture above still stands on its own.
+    """
+    try:
+        mod = importlib.import_module(f"{SELF}.doctor_local")
+    except Exception:
+        return []
+    try:
+        return list(mod._doctor_local())
+    except Exception as exc:                       # noqa: BLE001
+        return [f"local     checks raised {type(exc).__name__}: {exc}"]
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    return report()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

awask/agent_tools.py

@@ -0,0 +1,473 @@
+# GENERATED from the decisions module by the awask package generator.
+# Do not edit here: regenerate instead, or the next run reverts you.
+# Edit the SOURCE, then regenerate. An edit made here is reverted by the next
+# regeneration and fails the AWK001 parity gate.
+"""Decision cards as first-class ADK agent tools.
+
+Until now this whole channel was Claude-Code-shaped: a CLI an agent shelled out
+to, plus a Stop hook. An ADK agent — Lyra, Demiurge, a customer's `awdk`
+agent on their own laptop — had no way to reach its owner at all except
+``escalate_to_human``, which in standalone mode wrote a log line and returned
+``"status": "logged_locally"``. Nothing raised, nothing notified, nobody saw it.
+That is the silent-no-op pattern (`security-review-patterns.md` §5) sitting in
+the one tool whose entire job is "get a human".
+
+So the primitives are tools now, and every ADK agent gets them:
+
+* ``ask_human`` — raise a card and (optionally) BLOCK on it, with a deadline and
+  a declared default so the agent is never stuck forever.
+* ``check_human`` — non-blocking: has the owner answered, or typed anything at
+  this card since I last looked?
+* ``list_my_cards`` / ``withdraw_card`` — an agent that resolves its own question
+  must withdraw the card, or it trains the owner to ignore cards.
+
+Two properties are inherited from the store and must not be re-implemented here:
+a card without a stated default is REFUSED, and an answer is delivered back to
+the raising session rather than merely recorded. Both are what make a card safe
+to ignore and worth answering respectively.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+from typing import Any
+
+from awask.store import (
+    CLOSED_STATUSES,
+    DecisionCard,
+    DecisionError,
+    DecisionOption,
+    DecisionSource,
+    console_tab_title,
+    get_store,
+)
+
+#: An agent that blocks forever is a hung agent. Any ``wait_seconds`` above this
+#: is clamped, and the clamp is REPORTED in the result rather than applied
+#: quietly — an agent that thinks it waited an hour and actually waited ten
+#: minutes will draw the wrong conclusion from a timeout.
+MAX_WAIT_SECONDS = float(os.getenv("AITHER_DECISIONS_MAX_WAIT", "3600"))
+
+POLL_SECONDS = 1.0
+
+
+def _agent_name() -> str:
+    return os.getenv("AITHER_AGENT_NAME", "").strip() or "adk-agent"
+
+
+def _session_id() -> str:
+    return (os.getenv("AITHER_SESSION_ID", "").strip()
+            or os.getenv("CLAUDE_SESSION_ID", "").strip())
+
+
+def parse_options(raw: Any) -> list[DecisionOption]:
+    """Accept the three shapes an LLM actually emits, and refuse the rest.
+
+    A tool argument arrives as whatever the model decided to send: a JSON array
+    of objects, a JSON array of ``"key|Label|consequence"`` strings, or one
+    newline-separated string. Guessing badly here produces a card whose options
+    are nonsense while every log line says success — the exact failure the pipe
+    separator was introduced for in the CLI.
+    """
+    if raw in (None, "", []):
+        return []
+    value = raw
+    if isinstance(value, str):
+        text = value.strip()
+        if text.startswith("["):
+            try:
+                value = json.loads(text)
+            except ValueError as exc:
+                raise DecisionError(f"options is not valid JSON: {exc}") from exc
+        else:
+            value = [line for line in text.splitlines() if line.strip()]
+    if isinstance(value, dict):
+        value = [value]
+    if not isinstance(value, list):
+        raise DecisionError(f"options must be a list, got {type(raw).__name__}")
+
+    out: list[DecisionOption] = []
+    for index, entry in enumerate(value, start=1):
+        if isinstance(entry, dict):
+            key = str(entry.get("key") or index).strip()
+            out.append(DecisionOption(
+                key=key,
+                label=str(entry.get("label") or key).strip(),
+                consequence=str(entry.get("consequence") or "").strip(),
+                recommended=bool(entry.get("recommended")),
+            ))
+            continue
+        parts = str(entry).split("|")
+        key = parts[0].strip() or str(index)
+        out.append(DecisionOption(
+            key=key,
+            label=(parts[1].strip() if len(parts) > 1 else key),
+            consequence=(parts[2].strip() if len(parts) > 2 else ""),
+        ))
+    return out
+
+
+def raise_card(
+    title: str,
+    *,
+    summary: str = "",
+    detail: str = "",
+    options: Any = None,
+    facts: Any = None,
+    kind: str = "decision",
+    urgency: str = "normal",
+    recommend: str = "",
+    default: str = "",
+    deadline_seconds: float = 0.0,
+    agent: str = "",
+    session_id: str = "",
+    cwd: str = "",
+) -> DecisionCard:
+    """Raise a card from library code. The synchronous core of every tool here."""
+    from awask.notify import notify
+
+    parsed = parse_options(options)
+    if recommend:
+        wanted = recommend.strip().lower()
+        for option in parsed:
+            if option.key.lower() == wanted:
+                option.recommended = True
+    default_key = (default or "").strip()
+    if not default_key and parsed:
+        default_key = next((o.key for o in parsed if o.recommended), parsed[0].key)
+
+    fact_list: list[str]
+    if isinstance(facts, str):
+        fact_list = [line for line in facts.splitlines() if line.strip()]
+    else:
+        fact_list = [str(f) for f in (facts or []) if str(f).strip()]
+
+    try:
+        from awask import winproc
+
+        session_pid = winproc.resolve_owner_pid(os.getpid())
+    except (ImportError, OSError):
+        session_pid = os.getpid()
+
+    store = get_store()
+    card = store.create(DecisionCard(
+        id="",
+        title=(title or "").strip(),
+        summary=summary.strip(),
+        detail=detail.strip(),
+        kind=kind,
+        urgency=urgency,
+        options=parsed,
+        default_key=default_key,
+        facts=fact_list,
+        source=DecisionSource(
+            session_id=session_id or _session_id(),
+            agent=agent or _agent_name(),
+            cwd=cwd or os.getcwd(),
+            session_pid=session_pid,
+            tab_title=console_tab_title(),
+        ),
+        deadline=(time.time() + deadline_seconds) if deadline_seconds > 0 else None,
+    ))
+    notify(card, store)
+    return card
+
+
+def _card_state(card: DecisionCard) -> dict[str, Any]:
+    chosen = card.option(card.answer or "")
+    return {
+        "id": card.id,
+        "status": card.status,
+        "answer": card.answer,
+        "answer_label": chosen.label if chosen else "",
+        "answer_consequence": chosen.consequence if chosen else "",
+        "answer_note": card.answer_note or "",
+        "owner_said": [n.text for n in card.notes],
+        "title": card.title,
+    }
+
+
+# ── the tools ───────────────────────────────────────────────────────────────────
+
+
+async def ask_human(
+    title: str,
+    summary: str = "",
+    options: str = "",
+    facts: str = "",
+    urgency: str = "normal",
+    default: str = "",
+    recommend: str = "",
+    wait_seconds: float = 0,
+    deadline_seconds: float = 0,
+) -> str:
+    """Ask the owner a question they can answer from a popup, phone or terminal.
+
+    Use this ONLY when all three hold: the readings lead to materially different
+    work, a wrong guess costs real work to undo, and you cannot settle it
+    yourself by reading, measuring or taking the conventional default. Otherwise
+    decide it, say so in one line and keep going — a card is an interruption,
+    and an agent that raises them freely destroys the channel for the one that
+    mattered.
+
+    NEVER for ordinary conversation. A greeting, small talk, or "how should I
+    reply to this message" is not a decision — just answer it yourself in plain
+    text. Raising a card for "the user said hello, how do I respond?" wastes the
+    owner's attention and, if the card is malformed, can burn the whole turn
+    with nothing ever said back to them.
+
+    If a call is REJECTED (this returns `{"ok": false, "error": ...}`), read the
+    error and change what it names — do not resend the same arguments. The
+    loop guard will BLOCK an identical retry after a couple of attempts, and
+    a blocked call still counts as a turn you never answered the user in.
+
+    Args:
+        title: One line, the whole ask. If it needs two, it is two cards.
+        summary: One or two lines of what the owner needs in order to decide.
+        options: The choices. JSON array of {key,label,consequence}, or one
+            "key|Label|what happens if you pick it" per line. A consequence is
+            what makes a card answerable without reading the code.
+        facts: What you MEASURED, one per line — never a guess.
+        urgency: low | normal | high | critical (exact string — not a number).
+        default: The option's KEY (not its label/text) applied if the owner
+            never answers. REQUIRED for a real decision; the store refuses a
+            card without one. If you passed `options` as plain strings with no
+            "|", the key IS that string verbatim — match it exactly.
+        recommend: The option key (not the label) you would pick.
+        wait_seconds: Block until answered, up to this long. 0 returns at once
+            and you poll with check_human.
+        deadline_seconds: Apply the default automatically after this long.
+    """
+    try:
+        card = raise_card(
+            title, summary=summary, options=options, facts=facts, urgency=urgency,
+            default=default, recommend=recommend, deadline_seconds=deadline_seconds,
+        )
+    except DecisionError as exc:
+        # Refusals here are the store enforcing "a card must be decidable".
+        # Reported as a failure the agent can fix, never swallowed.
+        return json.dumps({"ok": False, "error": str(exc)})
+
+    wait = min(float(wait_seconds or 0), MAX_WAIT_SECONDS)
+    clamped = float(wait_seconds or 0) > MAX_WAIT_SECONDS
+    if wait <= 0:
+        return json.dumps({"ok": True, "waited": False, **_card_state(card)})
+
+    store = get_store()
+    deadline = time.time() + wait
+    while time.time() < deadline:
+        await asyncio.sleep(POLL_SECONDS)
+        current = store.get(card.id)
+        if current is None:
+            return json.dumps({"ok": False, "error": "the card disappeared while waiting",
+                               "id": card.id})
+        if current.status in CLOSED_STATUSES or current.notes:
+            return json.dumps({"ok": True, "waited": True, **_card_state(current)})
+
+    return json.dumps({
+        "ok": True, "waited": True, "timed_out": True,
+        "clamped_to_seconds": MAX_WAIT_SECONDS if clamped else None,
+        "guidance": (
+            f"No answer in {int(wait)}s. The card is still open and the owner can "
+            f"answer it later. Proceed on the declared default "
+            f"('{card.default_key}') and say that you did."
+        ),
+        **_card_state(card),
+    })
+
+
+async def check_human(card_id: str = "") -> str:
+    """Has the owner answered, or typed anything at, a card I raised?
+
+    Non-blocking. Call it between steps of long work so a mid-flight steer ("do
+    the other one first") reaches you before you finish the wrong thing.
+
+    Args:
+        card_id: The card to check. Empty checks every card this session raised.
+    """
+    store = get_store()
+    if card_id:
+        try:
+            card = store.get(card_id)
+        except DecisionError as exc:
+            return json.dumps({"ok": False, "error": str(exc)})
+        if card is None:
+            return json.dumps({"ok": False, "error": f"no such card: {card_id}"})
+        return json.dumps({"ok": True, **_card_state(card)})
+
+    session = _session_id()
+    cards = store.list(status=None, session_id=session) if session else store.list()
+    return json.dumps({
+        "ok": True,
+        "cards": [_card_state(c) for c in cards],
+        "open": sum(1 for c in cards if c.is_open),
+    })
+
+
+async def list_my_cards(include_closed: bool = False) -> str:
+    """What is waiting on the owner right now.
+
+    Args:
+        include_closed: Also list answered/expired/withdrawn cards.
+    """
+    store = get_store()
+    cards = store.list(status=None if include_closed else "open")
+    return json.dumps({
+        "ok": True,
+        "count": len(cards),
+        "cards": [
+            {**_card_state(c), "urgency": c.urgency,
+             "age_seconds": round(c.age_seconds, 1),
+             "agent": c.source.agent}
+            for c in cards
+        ],
+    })
+
+
+async def withdraw_card(card_id: str, reason: str = "") -> str:
+    """Withdraw a card you no longer need answered.
+
+    Do this the moment you resolve the question yourself. A card left open after
+    the agent has moved on is how the owner learns that cards can be ignored.
+
+    Args:
+        card_id: The card to withdraw.
+        reason: Why it is no longer needed.
+    """
+    try:
+        card = get_store().cancel(card_id, note=reason or "the agent resolved it")
+    except DecisionError as exc:
+        return json.dumps({"ok": False, "error": str(exc)})
+    return json.dumps({"ok": True, "id": card.id, "status": card.status})
+
+
+#: Registered as the ``decisions`` category by ``adk.builtin_tools``.
+DECISION_TOOLS = [ask_human, check_human, list_my_cards, withdraw_card]
+
+
+def _self_test() -> int:
+    """Prove the option parsing, the refusals and the wait/timeout all behave."""
+    import tempfile
+    from pathlib import Path
+
+    problems: list[str] = []
+
+    def check(name: str, condition: bool, detail: str = "") -> None:
+        print(f"  {'ok  ' if condition else 'FAIL'} {name}{'' if condition else ' ' + detail}")
+        if not condition:
+            problems.append(name)
+
+    parsed = parse_options('[{"key":"a","label":"A","consequence":"c","recommended":true}]')
+    check("parses JSON objects", len(parsed) == 1 and parsed[0].recommended)
+    parsed = parse_options('["a|Keep it|nothing changes","b|Fix it|needs a restart"]')
+    check("parses a JSON array of pipe strings",
+          len(parsed) == 2 and parsed[1].consequence == "needs a restart")
+    parsed = parse_options("a|Keep it|nothing changes\nb|Fix it|needs a restart")
+    check("parses newline-separated pipe strings", len(parsed) == 2)
+    parsed = parse_options(r"repoint|Repoint to C:\Projects\Example|drops the D: dep")
+    check("an option can carry a Windows path",
+          parsed[0].label == r"Repoint to C:\Projects\Example", parsed[0].label)
+    try:
+        parse_options("[not json")
+        check("refuses malformed JSON", False, "it was accepted")
+    except DecisionError:
+        check("refuses malformed JSON", True)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        os.environ["AITHER_DECISIONS_DIR"] = str(Path(tmp) / "cards")
+        os.environ["AITHER_STEER_DIR"] = str(Path(tmp) / "steer")
+        os.environ["AITHER_DECISIONS_POPUP"] = "0"   # no window in a self-test
+        # Never type into a REAL console from a self-test: the temp card still
+        # carries the live session's pid, so with console input armed the
+        # delivery typed "Answer: b ... do it tonight" into the OWNER's
+        # terminal (observed live 2026-08-25).
+        os.environ["AITHER_DECISIONS_CONSOLE_INPUT"] = "0"
+        os.environ["AITHER_SESSION_ID"] = "agent-selftest"
+        import awask.store as store_module
+
+        store_module._STORE = None  # noqa: SLF001 - rebind the singleton at the temp dir
+
+        bare = json.loads(asyncio.run(ask_human("no options at all")))
+        check("refuses an optionless decision card",
+              not bare.get("ok") and "options" in bare.get("error", ""), str(bare))
+
+        raised = json.loads(asyncio.run(ask_human(
+            "Keep the 5090 in the pool while the DGX rebuilds?",
+            summary="Both are defensible and they diverge by days of work.",
+            options="keep|Keep it pooled|throughput holds, DGX rebuild is slower\n"
+                    "drain|Drain the 5090|rebuild finishes tonight, pool loses 40%",
+            facts="pool throughput measured at 41 tok/s\nDGX rebuild ETA 6h",
+            recommend="keep", default="keep",
+        )))
+        check("raises a real card", raised.get("ok") and raised["id"].startswith("d-"),
+              str(raised))
+        check("does not wait when not asked", raised.get("waited") is False)
+
+        card_id = raised["id"]
+        listed = json.loads(asyncio.run(list_my_cards()))
+        check("lists the open card", listed["count"] == 1)
+
+        checked = json.loads(asyncio.run(check_human(card_id)))
+        check("check_human sees it open", checked["status"] == "open")
+
+        # A wait that nobody answers must TIME OUT with guidance, never hang and
+        # never claim an answer.
+        started = time.time()
+        timed = json.loads(asyncio.run(ask_human(
+            "will not be answered", options="a|A|nothing\nb|B|nothing",
+            default="a", wait_seconds=2,
+        )))
+        check("a wait times out rather than hanging", time.time() - started < 20)
+        check("the timeout says what to do next",
+              timed.get("timed_out") and "default" in timed.get("guidance", ""), str(timed))
+
+        # An answer that lands WHILE the agent is waiting must be returned by the
+        # wait itself — not merely recorded for a later poll. That is the whole
+        # difference between a blocking ask and a survey.
+        store = store_module.get_store()
+        subject = "answered while the agent waits"
+
+        async def answer_midflight() -> str:
+            for _ in range(100):
+                await asyncio.sleep(0.2)
+                match = [c for c in store.list() if c.title == subject]
+                if match:
+                    store.answer(match[0].id, "b", note="do it tonight", via="selftest")
+                    return match[0].id
+            return ""
+
+        async def race():
+            answering = asyncio.create_task(answer_midflight())
+            waited = await ask_human(
+                subject, options="a|A|nothing\nb|B|nothing", default="a", wait_seconds=15,
+            )
+            await answering
+            return json.loads(waited)
+
+        raced = asyncio.run(race())
+        check("a blocking wait returns the answer it was waiting for",
+              raced.get("answer") == "b" and not raced.get("timed_out"), str(raced))
+        check("the owner's note comes back with it",
+              raced.get("answer_note") == "do it tonight", str(raced))
+        after = json.loads(asyncio.run(check_human(card_id)))
+        check("an unanswered card is still open afterwards", after["status"] == "open")
+
+        withdrawn = json.loads(asyncio.run(withdraw_card(timed["id"], "resolved it myself")))
+        check("withdrawing works", withdrawn.get("ok") and withdrawn["status"] == "cancelled")
+        asyncio.run(withdraw_card(card_id, "done with it"))
+        gone = json.loads(asyncio.run(list_my_cards()))
+        check("a withdrawn card leaves the open list", gone["count"] == 0, str(gone))
+
+    print()
+    if problems:
+        print(f"agent-tools self-test FAILED - {', '.join(problems)}")
+        return 1
+    print("agent-tools self-test passed - cards raise, wait, time out and withdraw")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_self_test())