codi-api-agent 0.3.1__py3-none-any.whl

api_agent/ui.py

@@ -0,0 +1,918 @@
+"""Streamlit UI for the API Agent — packaged entry point.
+
+Launch it with the console command after installing:  ``api-agent``
+or directly:  ``streamlit run -m api_agent.ui`` (or ``python -m api_agent`` → prints how).
+
+Load an OpenAPI/Swagger, GraphQL, or Postman/RAML/API-Blueprint spec in the sidebar, then ask
+questions — the agent picks the right operations, calls them (read-only), and answers with
+citations and a faithfulness check.
+"""
+from __future__ import annotations
+
+import os
+import queue
+import re
+import threading
+
+try:  # work both installed and from a source checkout
+    import api_agent  # noqa: F401
+except ModuleNotFoundError:  # pragma: no cover
+    import sys
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import streamlit as st
+import streamlit.components.v1 as components
+
+from api_agent import log as _log
+from api_agent.agent import Agent, _tool_category
+from api_agent.catalog import Catalog
+from api_agent.config import Config
+from api_agent.graphql_loader import load_catalog
+from api_agent.openapi_loader import build_catalog, merge_catalogs, spec_label
+from api_agent.schemas import CACHED_INPUT_DISCOUNT, AgentResult, unpriced_models
+from api_agent.supervisor import Supervisor
+
+st.set_page_config(page_title="API Agent", page_icon="🛰️", layout="wide")
+
+ENV = Config.from_env()
+
+# ---- Console step trail -------------------------------------------------------------------- #
+# Re-apply the log level AFTER Config.from_env(), which is what runs `load_dotenv()`. Import order
+# makes this necessary rather than tidy: `api_agent.agent` imports `metrics` → `log` before it
+# imports `config`, so `log` was already configured at the pre-dotenv level and a `LOG_LEVEL` set
+# in `.env` was silently ignored — the cap stayed 800 and the level stayed INFO with nothing said.
+#
+#   LOG_LEVEL=DEBUG        every step's FULL input and output (LLM message lists, replies,
+#                          tool args, tool results, routing, verdicts)
+#   LOG_PAYLOAD_CHARS=0    no truncation (default 800 cuts exactly the long payloads you want)
+#   LOG_RAW_ROWS=1         log warehouse rows BEFORE PII redaction (see sql_loader._redact_row)
+#   LOG_FILE=agent.log     also tee to a file
+_log.setup(force=True)
+_UILOG = _log.get_logger("api_agent.ui")
+_UILOG.info("UI start — log level=%s payload_chars=%s raw_rows=%s (streamlit prints to THIS console)",
+            os.getenv("LOG_LEVEL", "INFO").upper(), _log.payload_chars(),
+            os.getenv("LOG_RAW_ROWS", "0"))
+# No spec auto-loads by default (a fresh install has none) — set DEFAULT_SPEC to a URL/path to
+# auto-load one. Example: DEFAULT_SPEC="https://petstore3.swagger.io/api/v3/openapi.json".
+DEFAULT_SPEC = os.getenv("DEFAULT_SPEC", "").strip()
+
+
+def _catalog_for_trace():
+    """The active catalog, for turning an operation name into its business category. Best-effort:
+    the trace must render even before a catalog is loaded."""
+    try:
+        return st.session_state.get("catalog")
+    except Exception:                      # pragma: no cover - outside a Streamlit run
+        return None
+
+
+def _md(text: str) -> str:
+    """Prepare answer text for `st.markdown`. Streamlit renders `$…$` as LaTeX math, so currency
+    like `$5,606,794.94` breaks the whole line (bold turns into `∗∗`). Escape every unescaped `$`
+    so amounts render literally."""
+    return re.sub(r"(?<!\\)\$", r"\\$", text or "")
+
+
+# Categorical slots 1-3 of the validated palette, in fixed order. Three is the ceiling that clears
+# every colour-vision-deficiency pair test in BOTH modes; a fourth puts yellow and orange together
+# and stops clearing. Assigned by POSITION in `spec.series`, never cycled, so a series keeps its
+# colour when a sibling drops out of the result.
+_SERIES_LIGHT = ["#2a78d6", "#eb6834", "#1baf7a"]
+_SERIES_DARK = ["#3987e5", "#d95926", "#199e70"]
+
+
+def _render_trend_chart(result: AgentResult) -> None:
+    """Draw the ONE result worth drawing, when there is one. Otherwise draw nothing.
+
+    Prose is weakest at exactly one shape: a trend. Measured — asked for "the Dentrix production
+    trend for the last 12 months through June 2026" the agent wrote an accurate paragraph naming
+    the first month, the last, the low, the high, the total and the year-over-year change: six
+    numbers standing in for twelve, and the reader still cannot see the shape.
+
+    `chart.chart_spec` owns the decision and refuses by default — truncated rows are never drawn,
+    because a line over a partial series shows a shape the data does not have and, unlike a table,
+    carries no visible sign that anything is missing.
+    """
+    try:
+        import altair as alt
+        import pandas as pd
+    except ModuleNotFoundError:            # charting is a nicety; never break the answer over it
+        return
+    from api_agent.chart import chart_spec, humanize
+
+    spec = next((s for e in (result.evidence or [])
+                 if (s := chart_spec(getattr(e, "rows", None),
+                                     truncated=getattr(e, "rows_truncated", False),
+                                     label=getattr(e, "tool", "")))), None)
+    if not spec:
+        return
+
+    dark = str(st.get_option("theme.base") or "").lower() == "dark"
+    palette = _SERIES_DARK if dark else _SERIES_LIGHT
+    ink, muted = ("#ffffff", "#c3c2b7") if dark else ("#0b0b0b", "#52514e")
+    names = [humanize(c) for c in spec.series]
+    df = pd.DataFrame(spec.points)
+    df["series"] = df["series"].map(humanize)
+    order = [n for n in names]             # x stays in the order the warehouse returned
+
+    colour = alt.Color("series:N", title=None,
+                       scale=alt.Scale(domain=order, range=palette[:len(order)]),
+                       legend=alt.Legend(orient="top", direction="horizontal", labelColor=muted,
+                                         symbolStrokeWidth=3, symbolType="stroke"))
+    base = alt.Chart(df).encode(
+        # `sort=None` keeps the periods in the order the rows arrived. Altair sorts a nominal axis
+        # alphabetically by default, which turns "Jul 2025 → Jun 2026" into "Apr, Aug, Dec, …" — a
+        # chart that looks fine and is pure noise.
+        x=alt.X("period:N", title=None, sort=None,
+                axis=alt.Axis(labelColor=muted, labelAngle=-45, domainColor=muted,
+                              tickColor=muted, grid=False)),
+        y=alt.Y("value:Q", title=None,
+                # A trend chart is read for SHAPE, so the axis is not forced to zero — but it is
+                # never clipped so tightly that a 2% wobble looks like a collapse.
+                scale=alt.Scale(zero=False, nice=True, padding=12),
+                axis=alt.Axis(labelColor=muted, format="~s", domain=False, ticks=False,
+                              gridColor=muted, gridOpacity=0.18, gridDash=[])),
+        color=colour,
+    )
+    hover = alt.selection_point(on="mouseover", nearest=True, fields=["period"], empty=False)
+    chart = (
+        base.mark_line(strokeWidth=2, point=alt.OverlayMarkDef(size=64, filled=True))
+        + base.mark_point(size=90, opacity=0).add_params(hover)
+        + base.mark_rule(color=muted, strokeWidth=1).encode(
+            opacity=alt.condition(hover, alt.value(0.35), alt.value(0)),
+            tooltip=[alt.Tooltip("period:N", title="Period"),
+                     alt.Tooltip("series:N", title="Series"),
+                     alt.Tooltip("value:Q", title="Value", format=",.2f")])
+    ).properties(height=280).configure_view(strokeWidth=0).configure_axis(labelFontSize=11)
+
+    st.altair_chart(chart, use_container_width=True)
+    # The table view is not optional garnish: two of the three light-mode hues sit below 3:1
+    # against the surface, and the palette's relief rule requires visible labels or a table
+    # wherever that holds. It also keeps every series the scale guard dropped reachable.
+    with st.expander("🔢 The numbers behind this chart"):
+        st.dataframe(df.pivot(index="period", columns="series", values="value").reindex(
+            df["period"].drop_duplicates()), use_container_width=True)
+
+
+def render_result(result: AgentResult) -> None:
+    """Render an answer's supporting detail: faithfulness, timing, sources, trace."""
+    # The sidebar may override per-model prices, and that `config` is built further down this
+    # module. Resolve it defensively rather than depending on definition order — falling back to
+    # the environment's table keeps costs priced even if this is ever called earlier.
+    pricing = getattr(globals().get("config") or ENV, "model_pricing", {})
+    cols = st.columns(3)
+    fh = result.faithfulness
+    if fh and fh.judged:
+        verdict = "grounded" if fh.supported else "check claims"
+        cols[0].caption(f"🔎 Evaluation: **{fh.score:.0%} grounded** ({verdict})")
+    elif not getattr(globals().get("config") or ENV, "judge_enabled", True):
+        # A deliberate cost decision, not a failure. The full note (what still ran) is in the
+        # tooltip so the caption doesn't turn into a paragraph.
+        cols[0].caption("🔎 Evaluation: **scoring off** for this session",
+                        help=(fh.notes if fh else ""))
+    elif fh:
+        cols[0].caption(f"🔎 Evaluation: not judged — {fh.notes}")
+    if result.cached:
+        cols[1].caption(f"⚡ **{result.elapsed_s * 1000:.1f} ms** (cached)")
+    else:
+        cols[1].caption(f"⏱️ **{result.elapsed_s:.2f} s**")
+    u = result.usage
+    if u and u.total_tokens:
+        # Combined across every model (generator + writer + judge + router/cache), each priced at
+        # its OWN rate via Usage.by_model — the pipeline runs three different models, so a single
+        # blended rate would misprice it.
+        cost = f" · 💲 **${result.cost_usd:.4f}**" if result.cost_usd is not None else ""
+        split = (f" (in **{u.prompt_tokens:,}** · out **{u.completion_tokens:,}**)"
+                 if (u.prompt_tokens or u.completion_tokens) else "")
+        cols[2].caption(f"🔢 **{u.total_tokens:,}** tokens{split}{cost}")
+        # An UNPRICED model contributes $0 to the figure above, so the total reads as
+        # authoritative while being quietly too low. Say so rather than let it pass as free.
+        if missing := unpriced_models(u, pricing):
+            cols[2].caption(f"⚠️ no price set for `{', '.join(missing)}` — the $ above "
+                            "excludes it")
+        if len(u.by_model or {}) > 1:
+            with st.expander("💲 Cost by model"):
+                st.caption("Each model is priced at its own rate. The pipeline deliberately runs "
+                           "a cheaper model for routing/execution/judging and a stronger one for "
+                           "the user-facing writing, so these will differ.")
+                for m, (p, c) in sorted(u.by_model.items(),
+                                        key=lambda kv: -(kv[1][0] + kv[1][1])):
+                    rate = pricing.get(m) or pricing.get(m.split("/")[-1])
+                    cached = (u.cached_by_model or {}).get(m, 0)
+                    if rate:
+                        billed = max(p - cached, 0) + cached * CACHED_INPUT_DISCOUNT
+                        line = f"**${billed / 1e6 * rate[0] + c / 1e6 * rate[1]:.4f}**"
+                    else:
+                        line = "*not priced*"
+                    st.markdown(f"- `{m}` — in {p:,} · out {c:,}"
+                                + (f" · {cached:,} cached" if cached else "") + f" → {line}")
+
+    if getattr(result, "answered_by", ""):
+        st.caption(f"🤖 Answered by the **{result.answered_by}** agent")
+
+    if result.routed_tools and result.route_method not in ("", "all (small catalog)"):
+        chosen = ", ".join(f"`{t}`" for t in result.routed_tools)
+        st.caption(f"🧭 Router ({result.route_method}) selected {len(result.routed_tools)} op(s): {chosen}")
+
+    if result.needs_keys:
+        hosts = ", ".join(f"`{h}`" for h in result.needs_keys)
+        st.warning(
+            f"🔑 This API needs authentication for {hosts}. Re-load the spec with the "
+            f"**Auth** fields filled in (header name + value), then ask again."
+        )
+
+    # Evaluation — a multi-dimensional verdict (grounding + responsiveness), not just one opaque
+    # number, so it's clear WHY the status is what it is.
+    if fh and fh.judged:
+        #head = "looks good ✅" if (fh.supported and fh.answers_question) else "see caveats ⚠️"
+        with st.expander(f"🔎 Evaluation"):
+            def _dim(ok, label_ok, label_bad):
+                return f"{'✅' if ok else '⚠️'} {label_ok if ok else label_bad}"
+            st.markdown(
+                f"- **Grounding:** {fh.score:.0%} of the answer's claims are backed by the fetched data\n"
+                f"- **Addresses the question:** {_dim(fh.answers_question, 'yes', 'not fully')}")
+            if fh.notes:
+                st.markdown(f"**Validator's justification:** {fh.notes}")
+            if fh.unsupported_claims:
+                st.markdown(
+                    f"**{len(fh.unsupported_claims)} claim(s) not grounded in the data** "
+                    "— this is what pulled the score below 100%:"
+                )
+                for u in fh.unsupported_claims:
+                    st.markdown(f"- {u}")
+            elif fh.supported:
+                st.markdown("✅ Every claim in the answer was grounded in the fetched data.")
+
+    # Five-dimension quality scorecard (mirrors the eval rubric D1–D5).
+    rb = getattr(result, "rubric", None)
+    if rb:
+        _RB_EMOJI = {"correctness": "🎯", "completeness": "🧩", "groundedness": "🔗",
+                     "safety": "🛡️", "communication": "💬", "traceability": "🧭"}
+        with st.expander(f"🏅 Answer scorecard — **{rb.overall}/5**"):
+            # The ladder takes the FIRST rule that matches, so five green dimensions beside one
+            # amber leave the reader guessing which one set the headline. Say it outright.
+            if getattr(rb, "overall_reason", ""):
+                st.markdown(f"**{rb.overall}/5** — {_md(rb.overall_reason)}")
+            st.caption(
+                "Five quality dimensions (same rubric as the offline eval). Groundedness and "
+                "communication are LLM-judged; safety is a deterministic scan; correctness and "
+                "completeness are derived from grounding, data-sufficiency and responsiveness "
+                "(there's no reference answer at answer time, so those two mean 'consistent with "
+                "the fetched data and addresses the question')."
+                + (" **Traceability** appears on advisory answers only: it checks deterministically "
+                   "that every recommendation has an owner and a timeframe, that its figures trace "
+                   "back to the analysis, and that no forward dollar/percent outcome was invented."
+                   if rb.traceability is not None else ""))
+            for d in rb.dims():
+                icon = "✅" if d.passed else "⚠️"
+                line = (f"{_RB_EMOJI.get(d.name, '•')} **{d.name.title()}** — {icon} "
+                        f"{d.score:.0%} · *{d.method}*")
+                if d.note:
+                    line += f"  \n&nbsp;&nbsp;&nbsp;{_md(d.note)}"
+                st.markdown(line)
+
+    # Both panels below are DEBUG surfaces — they name operations, arguments and sources.
+    # DEBUG_PANELS=0 removes them entirely for production.
+    if ENV.debug_panels and (result.citations or getattr(result, "source_note", "")):
+        with st.expander(f"📎 Sources ({len(result.citations)})", expanded=True):
+            # Which system answered belongs HERE, not in the prose: the answer must never name the
+            # machinery, but the reader must still be able to find out what it drew on.
+            if note := getattr(result, "source_note", ""):
+                st.caption(_md(note))
+            for c in result.citations:
+                # Same reasoning as the trace panel below: a debugging surface, gated off in
+                # production, so it carries the real source and operation.
+                st.markdown(f"- [{c.source}]({c.source}) · via `{c.locator}`"
+                            f"  ·  *{_tool_category(c.locator, _catalog_for_trace())}*")
+
+    if ENV.debug_panels and result.trace:
+        with st.expander("🧭 How this answer was produced"):
+            is_doc = result.route_method == "doc"
+            mode = ("Looked the operation(s) up in the loaded spec — nothing was called."
+                    if is_doc else
+                    "Picked the relevant operation(s) and called them; here's each step.")
+            st.caption(f"**{len(result.trace)} step(s).** {mode}")
+            for i, t in enumerate(result.trace, 1):
+                src = str(t.source or "")
+                src_md = f"[{src}]({src})" if src.startswith("http") else f"`{src}`"
+                if is_doc:
+                    st.markdown(f"{i}. 📖 **{t.detail}** — {src_md}  \n   *(read from the spec, not executed)*")
+                else:
+                    # FULL DETAIL, deliberately. This panel is a DEBUGGING surface, not a
+                    # customer one — it is gated off in production (`debug_panels`), and the
+                    # customer-visible live step trail shows only the category. Understanding why
+                    # an answer came out the way it did needs the operation, its exact arguments
+                    # and the source it hit; a category alone cannot be debugged.
+                    icon = "✅" if t.ok else "⚠️"
+                    line = f"{i}. {icon} Called **`{t.tool}`**"
+                    line += f"  ·  *{_tool_category(t.tool, _catalog_for_trace())}*"
+                    if t.args:
+                        line += f" with `{t.args}`"
+                    if t.detail:
+                        line += f" → returned {t.detail}"
+                    if not t.ok and t.error:
+                        line += f" → **{t.error}**"
+                    st.markdown(line)
+                    if src:
+                        st.caption(f"   ↳ {src_md}")
+                    if t.error:
+                        st.caption(f"   ↳ ⚠️ {t.error}")
+
+
+def greeting_message() -> str:
+    """Welcome shown at the start of every session/chat (and after clearing)."""
+    return (
+        "👋 **Hi — I'm your API agent.**\n\n"
+        "Add a spec in the sidebar (**OpenAPI/Swagger, GraphQL, or a Postman/RAML/API-Blueprint "
+        "collection** — I auto-convert those), then ask me anything about it in plain language. "
+        "I pick the right operations, call them, and answer with **citations** and a "
+        "**faithfulness check**. I'm **read-only** and I never make data up.\n\n"
+        "**No spec yet? Try one of these free, no-auth demos** (Sidebar → *Spec URL* → *Add spec*):\n"
+        "- **GraphQL** — URL `https://countries.trevorblades.com/`, tick **GraphQL API** → ask "
+        "*\"list the continents\"* or *\"capital and currency of Japan?\"*\n"
+        "- **Postman → auto-converted** — URL "
+        "`https://raw.githubusercontent.com/aisabel/SWAPI-PostmanTest/master/SWAPI.postman_collection.json`, "
+        "Base URL `https://swapi.dev/api` → ask *\"list the Star Wars characters\"*\n\n"
+        "What would you like to find out?"
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Specs: load one or more specs (each with its own auth) into one catalog.
+# --------------------------------------------------------------------------- #
+if "specs" not in st.session_state:
+    st.session_state.specs = []
+    if DEFAULT_SPEC:
+        try:
+            st.session_state.specs.append(
+                {"label": spec_label(DEFAULT_SPEC), "source": DEFAULT_SPEC,
+                 "catalog": load_catalog(DEFAULT_SPEC)}
+            )
+        except Exception as e:
+            st.sidebar.error(f"Failed to load DEFAULT_SPEC: {e}")
+
+st.sidebar.title("⚙️ Configuration")
+st.sidebar.subheader("📚 Load an API")
+st.sidebar.caption("Add one or more sources — a **spec** (OpenAPI/Swagger, GraphQL, or Postman/RAML/"
+                   "API Blueprint) or a prose **API reference doc** (endpoints extracted for you to "
+                   "review). The agent can use operations from any of them in a single answer.")
+src_kind = st.sidebar.radio(
+    "Source type", ["API spec", "API reference doc", "Postgres warehouse"], horizontal=True,
+    help="A structured spec, a prose reference document (endpoints extracted deterministically "
+    "for review), or a Postgres warehouse whose schema functions become read-only tools.")
+_is_doc = src_kind == "API reference doc"
+_is_sql = src_kind == "Postgres warehouse"
+
+if _is_sql:
+    # ---- SQL (warehouse) backend: schema functions -> read-only tools ----
+    sql_dsn = st.sidebar.text_input(
+        "Postgres DSN", ENV.sql_dsn, type="password",
+        help="e.g. postgresql://agent_ro:pass@localhost:7432/arq-dev — use a SELECT-only role; "
+        "connections are additionally forced read-only with a statement timeout.")
+    sql_schema = st.sidebar.text_input("Schema", ENV.sql_schema)
+    sql_prefix = st.sidebar.text_input(
+        "Function prefix", ENV.sql_fn_prefix,
+        help="Only functions matching this prefix are exposed as tools (the whitelist).")
+    sql_label = st.sidebar.text_input("Label (optional)", "", key="sql_label")
+    if st.sidebar.button("➕ Connect warehouse"):
+        if not sql_dsn.strip():
+            st.sidebar.warning("Enter a Postgres DSN first.")
+        else:
+            try:
+                from api_agent.sql_loader import load_sql_catalog
+                loaded = load_sql_catalog(
+                    sql_dsn.strip(), schema=sql_schema.strip() or "gold",
+                    fn_prefix=sql_prefix.strip(), timeout=ENV.http_timeout,
+                    statement_timeout_ms=ENV.sql_timeout * 1000,
+                    profile_rows=ENV.profile_rows)
+                if not loaded.tools:
+                    st.sidebar.error(
+                        f"No functions matching `{sql_prefix}*` found in schema `{sql_schema}`.")
+                else:
+                    st.session_state.specs.append(
+                        {"label": sql_label.strip() or f"{sql_schema} (warehouse)",
+                         "source": f"sql://{sql_schema}", "catalog": loaded})
+                    st.sidebar.success(f"Connected — **{len(loaded.tools)}** warehouse functions.")
+            except Exception as e:
+                st.sidebar.error(f"Failed — {e}")
+    spec_src, spec_files = "", []  # the spec/doc widgets below don't apply to a warehouse
+
+if not _is_sql:
+    spec_src = st.sidebar.text_input("URL or file path", "")
+    spec_files = st.sidebar.file_uploader(
+        "…or upload file(s)",
+        type=(["md", "markdown", "txt"] if _is_doc
+              else ["json", "yaml", "yml", "graphql", "gql", "sdl", "raml", "apib"]),
+        accept_multiple_files=True,
+        help=("Prose reference doc(s) (.md/.txt) — combined into one." if _is_doc
+              else "OpenAPI/Swagger, GraphQL SDL, or Postman/RAML/API-Blueprint. Each file loads as a "
+              "separate source.")) or []
+    with st.sidebar.expander("Auth for this source (optional)"):
+        auth_header = st.text_input("Header name", "Authorization", help="e.g. Authorization, Cookie, or X-API-Key")
+        auth_value = st.text_input(
+            "Header value", "", type="password",
+            help="e.g. 'Bearer <token>', 'adminhtml=<cookie>', or your API key")
+        label_in = st.text_input("Label (optional)", "", help="Short name shown in the trace; defaults to the file/URL name")
+
+if not _is_doc and not _is_sql:
+    # ---- Structured spec (OpenAPI / GraphQL / Postman / RAML / API Blueprint) ----
+    max_ops = st.sidebar.number_input(
+        "Max operations to load", 10, 5000, ENV.max_operations, step=50,
+        help="Large specs (e.g. GitHub has 600+) load up to this many ops; the router narrows them per query.")
+    _spec_name = (spec_src or (spec_files[0].name if spec_files else "")).lower().rstrip("/")
+    is_graphql = st.sidebar.checkbox(
+        "GraphQL API", value=_spec_name.endswith((".graphql", ".gql", ".sdl")),
+        help="Treat the source as GraphQL: introspect an endpoint URL, or load a local .graphql/.sdl "
+        "schema (then set the endpoint below). Only query fields become callable — mutations stay read-only.")
+    gql_endpoint = st.sidebar.text_input(
+        "GraphQL endpoint (for SDL files)", "",
+        help="Server URL to query when the source is a .graphql/.sdl file. Blank if the source is already the endpoint URL.",
+    ) if is_graphql else ""
+    base_url_in = "" if is_graphql else st.sidebar.text_input(
+        "Base URL (for Postman/RAML/Blueprint)", "",
+        help="The server to call for a converted spec, e.g. https://swapi.dev/api. Ignored for OpenAPI "
+        "specs that already declare their server. (Conversion needs Node/npx on PATH.)")
+    if base_url_in and not base_url_in.lower().startswith(("http://", "https://")):
+        base_url_in = "https://" + base_url_in.strip()   # add a scheme if the user omitted it
+    if st.sidebar.button("➕ Add spec"):
+        # Each source loads as its own entry: the URL/path (if given) + every uploaded file.
+        import tempfile
+        jobs = []  # (display_name, path_or_url, is_temp_file)
+        if spec_src.strip():
+            jobs.append((spec_src.strip(), spec_src.strip(), False))
+        for f in spec_files:
+            ext = os.path.splitext(f.name)[1] or ".txt"  # keep extension so format sniffing works
+            fd, tmp = tempfile.mkstemp(suffix=ext)
+            with os.fdopen(fd, "wb") as fh:
+                fh.write(f.getvalue())
+            jobs.append((f.name, tmp, True))
+        if not jobs:
+            st.sidebar.warning("Enter a spec URL/path or upload spec file(s) first.")
+        else:
+            single, added_ops, added, errors = len(jobs) == 1, 0, 0, []
+            for display, src, is_tmp in jobs:
+                try:
+                    loaded = load_catalog(
+                        src, graphql=is_graphql, endpoint=gql_endpoint or None,
+                        base_url=base_url_in or None, max_operations=int(max_ops),
+                        auth_header=auth_header or None, auth_value=auth_value or None)
+                    if not loaded.tools:
+                        errors.append(f"{display}: no callable read operations")
+                    else:
+                        st.session_state.specs.append(
+                            {"label": (label_in.strip() if single else "") or spec_label(display),
+                             "source": display, "catalog": loaded})
+                        added_ops += len(loaded.tools)
+                        added += 1
+                except Exception as e:
+                    errors.append(f"{display}: {e}")
+                finally:
+                    if is_tmp:
+                        try:
+                            os.remove(src)
+                        except OSError:
+                            pass
+            if added:
+                st.sidebar.success(f"Added **{added_ops}** operations from **{added}** source(s).")
+            for err in errors:
+                st.sidebar.error(f"Failed — {err}")
+elif _is_doc:
+    # ---- Prose API reference doc: extract (structural, free) → review → load ----
+    base_url_in = st.sidebar.text_input(
+        "Base URL for these endpoints", "",
+        help="Server to call, e.g. https://api.example.com. Overrides any URL found in the doc.")
+    doc_use_llm = st.sidebar.checkbox(
+        "🤖 Also use the LLM to enrich params (slower, costs tokens)", value=False,
+        help="Endpoints are extracted from the doc's method+path lines for free. Tick to also have the "
+        "LLM add param types/enums, or to handle a prose-only doc. Uses your .env model.")
+    if st.session_state.get("doc_loaded_note"):
+        st.sidebar.success(st.session_state["doc_loaded_note"])
+    if st.sidebar.button("🔍 Extract endpoints"):
+        from api_agent.doc_extract import build_doc_openapi, fetch_doc_text, looks_graphql_heavy
+        from api_agent.llm import LLMClient
+        try:
+            parts = []
+            if spec_src.strip():
+                parts.append(fetch_doc_text(spec_src.strip(), timeout=ENV.http_timeout))
+            for f in spec_files:
+                parts.append(f.getvalue().decode("utf-8", "ignore"))
+            text = "\n\n".join(p for p in parts if p and p.strip())  # combine all docs into one
+            if not text.strip():
+                st.sidebar.warning("Provide a doc URL/path or upload doc file(s) first.")
+            elif doc_use_llm and Config.from_env().problems():
+                st.sidebar.warning("LLM enrichment needs LLM_BASE_URL + LLM_API_KEY in .env — or untick it.")
+            else:
+                st.session_state.pop("doc_loaded_note", None)
+                prog = st.sidebar.progress(0.0, text="Extracting…")
+                _cfg = Config.from_env()
+                st.session_state.doc_draft = build_doc_openapi(
+                    text, llm=LLMClient(_cfg) if doc_use_llm else None,
+                    model=_cfg.generator_model, use_llm=doc_use_llm,
+                    progress=lambda d, t: prog.progress(d / t, text=f"Enriching chunk {d}/{t}…"))
+                prog.empty()
+                heavy, n = looks_graphql_heavy(text)
+                st.session_state.doc_gql_note = (
+                    f"ℹ️ This doc also describes ~{n} **GraphQL** operations (e.g. `useGetTasksQuery`); "
+                    "those have no REST path — load the **GraphQL API** for them.") if heavy else None
+        except Exception as e:
+            st.sidebar.error(f"Extraction failed: {e}")
+
+    draft = st.session_state.get("doc_draft")
+    if draft:
+        from api_agent.doc_extract import endpoint_rows, prune_openapi
+        # Show ALL methods, not just GET. Writes (POST/PUT/DELETE…) load as DOCUMENTATION only —
+        # the agent can describe them ("what params does create-order take?") but the read-only
+        # guardrail never calls them; only GET/HEAD become callable tools.
+        rows = endpoint_rows(draft)
+        _readable = {"get", "head"}
+        n_get = sum(1 for m, _p, _op in rows if m in _readable)
+        n_write = len(rows) - n_get
+        if st.session_state.get("doc_gql_note"):
+            st.sidebar.info(st.session_state["doc_gql_note"])
+        xa = draft.get("x-auth") or {}
+        if xa.get("scheme"):
+            st.sidebar.caption(f"🔑 Doc suggests **{xa['scheme']}** auth"
+                               + (f" via `{xa['header']}`" if xa.get("header") else "") + " — set it in *Auth* above.")
+        _found = f"**{len(rows)} endpoint(s) found**"
+        if n_write:
+            _found += f" — {n_get} callable GET/HEAD + {n_write} write op(s) (loaded as **read-only docs** the agent can describe, never call)"
+        st.sidebar.caption(_found + " — untick any to drop, then load:")
+        keep = set()
+        for m, p, op in rows:
+            tag = "" if m in _readable else " · _docs-only_"
+            label = f"`{m.upper()} {p}`" + tag + (f" — {op.get('summary')}" if op.get("summary") else "")
+            if st.sidebar.checkbox(label, value=True, key=f"docep::{m}::{p}"):
+                keep.add((m, p))
+        _keep_has_get = any(m in _readable for m, _p in keep)
+        # The endpoints are relative paths → they need a real server. Prefer the field; fall back to
+        # a real (non-placeholder) base URL found in the doc. Show which is in effect.
+        _doc_base = (draft.get("servers") or [{}])[0].get("url", "")
+        _eff_base = base_url_in.strip().rstrip("/") or _doc_base
+        if _eff_base and not _eff_base.lower().startswith(("http://", "https://")):
+            _eff_base = "https://" + _eff_base   # e.g. "viciqa.tapdemo.com" → add scheme
+        if _eff_base:
+            st.sidebar.caption(f"🌐 Base URL: `{_eff_base}`")
+        else:
+            st.sidebar.caption("🌐 **No base URL** — the doc uses a placeholder like `https://{host}`. "
+                               "Set **Base URL for these endpoints** above (e.g. `https://your-instance.tapclicks.com`).")
+        c1, c2 = st.sidebar.columns(2)
+        if c1.button(f"✅ Approve & load ({len(keep)})"):
+            # A base URL is only needed to CALL an endpoint (GET/HEAD). A doc with only write ops
+            # loads as read-only documentation and is never called, so it doesn't require one.
+            if _keep_has_get and not _eff_base:
+                st.sidebar.warning("⚠️ Set a **Base URL for these endpoints** first — the endpoints are "
+                                   "relative and the doc's base is a placeholder (`https://{host}`), so "
+                                   "calls would have no host.")
+                st.stop()
+            pruned = prune_openapi(draft, keep)
+            pruned["servers"] = [{"url": _eff_base or "https://{host}"}]
+            auth = (auth_header, auth_value) if auth_value else None
+            cat = build_catalog(pruned, auth=auth)
+            if not cat.tools and not cat.reference:
+                st.sidebar.warning("Nothing approved — tick at least one endpoint to load.")
+            else:
+                title = (draft.get("info") or {}).get("title") or "extracted"
+                st.session_state.specs.append(
+                    {"label": label_in.strip() or f"doc:{title}", "source": "doc-extract", "catalog": cat})
+                st.session_state.pop("doc_draft", None)
+                n_doc = max(len(cat.reference) - len(cat.tools), 0)
+                note = f"✅ Loaded **{len(cat.tools)}** callable GET op(s) from the doc"
+                note += (f" + **{n_doc}** documented write op(s) (describe-only)." if n_doc else ".")
+                st.session_state.doc_loaded_note = note
+                st.rerun()
+        if c2.button("✖ Discard"):
+            st.session_state.pop("doc_draft", None)
+            st.rerun()
+
+# Loaded specs, each removable
+if st.session_state.specs:
+    st.sidebar.caption("**Loaded sources**")
+    for i, s in enumerate(st.session_state.specs):
+        c1, c2 = st.sidebar.columns([5, 1])
+        c1.caption(f"• **{s['label']}** · {len(s['catalog'].tools)} ops")
+        if c2.button("✕", key=f"rmspec_{i}", help=f"Remove {s['label']}"):
+            st.session_state.specs.pop(i)
+            st.rerun()
+else:
+    st.sidebar.info("No specs loaded — add one above (see the demos in the chat).")
+
+catalog = (
+    merge_catalogs([(s["label"], s["catalog"]) for s in st.session_state.specs])
+    if st.session_state.specs else Catalog([])
+)
+st.session_state.catalog = catalog
+st.session_state.catalog_label = " + ".join(s["label"] for s in st.session_state.specs) or "(none)"
+st.sidebar.caption(f"Active: **{len(st.session_state.specs)} source(s)** · {len(catalog.tools)} operations")
+
+# --------------------------------------------------------------------------- #
+# Model + behaviour
+# --------------------------------------------------------------------------- #
+st.sidebar.subheader("Model")
+base_url = st.sidebar.text_input("LLM base URL", ENV.base_url)
+api_key = st.sidebar.text_input("API key", ENV.api_key, type="password")
+generator_model = st.sidebar.text_input("Generator model", ENV.generator_model)
+synthesis_model = st.sidebar.text_input(
+    "Writer model (blank = generator)", ENV.synthesis_model,
+    help="Used ONLY for the user-facing writing stages — synthesis, self-review and resynthesis. "
+         "Everything else (router, executor, judge) stays on the generator model. Point this at a "
+         "stronger model to raise answer quality without paying for it on every call.")
+judge_enabled = st.sidebar.checkbox(
+    "Quality scoring (LLM judges)", value=bool(ENV.judge_enabled),
+    help="On: the answer is graded — a grounding fact-check, a responsiveness check and a "
+         "presentation check, plus the 0–5 scorecard. That is up to three extra LLM calls per "
+         "answered question, and the grounding one re-sends the whole evidence block, so it is the "
+         "most expensive optional part of a query.\n\n"
+         "Off: none of those calls are made and no scorecard is shown. Every DETERMINISTIC check "
+         "still runs — figures are still matched against the fetched data, the total / attribution "
+         "/ superlative repairs still fire, and the confidentiality and PII scrubs are untouched. "
+         "The answer is still checked; it just isn't scored. Default comes from JUDGE_ENABLED.")
+judge_model = st.sidebar.text_input("Judge model", ENV.judge_model,
+                                    disabled=not judge_enabled)
+# Routing, embeddings and the tool-iteration limit are set in .env (not the UI) — they rarely change
+# per session. The router AND cache-match LLM reuse the generator model unless ROUTER_MODEL is set.
+# st.sidebar.caption(
+#     f"⚙️ Routing, embeddings & tool-iteration limits are set in **.env** "
+#     f"(`ROUTER_*`, `EMBEDDING_MODEL` = `{ENV.embedding_model or 'lexical only'}`, "
+#     f"`MAX_TOOL_ITERATIONS` = `{ENV.max_tool_iterations}`). The router & cache-match LLM reuse the "
+#     f"**generator model** unless `ROUTER_MODEL` is set.")
+
+st.sidebar.subheader("💲 Budget & cost")
+max_response_tokens = st.sidebar.number_input(
+    "Max tokens / response (0 = unlimited)", min_value=0, value=int(ENV.max_response_tokens), step=1000,
+    help="Spending guardrail: stop a single response once its cumulative tokens reach this. The "
+    "answer is returned with what was gathered (marked partial).",
+)
+def _rate_of(model: str) -> tuple[float, float]:
+    return (ENV.model_pricing.get(model)
+            or ENV.model_pricing.get((model or "").split("/")[-1]) or (0.0, 0.0))
+
+# Prices are keyed by model name so they RE-PREFILL when you switch models (type gpt-4o-mini →
+# 0.15/0.60 appears). Known OpenAI/Groq/etc. models auto-fill from config.DEFAULT_MODEL_PRICING; an
+# unknown model prefills 0 (tokens shown, no $) — type a rate to price it.
+pricing = dict(ENV.model_pricing)
+
+# ---- Generator pricing (executor + synthesis; ALSO the router & cache-match LLM, which reuse it) --
+st.sidebar.caption(f"**Generator** pricing · `{generator_model or '(unset)'}` — routing, the executor tool-loop, planning and the judge")
+_grate = _rate_of(generator_model)
+gen_in = st.sidebar.number_input(
+    "Generator input price ($ / 1M tokens)", min_value=0.0, value=float(_grate[0]), step=0.05,
+    format="%.4f", key=f"gen_price_in::{generator_model}",
+    help="Applies to routing, the executor tool-loop, planning and the judge. NOT to synthesis — "
+         "that moved to the Writer model below. 0 = unknown/free → not counted in $.")
+gen_out = st.sidebar.number_input(
+    "Generator output price ($ / 1M tokens)", min_value=0.0, value=float(_grate[1]), step=0.05,
+    format="%.4f", key=f"gen_price_out::{generator_model}")
+if gen_in or gen_out:
+    for _m in {generator_model, ENV.router_model or generator_model}:
+        if _m:
+            pricing[_m] = (gen_in, gen_out)
+
+# ---- Writer pricing (synthesis + self-review + resynthesis). Only shown when the writer is a
+# DISTINCT model; blank or same-as-generator means the generator price above already covers it. ----
+if synthesis_model and synthesis_model != generator_model:
+    st.sidebar.caption(f"**Writer** pricing · `{synthesis_model}`")
+    _wrate = _rate_of(synthesis_model)
+    writer_in = st.sidebar.number_input(
+        "Writer input price ($ / 1M tokens)", min_value=0.0, value=float(_wrate[0]), step=0.05,
+        format="%.4f", key=f"writer_price_in::{synthesis_model}",
+        help="Applies to synthesis, self-review and resynthesis — roughly 42% of input tokens.")
+    writer_out = st.sidebar.number_input(
+        "Writer output price ($ / 1M tokens)", min_value=0.0, value=float(_wrate[1]), step=0.05,
+        format="%.4f", key=f"writer_price_out::{synthesis_model}")
+    if writer_in or writer_out:
+        pricing[synthesis_model] = (writer_in, writer_out)
+
+# ---- Judge pricing (grounding + responsiveness checks). Only shown when the judge is a DISTINCT
+# model; when judge == generator the generator price above already covers it. ----
+if judge_enabled and judge_model and judge_model != generator_model:
+    st.sidebar.caption(f"**Judge** pricing · `{judge_model}`")
+    _jrate = _rate_of(judge_model)
+    judge_in = st.sidebar.number_input(
+        "Judge input price ($ / 1M tokens)", min_value=0.0, value=float(_jrate[0]), step=0.05,
+        format="%.4f", key=f"judge_price_in::{judge_model}",
+        help="Applies to the grounding + responsiveness checks. Set so the judge's tokens are priced "
+             "at ITS own rate (they're already counted in the total either way).")
+    judge_out = st.sidebar.number_input(
+        "Judge output price ($ / 1M tokens)", min_value=0.0, value=float(_jrate[1]), step=0.05,
+        format="%.4f", key=f"judge_price_out::{judge_model}")
+    if judge_in or judge_out:
+        pricing[judge_model] = (judge_in, judge_out)
+
+tool_names = list(catalog.tools.keys())
+enabled = st.sidebar.multiselect(
+    "Enabled operations", tool_names, default=tool_names,
+    key=f"enabled::{st.session_state.catalog_label}",
+)
+
+# Routing / embeddings / max-iterations are intentionally NOT overridden here — they come from .env
+# (ENV already carries them). Only the per-session fields the sidebar still exposes are overridden.
+config = ENV.override(
+    base_url=base_url, api_key=api_key, generator_model=generator_model, judge_model=judge_model,
+    judge_enabled=bool(judge_enabled), synthesis_model=synthesis_model,
+    max_response_tokens=int(max_response_tokens), model_pricing=pricing,
+)
+for issue in config.problems():
+    st.sidebar.warning(issue)
+
+_clear_chat, _clear_cache = st.sidebar.columns(2)
+if _clear_chat.button("🗑️ Clear chat", help="Remove the visible conversation."):
+    st.session_state.pop("messages", None)
+if _clear_cache.button("⚡ Clear cache", help="Empty the in-memory answer cache so every question "
+                       "re-runs fresh (the cache lives in memory only — there's no file)."):
+    from api_agent.agent import clear_query_cache
+    st.sidebar.success(f"Cleared {clear_query_cache()} cached answer(s).")
+
+# One agent per BACKEND FAMILY when both are loaded (warehouse first — ties prefer the
+# direct-SQL path); the Supervisor routes each question to ONE of them and falls back to
+# the other if the chosen source is unreachable. A single family keeps today's one-agent path.
+_sql_specs = [s for s in st.session_state.specs
+              if any(t.backend == "sql" for t in s["catalog"].tools.values())]
+_http_specs = [s for s in st.session_state.specs if s not in _sql_specs]
+if _sql_specs and _http_specs:
+    def _family_agent(specs):
+        return Agent(config, merge_catalogs([(s["label"], s["catalog"]) for s in specs]))
+    agent = Supervisor(config, [("warehouse", _family_agent(_sql_specs)),
+                                ("api", _family_agent(_http_specs))])
+else:
+    agent = Agent(config, catalog)
+
+# --------------------------------------------------------------------------- #
+# Main: chat
+# --------------------------------------------------------------------------- #
+st.title("🛰️ API Agent")
+st.caption(
+    "Load one or more specs in the sidebar, then ask a question — the agent picks the right "
+    "operations across all loaded specs, calls them, and answers with citations + a faithfulness check."
+)
+
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+
+if not st.session_state.messages:
+    with st.chat_message("assistant"):
+        st.markdown(greeting_message())
+
+for m in st.session_state.messages:
+    with st.chat_message(m["role"]):
+        st.markdown(_md(m["content"]))
+        if m.get("steps"):  # the live-status log, kept (collapsed) so it doesn't vanish on completion
+            with st.expander("⚙️ Steps the agent took", expanded=False):
+                st.markdown(m["steps"])
+        if m.get("result") is not None:
+            _render_trend_chart(m["result"])   # above the metadata, below the answer it illustrates
+            render_result(m["result"])
+
+# A response can take many seconds. Rather than block the whole script (which would freeze the
+# page and make a Stop button unclickable), the agent runs in a BACKGROUND THREAD that pushes
+# progress events onto a queue; the main script polls that queue on a short auto-rerun and can set
+# a cancel Event the agent checks at each step. So the user sees live steps AND can hit Stop.
+_STAGE_ICONS = {
+    "cache": "⚡", "route": "🧭", "intent": "🛡️", "doc": "📖",
+    "call": "🔧", "complete": "➕", "synthesize": "✍️", "validate": "🔍",
+    "retry": "♻️", "abstain": "⚠️", "budget": "🛑",
+}
+_SPINNER = "◐◓◑◒"  # rotates once per poll → a clearly visible "still working" indicator (no flicker)
+# Pin the viewport to the NEW question so the long run doesn't look like it answered the old one.
+_SCROLL_PIN = """<script>
+(function () {
+  const doc = window.parent.document;
+  let n = 0;
+  function pin() {
+    const msgs = doc.querySelectorAll('[data-testid="stChatMessage"]');
+    const t = msgs[msgs.length - 2] || msgs[msgs.length - 1];  // the new USER question
+    if (t) t.scrollIntoView({block: "start", behavior: "instant"});
+    if (++n < 12) setTimeout(pin, 250);
+  }
+  pin();
+})();
+</script>"""
+
+
+def _drain(run) -> bool:
+    """Move all queued progress events into run['events']; return True once the worker is done."""
+    done = False
+    while True:
+        try:
+            kind, payload = run["queue"].get_nowait()
+        except queue.Empty:
+            break
+        if kind == "done":
+            done = True
+        else:
+            run["events"].append(payload)
+    return done
+
+
+def _events_summary(run) -> tuple[str, str, str, str]:
+    """Fold the queued progress events into (current-action header, step-log markdown, token line,
+    streaming answer). Rendered as plain markdown so the live view updates IN PLACE — unlike an
+    `st.status` expander, which replays an open/close animation on every poll (the flicker)."""
+    header, tokens, answer = "Starting…", "", ""
+    lines: list[str] = []
+    for ev in run["events"]:
+        stage = ev.get("stage", "")
+        if stage == "routed":
+            continue
+        if stage == "usage":
+            cost = ev.get("cost")
+            tail = f" · 💲${cost:.4f}" if cost is not None else ""
+            tokens = (f"🔢 {ev.get('total', 0):,} tokens "
+                      f"(in {ev.get('prompt', 0):,} · out {ev.get('completion', 0):,}){tail}")
+            continue
+        msg = ev.get("message", "")
+        if stage == "answer":
+            answer = msg
+        elif stage == "call_done":
+            lines.append(f"- {'✓' if ev.get('ok') else '✗'} {msg}")
+        else:
+            header = msg
+            lines.append(f"- {_STAGE_ICONS.get(stage, '•')} {msg}")
+    return header, "\n".join(lines), tokens, answer
+
+
+def _start_run(the_agent, prompt, history, enabled_tools) -> None:
+    """Kick off agent.run in a daemon thread. The thread NEVER touches st.* — it only pushes events
+    onto a thread-safe queue and stashes the result; the main script renders on its poll reruns."""
+    q: queue.Queue = queue.Queue()
+    cancel = threading.Event()
+    holder: dict = {}
+
+    def worker():
+        try:
+            holder["result"] = the_agent.run(
+                prompt, history=history, enabled_tools=enabled_tools,
+                progress=lambda ev: q.put(("ev", ev)), cancel_check=cancel.is_set)
+        except Exception as exc:  # pragma: no cover — surfaced in the UI on the next poll
+            holder["error"] = str(exc)
+        finally:
+            q.put(("done", None))
+
+    threading.Thread(target=worker, daemon=True).start()
+    st.session_state.run = {"queue": q, "cancel": cancel, "holder": holder,
+                            "prompt": prompt, "events": []}
+
+
+run_active = bool(st.session_state.get("run"))
+prompt = st.chat_input("Ask a question about the loaded API…", disabled=run_active)
+if prompt and not run_active:
+    st.session_state.messages.append({"role": "user", "content": prompt})
+    history = [
+        {"role": m["role"], "content": m["content"]}
+        for m in st.session_state.messages[:-1]
+        if m["role"] in ("user", "assistant")
+    ]
+    _start_run(agent, prompt, history, enabled)
+    st.rerun()
+
+@st.fragment(run_every=0.3)
+def _render_active_run() -> None:
+    """Render the in-flight run's live progress. Runs as a FRAGMENT, so only THIS bubble reloads
+    every 0.5s to poll the background worker — the sidebar and chat history don't re-render. The
+    progress is drawn as plain markdown inside a static bordered box (NOT an `st.status` expander),
+    so a poll updates the text in place instead of animating a dropdown open/closed. On completion it
+    does one full ``st.rerun()`` to return to the idle state (which re-enables the chat input)."""
+    run = st.session_state.get("run")
+    if not run:
+        return
+    done = _drain(run)
+    run["polls"] = run.get("polls", 0) + 1
+    spin = _SPINNER[run["polls"] % len(_SPINNER)]  # advances each poll → a live "working" spinner
+    header, log_md, tokens, answer = _events_summary(run)
+    with st.container(border=True):
+        head = "✅ Done" if done else f"{spin} Working — {header}"
+        st.markdown(f"**{head}**  \n_{run['prompt'][:80]}_")
+        if log_md:
+            st.markdown(log_md)
+    if not done:
+        if tokens:
+            st.caption(tokens)
+        if answer:
+            st.markdown(_md(answer) + " ▌")  # the answer streaming in as it's composed
+        # Stop is IMMEDIATE: flag cancel (so the worker makes no further calls) and ABANDON the run
+        # right now — don't wait for the in-flight call to return. Back to idle instantly with a
+        # "Stopped" message; the orphaned daemon thread finishes its current call and is discarded.
+        if st.button("⏹️ Stop", key="stop_run", type="primary",
+                     help="Stop now — no further API/LLM calls."):
+            run["cancel"].set()
+            st.session_state.pop("run", None)
+            st.session_state.messages.append(
+                {"role": "assistant", "content": "⏹️ **Stopped.**", "steps": log_md})
+            st.rerun()
+        return  # the fragment auto-reruns in ~0.3s to poll again
+    # ---- finished: stash the answer + the step log in history and drop back to the idle state ----
+    holder = run["holder"]
+    st.session_state.pop("run", None)
+    if "error" in holder:
+        st.session_state.messages.append(
+            {"role": "assistant", "content": f"⚠️ Agent error: {holder['error']}", "steps": log_md})
+    else:
+        result = holder["result"]
+        st.session_state.messages.append(
+            {"role": "assistant", "content": result.answer, "result": result, "steps": log_md})
+    st.rerun()  # full rerun: re-enable the chat input and render the answer from history
+
+
+if st.session_state.get("run"):
+    with st.chat_message("assistant"):
+        components.html(_SCROLL_PIN, height=0)
+        _render_active_run()