kiwi-code 0.0.449__tar.gz → 0.0.502__tar.gz

{kiwi_code-0.0.449 → kiwi_code-0.0.502}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kiwi-code
-Version: 0.0.449
+Version: 0.0.502
 Summary: A textual-based terminal user interface application
 Project-URL: Homepage, https://kiwicode.ai
 Author-email: Anurag <anurag@meetkiwi.co>
@@ -19,7 +19,7 @@ Requires-Dist: httpx>=0.25.0
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: psutil>=5.9.0
 Requires-Dist: pydantic>=2.12.5
-Requires-Dist: pykiwiai==0.0.13
+Requires-Dist: pykiwiai==0.0.14
 Requires-Dist: setproctitle>=1.3.0
 Requires-Dist: textual-dev>=1.8.0
 Requires-Dist: textual>=8.1.1

{kiwi_code-0.0.449 → kiwi_code-0.0.502}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "kiwi-code"
-version = "0.0.449"
+version = "0.0.502"
 description = "A textual-based terminal user interface application"
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.11,<4.0"
 dependencies = [
-    "pykiwiai==0.0.13",
+    "pykiwiai==0.0.14",
     "loguru>=0.7.3",
     "pydantic>=2.12.5",
     "textual>=8.1.1",

{kiwi_code-0.0.449 → kiwi_code-0.0.502}/src/kiwi_cli/cli.py

@@ -206,6 +206,17 @@ def runs_get_cmd(id: str = typer.Argument(help="Action run ID")):
 
 # -- top-level --------------------------------------------------------------
 
+@app.command("stats")
+def stats_cmd(
+    range: str = typer.Option(commands.DEFAULT_STATS_RANGE, "--range", help="7d, 30d, 90d or 1y"),
+):
+    """Show run statistics: runs, tokens, spend."""
+    if range not in commands.STATS_RANGES:
+        _print([f"Invalid range: {range}. Valid: {', '.join(commands.STATS_RANGES)}"])
+        raise typer.Exit(2)
+    _print(_run_with_refresh_retry(lambda c: commands.stats(c, range_key=range)))
+
+
 @app.command()
 def login(
     username: str = typer.Option(..., prompt=True, help="Email"),

{kiwi_code-0.0.449 → kiwi_code-0.0.502}/src/kiwi_cli/client.py

@@ -11,8 +11,12 @@ from pykiwiai.api.hello import hello_v1_hello_get
 from pykiwiai.api.auth import (
     return_user_and_session_v1_auth_post,
 )
-from pykiwiai.api.actions import async_run_action_v1_actions_id_async_run_post
+from pykiwiai.api.actions import (
+    answer_human_questions_v1_actions_action_result_id_answer_post,
+    async_run_action_v1_actions_id_async_run_post,
+)
 from pykiwiai.api.action_results import get_action_result_v1_action_results_id_get
+from pykiwiai.models.human_answers_request import HumanAnswersRequest
 from pykiwiai.models.body_return_user_and_session_v1_auth_post import (
     BodyReturnUserAndSessionV1AuthPost,
 )
@@ -21,6 +25,7 @@ from pykiwiai.models.body_async_run_action_v1_actions_id_async_run_post import (
 )
 from pykiwiai.models import DataBlock, Metadata
 from .models import AuthTokens, LoginCredentials
+from .human_questions import WAITING_STATUS, human_event_type, parse_questions
 
 
 class AutobotsClientWrapper:
@@ -545,8 +550,18 @@ class AutobotsClientWrapper:
                     except Exception:
                         pass
 
+                questions = getattr(result, "human_questions", None)
+                result_dict["human_questions"] = parse_questions(
+                    [q.to_dict() for q in questions] if isinstance(questions, list) else None
+                )
+
                 result_dict["id"] = run_id
 
+                # Prompts waiting behind the current turn: with any left, a finished turn
+                # is not the end of the run.
+                queued_inputs = getattr(getattr(result, "queued_inputs", None), "inputs", None)
+                result_dict["queued"] = len(queued_inputs) if isinstance(queued_inputs, list) else 0
+
                 logger.info(f"Parsed result: status={result_dict.get('status')}, has_result={('result' in result_dict)}")
                 logger.info(f"Result structure keys: {result_dict.keys()}")
                 if "result" in result_dict and isinstance(result_dict["result"], dict):
@@ -599,6 +614,10 @@ class AutobotsClientWrapper:
             elif status == "cancelled":
                 return False, result, "Action cancelled"
 
+            # The turn ended asking the user something: done until they answer.
+            elif status == WAITING_STATUS:
+                return True, result, "Action waiting for an answer"
+
             # Still processing (a run being cancelled is not over until it says so)
             elif status in ["processing", "running", "pending", "request_cancel"]:
                 logger.debug(f"Action still {status}, attempt {attempt + 1}/{max_attempts}")
@@ -679,7 +698,12 @@ class AutobotsClientWrapper:
                         try:
                             data = json.loads(data_str)
                             on_message(data)
-                            if stop_on_terminal_status and isinstance(data, dict):
+                            # A question event's `status` is the questions', not the run's.
+                            if (
+                                stop_on_terminal_status
+                                and isinstance(data, dict)
+                                and human_event_type(data) is None
+                            ):
                                 status = str(data.get("status", "") or "").lower()
                                 if status in ["completed", "success", "finished", "failed", "error", "cancelled"]:
                                     return True
@@ -746,6 +770,47 @@ class AutobotsClientWrapper:
             logger.error(f"SSE error: {e}")
             raise
 
+    def answer_human_questions(
+        self, run_id: str, answers: list[dict]
+    ) -> tuple[int, Optional[dict], str]:
+        """Answer questions the run's model asked with `ask_human`.
+
+        `POST /v1/actions/{run_id}/answer`. Every open question must be in `answers`, each
+        answered (`selected` and/or `text`) or skipped (`skip: true`); recorded all or nothing.
+
+        Returns:
+            Tuple of (http_status, body, message). On 200 the body has `question_ids` and
+            `delivered_as`: "turn" when the run had finished and reopened as processing,
+            "instruct" when it was still running. 0 means the request did not complete.
+        """
+        try:
+            if not isinstance(self.client, AuthenticatedClient):
+                return 401, None, "Authentication required"
+            response = answer_human_questions_v1_actions_action_result_id_answer_post.sync_detailed(
+                action_result_id=run_id,
+                client=self.client,
+                body=HumanAnswersRequest.from_dict({"answers": answers}),
+            )
+            code = int(response.status_code)
+            if code == 200 and response.parsed is not None and hasattr(response.parsed, "delivered_as"):
+                body = response.parsed.to_dict()
+                logger.info(f"Answered {len(answers)} question(s) on run {run_id}: {body}")
+                return 200, body, "Answer sent"
+            # Only 200 and 422 are typed; the 400/403/404/409 `detail` is read from the body.
+            try:
+                body = json.loads(response.content or b"null")
+            except ValueError:
+                body = None
+            detail = body.get("detail") if isinstance(body, dict) else None
+            if not isinstance(detail, str):
+                detail = json.dumps(detail) if detail else (response.content or b"").decode("utf-8", "replace")
+            message = f"HTTP {code}" + (f": {detail}" if detail else "")
+            logger.warning(f"Answering questions on run {run_id} failed: {message}")
+            return code, body if isinstance(body, dict) else None, message
+        except Exception as e:
+            logger.error(f"Error answering questions on run {run_id}: {e}")
+            return 0, None, f"Error sending answer: {e}"
+
     def close(self) -> None:
         """Close the client connection."""
         try:

{kiwi_code-0.0.449 → kiwi_code-0.0.502}/src/kiwi_cli/commands.py

@@ -4,19 +4,26 @@ Each command function takes an AuthenticatedClient and keyword args,
 and returns a list of strings (output lines).
 """
 
+import re
+import os
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field
-from typing import Iterator, Optional
+from datetime import datetime, timedelta
+from typing import Callable, Iterator, Optional
 from pykiwiai import AuthenticatedClient
 from pykiwiai.api.actions import (
     list_actions_v1_actions_get,
     get_action_v1_actions_id_get,
     cancel_action_run_v1_actions_action_result_id_cancel_post,
+    instruct_action_run_v1_actions_action_result_id_instruct_post,
 )
 from pykiwiai.api.action_results import (
+    get_action_queue_v1_action_results_action_result_id_queue_get,
+    update_action_queue_v1_action_results_action_result_id_queue_put,
     list_action_result_v1_action_results_get,
     get_action_result_v1_action_results_id_get,
 )
+from pykiwiai.api.run_metrics import get_run_metrics_v1_run_metrics_get
 from pykiwiai.api.subagents import list_subagents_of_run_v1_subagents_runs_parent_action_run_id_get
 from pykiwiai.api.token_usage import get_token_usage_for_run_v1_token_usage_run_id_get
 
@@ -208,6 +215,121 @@ def runs_cancel(client: AuthenticatedClient, *, id: str) -> list[str]:
     return cancel_lines(id, *cancel_run(client, id=id))
 
 
+# steering a run that is in progress
+
+def instruct_run(client: AuthenticatedClient, *, id: str, text: str, urls: Optional[list[str]] = None) -> int:
+    """Hand a run that is processing an instruction to read at its next step. Returns the
+    HTTP status: 202 when taken, 409 when the run is not processing."""
+    from pykiwiai.models.run_instruction import RunInstruction
+
+    resp = instruct_action_run_v1_actions_action_result_id_instruct_post.sync_detailed(
+        action_result_id=id, client=client, body=RunInstruction(text=text, urls=list(urls or [])),
+    )
+    return resp.status_code
+
+
+# the queue: prompts waiting behind the turn in progress
+
+def get_queue(client: AuthenticatedClient, *, id: str) -> tuple[int, list[str], int]:
+    """The prompts queued on a run, oldest first. Returns (HTTP status, prompts, the
+    queue's version, which a write has to quote)."""
+    status, blocks, version = _read_queue(client, id)
+    return status, [_block_text(block) for block in blocks], version
+
+
+def _block_text(block: object) -> str:
+    return str(getattr(block, "text", None) or "")
+
+
+def _read_queue(client: AuthenticatedClient, id: str) -> tuple[int, list, int]:
+    """The queue as the server stores it: (HTTP status, input blocks, version)."""
+    resp = get_action_queue_v1_action_results_action_result_id_queue_get.sync_detailed(
+        action_result_id=id, client=client,
+    )
+    queue = resp.parsed
+    inputs = getattr(queue, "inputs", None)
+    if resp.status_code != 200 or not isinstance(inputs, list):
+        return resp.status_code, [], 0
+    version = getattr(queue, "version_number", 0)
+    return 200, list(inputs), version if isinstance(version, int) else 0
+
+
+@dataclass
+class QueueRemoval:
+    status: int                      # HTTP status of the read or the write that decided it
+    removed: Optional[str] = None    # the prompt taken out, when one was
+    waiting: int = 0                 # how many are queued now
+    moved: bool = False              # the queue is not what the caller was looking at
+
+
+def remove_from_queue(
+    client: AuthenticatedClient, *, id: str, number: int, is_expected: Optional[Callable[[str], bool]] = None,
+) -> QueueRemoval:
+    """Take the prompt at `number` (1 is the next to run) out of a run's queue.
+
+    Positions shift whenever the server starts a queued prompt, so the caller can pass
+    `is_expected` to say what it believes is at that position; if something else is there
+    nothing is removed. The write quotes the version it read, so a change in between is
+    refused by the server rather than removing the wrong prompt."""
+    from pykiwiai.models.queued_inputs import QueuedInputs
+
+    status, blocks, version = _read_queue(client, id)
+    if status != 200:
+        return QueueRemoval(status)
+    if not 1 <= number <= len(blocks):
+        return QueueRemoval(200, waiting=len(blocks))
+    target = _block_text(blocks[number - 1])
+    if is_expected is not None and not is_expected(target):
+        return QueueRemoval(200, waiting=len(blocks), moved=True)
+    # The blocks go back as they came, so each keeps its author and attachments.
+    kept = blocks[: number - 1] + blocks[number:]
+    resp = update_action_queue_v1_action_results_action_result_id_queue_put.sync_detailed(
+        action_result_id=id, client=client, body=QueuedInputs(inputs=kept, version_number=version),
+    )
+    if resp.status_code == 200:
+        return QueueRemoval(200, removed=target, waiting=len(kept))
+    return QueueRemoval(resp.status_code, waiting=len(blocks), moved=resp.status_code == 409)
+
+
+def clear_queue(client: AuthenticatedClient, *, id: str) -> tuple[int, int]:
+    """Drop every prompt queued on a run. Returns (HTTP status, how many were dropped).
+    The turn in progress is not touched. A prompt the server started, or one queued from
+    elsewhere, between the read and the write makes the write a 409; it is read again
+    and retried once."""
+    from pykiwiai.models.queued_inputs import QueuedInputs
+
+    status = 409
+    for _ in range(2):
+        status, prompts, version = get_queue(client, id=id)
+        if status != 200 or not prompts:
+            return status, 0
+        resp = update_action_queue_v1_action_results_action_result_id_queue_put.sync_detailed(
+            action_result_id=id, client=client,
+            body=QueuedInputs(inputs=[], version_number=version),
+        )
+        status = resp.status_code
+        if status == 200:
+            return 200, len(prompts)
+        if status == 404:
+            # The server keeps no queue for a run nothing was ever queued on.
+            return 200, 0
+        if status != 409:
+            break
+    return status, 0
+
+
+def queue_lines(prompts: list[str], *, width: int = 100) -> list[str]:
+    """The queue as numbered lines, one prompt each, cut to fit."""
+    if not prompts:
+        return ["Nothing is queued."]
+    lines = [f"{len(prompts)} queued, in the order they will run:"]
+    for number, prompt in enumerate(prompts, 1):
+        text = " ".join(prompt.split())
+        room = max(10, width - 6)
+        lines.append(f"  {number}. {text if len(text) <= room else text[: room - 1] + '…'}")
+    return lines
+
+
 # token usage
 
 @dataclass
@@ -395,6 +517,245 @@ def token_usage(client: AuthenticatedClient, *, run_id: str) -> list[str]:
     return token_usage_lines(get_token_usage(client, run_id=run_id))
 
 
+# stats (the run metrics dashboard)
+
+#: What `/stats` accepts -> the server's range, how it is named, and the bucket size.
+STATS_RANGES: dict[str, tuple[str, str, str]] = {
+    "7d": ("last_7_days", "Last 7 days", "daily"),
+    "30d": ("last_30_days", "Last 30 days", "daily"),
+    "90d": ("last_90_days", "Last 90 days", "weekly"),
+    "1y": ("last_year", "Last year", "weekly"),
+}
+DEFAULT_STATS_RANGE = "7d"
+
+
+@dataclass
+class RunStats:
+    """The server's run metrics for one time range; `data` is its response as a dict."""
+    status_code: int
+    range_key: str
+    data: dict = field(default_factory=dict)
+
+    @property
+    def label(self) -> str:
+        return STATS_RANGES[self.range_key][1]
+
+    @property
+    def bucket_unit(self) -> str:
+        return "day" if STATS_RANGES[self.range_key][2] == "daily" else "week"
+
+    def runs_per_bucket(self) -> list[int]:
+        """Runs in each day or week of the range, oldest first. The server leaves out a
+        bucket with no runs, so the gaps are put back as zeros."""
+        step = timedelta(days=1 if self.bucket_unit == "day" else 7)
+        try:
+            buckets = sorted(
+                (datetime.fromisoformat(str(b["bucket"])).replace(tzinfo=None), int(b.get("runs") or 0))
+                for b in self.data.get("buckets") or []
+            )
+            start = datetime.fromisoformat(str(self.data["start"])).replace(tzinfo=None)
+            end = datetime.fromisoformat(str(self.data["end"])).replace(tzinfo=None)
+        except (KeyError, TypeError, ValueError):
+            return []
+        if not buckets:
+            return []
+        first = buckets[0][0]
+        before = max(0, int((first - start) / step))
+        series = [0] * (before + max(0, int((end - first) / step)) + 1)
+        for at, runs in buckets:
+            slot = before + round((at - first) / step)
+            if 0 <= slot < len(series):
+                series[slot] += runs
+        return series
+
+
+def local_timezone_name() -> str:
+    """This machine's IANA timezone, so a day in the stats is a day here. UTC when it
+    cannot be told, which is also what the server falls back to for a name it rejects."""
+    name = os.environ.get("TZ", "").lstrip(":")
+    if not name:
+        try:
+            target = os.path.realpath("/etc/localtime")
+            if "zoneinfo/" in target:
+                name = target.split("zoneinfo/", 1)[1]
+        except OSError:
+            name = ""
+    try:
+        from zoneinfo import ZoneInfo
+
+        ZoneInfo(name)
+    except Exception:
+        return "UTC"
+    return name
+
+
+def get_stats(client: AuthenticatedClient, *, range_key: str = DEFAULT_STATS_RANGE) -> RunStats:
+    """Fetch the run metrics dashboard for a time range."""
+    time_range, _, granularity = STATS_RANGES[range_key]
+    resp = get_run_metrics_v1_run_metrics_get.sync_detailed(
+        client=client, time_range=time_range, granularity=granularity, timezone=local_timezone_name(),
+    )
+    if resp.status_code != 200 or resp.parsed is None:
+        return RunStats(status_code=resp.status_code, range_key=range_key)
+    return RunStats(status_code=200, range_key=range_key, data=resp.parsed.to_dict())
+
+
+def fmt_count(n) -> str:
+    """A count short enough for a table: 99.8M, 52.6K, 842."""
+    n = n or 0
+    for limit, suffix in ((1e9, "B"), (1e6, "M"), (1e3, "K")):
+        if abs(n) >= limit:
+            return f"{n / limit:.1f}{suffix}"
+    return f"{n:,.0f}"
+
+
+def fmt_money(v) -> str:
+    if v is None:
+        return "\u2013"
+    if 0 < v < 0.01:
+        return "<$0.01"
+    return f"${v:,.2f}"
+
+
+def fmt_spend(totals: dict) -> str:
+    """Everything a group spent. When some of its runs are unpriced the server gives no
+    total, so the known part is shown with a `+` rather than passed off as the whole."""
+    total = totals.get("total_cost_usd")
+    if total is not None:
+        return fmt_money(total)
+    known = (totals.get("llm_cost_usd") or 0) + (totals.get("media_cost_usd") or 0)
+    return f"{fmt_money(known)}+" if known else "\u2013"
+
+
+def fmt_duration(seconds) -> str:
+    if seconds is None:
+        return "\u2013"
+    seconds = int(round(seconds))
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes, seconds = divmod(seconds, 60)
+    if minutes < 60:
+        return f"{minutes}m {seconds:02d}s"
+    hours, minutes = divmod(minutes, 60)
+    return f"{hours}h {minutes:02d}m"
+
+
+def fmt_pct(v) -> str:
+    return "\u2013" if v is None else f"{v:.0%}"
+
+
+def stats_changes(stats: RunStats) -> list[tuple[str, float]]:
+    """How runs, tokens and spend moved against the period before, as fractions. Empty
+    when that period had no runs, and a figure is left out when it had nothing to compare."""
+    now, before = stats.data.get("totals") or {}, stats.data.get("previous") or {}
+    if not before.get("runs"):
+        return []
+    changes = []
+    for label, key in (("runs", "runs"), ("tokens", "tokens_total"), ("spend", "total_cost_usd")):
+        old, new = before.get(key), now.get(key)
+        if old and new is not None:
+            changes.append((label, (new - old) / old))
+    return changes
+
+
+def top_subjects(stats: RunStats) -> list[dict]:
+    """The busiest workflows first. The server ranks them by estimated hours saved, a
+    column this view does not show, so its order would look arbitrary here."""
+    return sorted(stats.data.get("top_subjects") or [], key=lambda s: -(s.get("runs") or 0))
+
+
+def subject_name(subject: dict) -> str:
+    """A workflow's name; one the server could not name (deleted, say) keeps a short id."""
+    return subject.get("name") or f"(unnamed {str(subject.get('subject_id') or '')[:8]})"
+
+
+TRIGGER_LABELS = {"api": "API", "batch": "Batch", "scheduled": "Scheduled", "webhook": "Webhook"}
+
+
+def trigger_label(trigger: Optional[str]) -> str:
+    """A run's trigger as the web dashboard names it. Runs the server could not attribute
+    to a trigger come back as `unknown`."""
+    key = (trigger or "unknown").lower()
+    return TRIGGER_LABELS.get(key) or " ".join(w.capitalize() for w in re.split(r"[_\s-]+", key) if w)
+
+
+def trigger_rows(stats: RunStats) -> list[tuple[str, str, str, str, str]]:
+    """What started the runs, largest share first: label, runs, share, tokens, spend. A run
+    spawned by another run is its own row, so what subagents cost is read off directly."""
+    rows = sorted(stats.data.get("by_trigger") or [], key=lambda x: x.get("runs") or 0, reverse=True)
+    total = sum(x.get("runs") or 0 for x in rows)
+    return [
+        (
+            trigger_label(x.get("trigger")), f"{x.get('runs') or 0:,}", fmt_pct((x.get("runs") or 0) / total),
+            fmt_count(x.get("tokens_total")), fmt_spend(x),
+        )
+        for x in rows if x.get("runs")
+    ]
+
+
+def stats_lines(stats: RunStats) -> list[str]:
+    """The run metrics dashboard as plain output lines."""
+    if stats.status_code != 200:
+        return [f"Error: HTTP {stats.status_code}"]
+    data = stats.data
+    t = data.get("totals") or {}
+    if not t.get("runs"):
+        return [f"No runs in the {stats.label.lower()}."]
+
+    lines = [
+        f"{stats.label} ({data.get('scope', '')}, {data.get('timezone', '')})",
+        "",
+        f"Runs          : {t['runs']:,} ({t.get('succeeded', 0):,} succeeded, {t.get('failed', 0):,} failed, "
+        f"{t.get('cancelled', 0):,} cancelled)",
+        f"Success rate  : {fmt_pct(t.get('success_rate'))}",
+        f"Tokens        : {fmt_count(t.get('tokens_total'))} (input {fmt_count(t.get('tokens_input'))}, "
+        f"cached {fmt_count(t.get('tokens_cached'))}, cache write {fmt_count(t.get('tokens_cache_write'))}, "
+        f"output {fmt_count(t.get('tokens_output'))})",
+        f"Cache hit     : {fmt_pct(t.get('cache_hit_rate'))}",
+        f"Spend         : {fmt_spend(t)} (LLM {fmt_money(t.get('llm_cost_usd'))}, media {fmt_money(t.get('media_cost_usd'))})",
+        f"Duration      : {fmt_duration(t.get('duration_p50'))} median, {fmt_duration(t.get('duration_p95'))} slowest 5%",
+    ]
+    if t.get("hours_saved"):
+        lines.append(f"Hours saved   : {t['hours_saved']:,.1f} (estimated)")
+    changes = stats_changes(stats)
+    if changes:
+        lines.append("Vs previous   : " + ", ".join(f"{label} {change:+.0%}" for label, change in changes))
+
+    subjects = top_subjects(stats)
+    if subjects:
+        header = f"{'Workflow':<28} {'Runs':>6} {'Success':>8} {'Tokens':>9} {'Spend':>10}"
+        lines += ["", header, "-" * len(header)]
+        for s in subjects:
+            name = subject_name(s)
+            lines.append(
+                f"{name[:28]:<28} {s.get('runs', 0):>6,} {fmt_pct(s.get('success_rate')):>8} "
+                f"{fmt_count(s.get('tokens_total')):>9} {fmt_spend(s):>10}"
+            )
+    models = data.get("by_model") or []
+    if models:
+        header = f"{'Model':<28} {'Runs':>6} {'Tokens':>9} {'Spend':>10}"
+        lines += ["", header, "-" * len(header)]
+        for m in models:
+            lines.append(
+                f"{(m.get('model') or '(unknown)')[:28]:<28} {m.get('runs', 0):>6,} "
+                f"{fmt_count(m.get('tokens_total')):>9} {fmt_spend(m):>10}"
+            )
+    triggers = trigger_rows(stats)
+    if triggers:
+        header = f"{'Started by':<28} {'Runs':>6} {'Share':>8} {'Tokens':>9} {'Spend':>10}"
+        lines += ["", header, "-" * len(header)]
+        lines += [f"{label[:28]:<28} {runs:>6} {share:>8} {tokens:>9} {spend:>10}" for label, runs, share, tokens, spend in triggers]
+    errors = data.get("top_errors") or []
+    if errors:
+        lines += ["", "Failures      : " + ", ".join(f"{x.get('error_class') or 'Unclassified'} {x.get('runs', 0):,}" for x in errors)]
+    return lines
+
+
+def stats(client: AuthenticatedClient, *, range_key: str = DEFAULT_STATS_RANGE) -> list[str]:
+    """Run metrics for a time range. Returns output lines."""
+    return stats_lines(get_stats(client, range_key=range_key))
+
+
 # Command dispatcher — parses "/command args" from TUI input
 
 HELP_TEXT = """\
@@ -404,6 +765,11 @@ Session:
   /new                  Start new conversation
   /status               Show current action & run
   /cancel [run_id]      Cancel a running run (default: current run)
+  /queue <prompt>       Run a prompt after the current turn finishes
+  /queue list           Show the prompts waiting to run
+  /queue remove <n>     Drop one waiting prompt, by its number in /queue list
+  /queue clear          Drop every prompt waiting to run
+  /stats [7d|30d|90d|1y] Show run statistics: runs, tokens, spend (default: 7d)
   /usage [run_id]       Show token usage for a run and its subagents (default: current run)
 
 Files: