aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/apps/cli/handlers/realty_handlers.py

@@ -0,0 +1,114 @@
+"""Deterministic real-estate query handler extracted from aria_cli.py."""
+from __future__ import annotations
+
+from typing import Callable
+
+
+def handle_realty_query(
+    message: str,
+    *,
+    is_realty_query: Callable[[str], bool],
+    cn_cities: tuple | list,
+    intl_cities: tuple | list,
+) -> dict:
+    """Deterministic handler for natural-language real-estate / housing questions.
+
+    Detects city names + real-estate keywords and calls the realty data tools
+    directly, returning a formatted response without needing the LLM to parse it.
+    """
+    if not is_realty_query(message):
+        return {"success": False, "error": "not_realty_query"}
+
+    try:
+        from realty_data_tools import get_house_price_index, get_re_investment
+    except ImportError:
+        return {"success": False, "error": "realty_data_tools_not_available"}
+
+    cities_found: list[str] = []
+    for city in cn_cities:
+        if city in message:
+            cities_found.append(city)
+        if len(cities_found) >= 2:
+            break
+
+    _low_msg = message.lower()
+    _intl_found = [c for c in intl_cities if c in _low_msg]
+
+    if _intl_found and not cities_found:
+        _intl_name = _intl_found[0]
+        return {
+            "success": True,
+            "response": (
+                f"## 🌍 {_intl_name.title()} 房地产市场\n\n"
+                f"国际城市房价数据目前依赖 LLM 知识库分析（无实时数据接入）。\n\n"
+                f"**当前支持实时数据的城市：** 中国大陆 70 个主要城市（北上广深等）\n\n"
+                f"如需国际市场数据，建议查阅：\n"
+                f"- 美国：`/realty us` — 联邦住房数据（Case-Shiller 指数、新屋开工）\n"
+                f"- 其他国际城市：可直接提问，Aria 将基于训练知识回答（数据截止至知识库更新时间）\n\n"
+                f"---\n\n"
+                f"请问您具体想了解 **{_intl_name.title()}** 哪方面的房地产信息？"
+            ),
+            "tools_used": ["realty_query"],
+        }
+
+    city1 = cities_found[0] if cities_found else "全国"
+    city2 = cities_found[1] if len(cities_found) > 1 else ("上海" if city1 != "上海" else "北京")
+
+    lines: list[str] = []
+    lines.append(f"## 🏠 {city1} 房地产市场")
+    if len(cities_found) > 1:
+        lines[-1] += f" vs {city2}"
+    lines.append("")
+
+    try:
+        r = get_house_price_index(city1, city2)
+        if r.get("success"):
+            for lbl, cd in (
+                (city1, r.get("latest_city1", {})),
+                (city2, r.get("latest_city2", {})),
+            ):
+                if not cd:
+                    continue
+                lines.append(f"### {lbl}")
+                if cd.get("new_yoy") is not None:
+                    lines.append(f"- **新房同比**：{float(cd['new_yoy']):+.2f}%")
+                if cd.get("new_mom") is not None:
+                    lines.append(f"- **新房环比**：{float(cd['new_mom']):+.2f}%")
+                if cd.get("second_yoy") is not None:
+                    lines.append(f"- **二手房同比**：{float(cd['second_yoy']):+.2f}%")
+                if cd.get("second_mom") is not None:
+                    lines.append(f"- **二手房环比**：{float(cd['second_mom']):+.2f}%")
+                if cd.get("date"):
+                    lines.append(f"- **数据期**：{cd['date']}")
+                lines.append("")
+        else:
+            lines.append(f"房价指数数据暂时不可用（{r.get('error', '数据源未响应')}）")
+            lines.append("")
+    except Exception as _e:
+        lines.append(f"获取房价数据失败: {_e}")
+        lines.append("")
+
+    try:
+        ri = get_re_investment()
+        if ri.get("success") and ri.get("latest"):
+            lt = ri["latest"]
+            lines.append("### 全国房地产开发投资")
+            lines.append(f"- **最新值**：{lt.get('最新值', 'N/A')}")
+            lines.append(f"- **日期**：{lt.get('日期', 'N/A')}")
+            lines.append(f"- **涨跌幅**：{lt.get('涨跌幅', 'N/A')}")
+            lines.append(f"- **近1年涨跌幅**：{lt.get('近1年涨跌幅', 'N/A')}")
+            lines.append("")
+    except Exception:
+        pass
+
+    lines.append("**更多操作**")
+    lines.append(f"- `/realty market {city1}` — 完整城市房价走势图")
+    lines.append(f"- `/realty compare {city1} {city2}` — 城市横向对比")
+    lines.append("- `/realty rent` — 租金收益率计算")
+    lines.append("- `/realty reit` — REIT 市场数据")
+
+    return {
+        "success": True,
+        "response": "\n".join(lines),
+        "tools_used": ["realty_query"],
+    }

aria_code/apps/cli/handlers/sports_handlers.py

@@ -0,0 +1,22 @@
+"""Sports context prefetch for the chat path.
+
+The market equivalent already lives in handlers/market_handlers.py; this one
+was still inline in aria_cli and borrowed from its globals by stream_ollama,
+so the fallback path (SDK, daemon) raised NameError on any sports query.
+
+Kept deliberately quiet: a prefetch is an optimisation, and a missing or
+failing football client must degrade to "no extra context" rather than break
+the turn.
+"""
+
+from __future__ import annotations
+
+
+def try_prefetch_sports_data(message: str) -> str:
+    """Live sports context for a query, or "" when unavailable."""
+    try:
+        from football_data_client import get_sports_context_for_query
+
+        return get_sports_context_for_query(message) or ""
+    except Exception:
+        return ""

aria_code/apps/cli/handlers/strategy_advice.py

@@ -0,0 +1,82 @@
+"""Deterministic strategy-advice responses.
+
+This keeps advisory questions from being treated as code-generation tasks.
+When the user asks "how should I write a strategy" or "from which angles",
+the CLI should answer with a framework and explicit next commands, not create
+files or run backtests without a generation/execution intent.
+"""
+
+from __future__ import annotations
+
+
+_STRATEGY_TERMS = (
+    "量化策略", "交易策略", "美股策略", "回测策略", "策略框架",
+    "quant strategy", "trading strategy", "backtest strategy",
+)
+
+_ADVICE_TERMS = (
+    "几个角度", "哪些角度", "从几个方面", "怎么写", "如何写",
+    "思路", "框架", "结构", "要考虑", "你觉得", "建议",
+    "how", "what should", "framework", "approach", "angles",
+)
+
+_EXECUTION_TERMS = (
+    "开始写", "帮我写", "生成", "实现", "创建", "保存", "运行",
+    "回测一下", "直接做", "落地", "完善代码",
+    "write", "generate", "implement", "create", "save", "run",
+)
+
+
+def is_strategy_advice_request(message: str) -> bool:
+    text = (message or "").strip()
+    if not text or text.startswith("/"):
+        return False
+    low = text.lower()
+    has_strategy = any(term in text or term in low for term in _STRATEGY_TERMS)
+    has_advice = any(term in text or term in low for term in _ADVICE_TERMS)
+    has_execution = any(term in text or term in low for term in _EXECUTION_TERMS)
+    return bool(has_strategy and has_advice and not has_execution)
+
+
+def handle_strategy_advice(message: str) -> dict:
+    if not is_strategy_advice_request(message):
+        return {"success": False, "error": "not_strategy_advice"}
+
+    response = """## 美股量化策略写作框架
+
+建议从 8 个层级写，先定义假设，再验证和风控，最后才进入交易执行。
+当前是咨询型问题，不需要先写文件，也不会自动运行回测。
+
+| 层级 | 要解决的问题 | 产物 |
+|---|---|---|
+| 1. 市场假设 | 为什么这个信号可能赚钱 | 策略假设、适用市场、失效条件 |
+| 2. 标的池 | 交易哪些股票/ETF，如何剔除不可交易标的 | universe 规则、流动性/价格过滤 |
+| 3. 数据层 | OHLCV、财报、因子、宏观、新闻是否可得且可信 | 数据源、清洗、复权、缺失处理 |
+| 4. 信号层 | 入场/出场依据是什么 | 因子、阈值、信号延迟、防未来函数 |
+| 5. 组合层 | 单票仓位、行业暴露、相关性怎么控制 | 权重、再平衡、最大持仓、现金规则 |
+| 6. 交易成本 | 手续费、滑点、冲击成本是否吞噬收益 | 成本模型、成交假设 |
+| 7. 回测评估 | 策略是否稳健，而不是只在样本内好看 | CAGR、Sharpe、最大回撤、胜率、换手、分阶段表现 |
+| 8. 风控部署 | 实盘如何限制损失并监控失效 | 止损、熔断、告警、paper/live 分层 |
+
+**推荐落地顺序**
+
+1. 先写一页策略说明：假设、标的池、调仓频率、风险边界。
+2. 再写最小回测脚本：只包含数据、信号、仓位、绩效。
+3. 加 walk-forward、不同市场阶段、参数敏感性测试。
+4. 通过后接 paper trading，不直接上实盘。
+5. 实盘前加入订单预览、资金上限、熔断、审计日志。
+
+**下一步命令**
+
+- `/scaffold my_us_strategy --template strategy`：生成策略项目骨架。
+- `/backtest momentum SPY --period 1y`：先跑一个内置动量回测。
+- `/auto-strategy momentum SPY --target sharpe=1.2`：进入自动优化流程。
+
+*这只是策略设计框架，不构成投资建议。需要我生成代码时，请明确说“生成/实现/写文件”。*"""
+
+    return {
+        "success": True,
+        "response": response,
+        "tools_used": ["strategy_advice"],
+        "analysis_complete": True,
+    }

aria_code/apps/cli/headless.py

@@ -0,0 +1,352 @@
+"""Non-interactive Aria: `aria-code -p "…"` and `--watch`.
+
+Moved out of aria_cli.py, where ArtheraTerminal held it alongside the REPL.
+The bodies are unchanged and still use aria_cli's names (console, LOCAL_TOOLS,
+_run_deterministic_chain, …): aria_cli binds a copy of this class to its own
+globals with bind_to() and puts it among ArtheraTerminal's bases. A copy per
+binding, because aria_cli loads under two names (aria_cli and
+aria_code.aria_cli); rebinding one shared class would leave both terminals
+on whichever module loaded last.
+"""
+
+from __future__ import annotations
+
+def _headless_approval(config: dict, auto_approve, always_allow, *, on_denied=None):
+    """Answer approvals with what the operator granted up front, and nothing more.
+
+    ``auto_approve`` and ``always_allow`` are read at call time from the module
+    that is actually running (aria_cli, aria_code.aria_cli or __main__ under
+    ``python -m``), which is where --dangerously-skip-permissions and
+    --allow-tools set them.
+    """
+    from aria_code.runtime.approval import ApprovalDecision
+
+    def decide(tool_name: str, params: dict):
+        if not (auto_approve() or tool_name in (always_allow() or ())):
+            reason = "no one is here to approve it; pass --allow-tools or --dangerously-skip-permissions"
+            if on_denied is not None:
+                on_denied(tool_name, reason)
+            return ApprovalDecision.deny(reason)
+        if tool_name == "run_command":
+            return ApprovalDecision.allow(policy=config.get("command_policy", "safe"), user_approved=True)
+        return ApprovalDecision.allow()
+
+    return decide
+
+
+def _apply_approval_decision(params: dict, decision) -> dict:
+    from aria_code.runtime.approval import apply_approval_decision
+
+    return apply_approval_decision(params, decision)
+
+
+class HeadlessMixin:
+    """run_prompt, _run_prompt_turn, _finish_prompt and run_watch for ArtheraTerminal."""
+
+    async def run_prompt(self, prompt: str, json_output: bool = False,
+                         fmt: str = "table", output_file: str = None, quiet: bool = False,
+                         machine_out=None):
+        """Run a single prompt (non-interactive / pipe mode).
+
+        ``machine_out`` is the real stdout when the output is JSON (sys.stdout
+        then points at stderr). With fmt "jsonl" each step is written there as
+        one JSON event per line as it happens.
+        """
+        from aria_code.apps.cli.exec_events import ExecEvents, json_safe
+        events = ExecEvents(machine_out if fmt == "jsonl" else None)
+        events.emit("turn.started", prompt=prompt, model=self.config.get("model", ""))
+        result = await self._run_prompt_turn(prompt, quiet=quiet, events=events)
+        self._finish_prompt(result, json_output=json_output, fmt=fmt, output_file=output_file,
+                            quiet=quiet, machine_out=machine_out, events=events)
+
+    async def _run_prompt_turn(self, prompt: str, *, quiet: bool, events) -> dict:
+        """The work of run_prompt: a slash command, a deterministic answer, or an agent turn."""
+        model = self.config.get("model", "qwen2.5:7b")
+        thinking_mode = self.config.get("thinking_mode", "auto")
+        from aria_code.account_session import prepare_account
+        from aria_code.apps.cli.config_store import save_cli_config
+        from aria_code.apps.cli.config_paths import resolve_paths
+        save_account = lambda cfg: save_cli_config(resolve_paths(), cfg)
+        auth_token = await prepare_account(self.config, save_account)
+        auth_token = auth_token or self.config.get("auth_token")
+        user_context = _build_user_context(self.config)
+
+        local_mode = self.config.get("local_mode", False)
+
+        # Dispatch slash commands in -p mode (same as interactive REPL loop).
+        # Without this, /memory /note /init /review are sent to the LLM as plain text.
+        _stripped_prompt = prompt.strip()
+        if self.commands.is_command(_stripped_prompt):
+            self._maybe_show_intent_preflight(_stripped_prompt, quiet=quiet)
+            await self.commands.execute(_stripped_prompt)
+            return {"success": True, "command": _stripped_prompt.split()[0], "response": ""}
+
+        _reference_context = ""
+        _reference_service = getattr(self, "_reference_service", None)
+        if _reference_service is not None and "@" in prompt:
+            _prepared_references = _reference_service.prepare(prompt)
+            if _prepared_references.errors:
+                self._print_reference_errors(_prepared_references)
+                return {"success": False, "response": "", "error": "unresolved @ reference"}
+            if _prepared_references.references:
+                self._print_reference_summary(_prepared_references)
+                prompt = _prepared_references.expanded_text
+                _reference_context = _prepared_references.context_block
+
+        # Keep referenced local files as pointers; the model reads them through
+        # audited tools instead of silently embedding their contents.
+        if _reference_context:
+            prompt = f"{prompt}\n\n{_reference_context}"
+        else:
+            _file_tool_hint = _build_file_tool_hint(prompt)
+            if _file_tool_hint:
+                prompt = _file_tool_hint + prompt
+        self._maybe_show_intent_preflight(prompt, quiet=quiet)
+
+        _curr_model_id_p = self.config.get("model", "")
+        # The route counts as much as the model: on backend_chat the model gets
+        # no local tools whatever it could do with them. This only looked at the
+        # model, so the deterministic chain skipped its data pre-fetch there.
+        from aria_code.apps.cli.workspace_route import no_tools_message, needs_workspace, route_has_tools, workspace_config
+        _runtime_config = workspace_config(prompt, _curr_model_id_p, self.config, self.api_url)
+        _model_has_tools_p = route_has_tools(_curr_model_id_p, _runtime_config, self.api_url)
+
+        # ── Broker guide intent: broad discovery should not start an add wizard ──
+        if _is_broker_guide_intent(prompt):
+            if HAS_RICH:
+                console.print("\n[bold]Aria[/bold]  [dim]  正在打开券商与服务指南…[/dim]\n")
+            await self.commands.cmd_broker("guide")
+            await self.commands.cmd_broker("services")
+            await self.commands.cmd_packages("services")
+            return {"success": True, "command": "/broker guide", "response": ""}
+
+        # ── Broker setup intent: intercept before LLM / deterministic routing ──
+        if _is_broker_setup_intent(prompt):
+            _btype_p = _detect_broker_type(prompt)
+            if HAS_RICH:
+                from apps.cli.utils.market_detect import _BROKER_SETUP_NAMES
+                _display_p = _BROKER_SETUP_NAMES.get(_btype_p, ("",))[0] if _btype_p else ""
+                _label_p = f"  正在启动{_display_p}配置向导…" if _display_p else "  正在启动券商配置向导…"
+                console.print(f"\n[bold]Aria[/bold]  [dim]{_label_p}[/dim]\n")
+            await self.commands._cmd_broker_add(_btype_p)
+            return {"success": True, "command": "/broker add", "response": ""}
+
+        # ── Football prediction intercept → built-in Poisson handler ──────────
+        if await self._try_football_nl_intercept(prompt):
+            return {"success": True, "command": "football", "response": ""}
+
+        deterministic = _run_deterministic_chain(
+            prompt, model_has_tools=_model_has_tools_p)
+        if deterministic.get("success") or _is_stock_chart_analysis_request(prompt):
+            result = deterministic
+        else:
+            # No one reads a headless answer before a script acts on it. A task
+            # about this folder on a model that cannot open it would come back as
+            # a confident guess with exit 0; fail before sending it instead.
+            if not _model_has_tools_p and needs_workspace(prompt):
+                _zh = str(self.config.get("ui_lang", "en")).lower().startswith("zh")
+                _why = no_tools_message(self.config, lang="zh" if _zh else "en")
+                print(_why, file=sys.stderr)
+                return {"success": False, "response": "", "error": "model_cannot_use_tools", "detail": _why}
+            # Spinner for terminal usage: gives visual feedback while the model generates.
+            # Only starts when we actually need to call the LLM (not for deterministic responses).
+            _prompt_spinner = None
+            if HAS_RICH and sys.stdout.isatty():
+                try:
+                    _prompt_spinner = console.status("", spinner="dots", spinner_style="dim")
+                    _prompt_spinner.__enter__()
+                except Exception:
+                    _prompt_spinner = None
+            try:
+                # Headless -p runs the SAME loop as the REPL.
+                #
+                # It used to call stream_provider_result directly: one provider
+                # round, tool schemas advertised but nothing executing what came
+                # back, and a single best-effort pass over tool_calls_pending
+                # afterwards whose results the model never saw. So `-p` was not
+                # agentic at all — no rounds, no tool results fed back, no loop
+                # guard, no acceptance gate. Every non-interactive user (CI, a
+                # pipe, the eval harness) got a chat reply where the REPL would
+                # have done the work.
+                #
+                # run_chat_via_runtime is the documented single entry point and
+                # already handles provider selection and cloud→Ollama fallback,
+                # which is what the two branches here were open-coding.
+                from aria_code.apps.cli.providers.runtime_bridge import run_chat_via_runtime
+                # This method runs on aria_cli's names; these two live here.
+                from aria_code.apps.cli.headless import _apply_approval_decision, _headless_approval
+
+                import uuid
+                _headless_scope = str(getattr(self, "session_id", "") or uuid.uuid4())
+                _turn = await run_chat_via_runtime(
+                    prompt=prompt, history=[],
+                    local_tools=LOCAL_TOOLS, tool_schemas=LOCAL_TOOL_SCHEMAS,
+                    model=model, config=_runtime_config, api_url=self.api_url,
+                    ollama_url=self.config.get("ollama_url", "http://localhost:11434"),
+                    thinking_mode=thinking_mode, user_context=user_context,
+                    auth_token=auth_token, project_context=_PROJECT_CONTEXT,
+                    max_rounds=int(self.config.get("max_rounds", 30) or 30),
+                    # No approval UI exists in headless mode; the operator opts in
+                    # with --dangerously-skip-permissions or --allow-tools. Those
+                    # used to take the tools out of the confirm set, so no
+                    # approval ever happened — and an approval is what lets
+                    # run_command past the default "safe" policy (the REPL's
+                    # "allow" upgrades it to balanced). Every `python3 script.py`
+                    # was blocked: the evals' agents wrote scripts they could not
+                    # run, then computed by hand or stopped. Now the confirm set
+                    # stays, and the pre-approval answers it the way the REPL would.
+                    confirm_tools=frozenset(_CONFIRM_TOOLS),
+                    approval_callback=_headless_approval(
+                        self.config, lambda: _auto_approve_session, lambda: _session_always_allow,
+                        on_denied=lambda tool, reason: events.status("approval_denied", f"{tool}: {reason}")),
+                    approval_applier=_apply_approval_decision,
+                    on_tool_call=events.tool_started,
+                    on_tool_result=events.tool_completed,
+                    on_token=events.text_delta if events.streaming else None,
+                    on_status=events.status if events.streaming else None,
+                    execution_context=lambda: {"_session_id": _headless_scope},
+                    return_result=True,
+                )
+                _tools_used = list(getattr(_turn.final, "tools", []) or [])
+                # A missing closing message can count as success only with
+                # passing acceptance evidence, never merely because a tool ran.
+                _empty_after_work = (
+                    _turn.error == "empty_response" and bool(_tools_used)
+                    and (getattr(_turn.final, "acceptance", None) or {}).get("verified") is True
+                )
+                result = {
+                    "success": _turn.ok or _empty_after_work,
+                    "response": (
+                        _turn.text
+                        or (f"（模型未给出收尾说明。已执行的工具：{', '.join(_tools_used)}）"
+                            if _empty_after_work else "")
+                    ),
+                    "error": "" if _empty_after_work else (_turn.error or ""),
+                    "provider": getattr(_turn.final, "provider", ""),
+                    "tools_used": _tools_used,
+                    "acceptance": getattr(_turn.final, "acceptance", None),
+                    "delivery": getattr(_turn.final, "delivery", None),
+                    "contract": getattr(_turn.final, "contract", None),
+                    "stop_reason": getattr(_turn.final, "stop_reason", "") or _turn.error or "completed",
+                }
+            finally:
+                if _prompt_spinner is not None:
+                    try:
+                        _prompt_spinner.__exit__(None, None, None)
+                    except Exception:
+                        pass
+
+        return result
+
+    def _finish_prompt(self, result: dict, *, json_output: bool, fmt: str, output_file,
+                       quiet: bool, machine_out, events) -> None:
+        """Print or save run_prompt's result, and exit 1 if it failed."""
+        from aria_code.apps.cli.exec_events import json_safe
+        result = result or {"success": False, "response": "", "error": "no result"}
+        # The agent loop executes tools now, so there is nothing left over to
+        # run here — only stream_provider_result ever populated
+        # tool_calls_pending, and the deterministic chain never does. Keeping
+        # the old pass would risk running a write twice.
+        #
+        # What is worth surfacing instead is the acceptance verdict: in headless
+        # mode nobody watched the run, so a turn that changed files and failed
+        # its checks must say so on stderr rather than print a confident summary
+        # and exit 0.
+        _acceptance = (result or {}).get("acceptance") or {}
+        if _acceptance.get("verified") is False:
+            result["success"] = False
+            result["error"] = result.get("error") or "checks_failed"
+            result["stop_reason"] = "checks_failed"
+        if _acceptance.get("verified") is False and not quiet:
+            _zh = str(self.config.get("ui_lang", "en")).lower().startswith("zh")
+            print(f"⚠ {'验收未通过' if _zh else 'Checks failed'}: {_acceptance.get('headline', '')}",
+                  file=sys.stderr)
+
+        # What this run cost, as the provider reported it. An evaluation harness
+        # asks for it in ARIA_USAGE_FILE; imports are local because aria_cli
+        # rebinds these methods to its own globals.
+        import json as _json
+        import os as _os
+        _config = getattr(self, "config", {}) or {}
+        result["usage"] = {
+            "model": str(_config.get("model", "") or ""),
+            "provider": str(_config.get("local_provider", "") or ""),
+            "input_tokens": int(getattr(self, "_session_input_tokens", 0) or 0),
+            "output_tokens": int(getattr(self, "_session_output_tokens", 0) or 0),
+            "thinking_tokens": int(getattr(self, "_session_thinking_tokens", 0) or 0),
+            "turns": int(getattr(self, "_session_turns", 0) or 0),
+        }
+        _usage_file = _os.environ.get("ARIA_USAGE_FILE")
+        if _usage_file:
+            try:
+                with open(_usage_file, "w", encoding="utf-8") as _handle:
+                    _json.dump(result["usage"], _handle)
+            except OSError:
+                pass
+        events.emit("turn.completed", **json_safe(result))
+        out = machine_out or sys.stdout
+        if fmt == "jsonl":
+            content = None              # the events were the output
+        elif json_output or fmt == "json":
+            content = json.dumps(json_safe(result), ensure_ascii=False, indent=2)
+        elif fmt == "csv":
+            content = f"role,content\nassistant,\"{result.get('response', '').replace(chr(34), chr(34)+chr(34))}\""
+        elif fmt == "md":
+            content = f"# Aria Code AI Response\n\n{result.get('response', '')}\n"
+        else:
+            content = result.get("response", "") if result.get("success") else f"Error: {result.get('error', 'Unknown')}"
+
+        # Output routing
+        if content is None or (fmt == "table" and not json_output and result.get("command") and not content):
+            pass                        # jsonl, or a command that printed its own output
+        elif output_file:
+            with open(output_file, "w") as f:
+                f.write(content)
+            if not quiet:
+                console.print(f"[green]Saved to {output_file}[/green]" if HAS_RICH
+                              else f"Saved: {output_file}")
+        elif not result.get("success") and fmt == "table" and not json_output:
+            print(f"Error: {result.get('error', 'Unknown')}", file=sys.stderr)
+        # In default (table) format: render with Rich Markdown when output is
+        # a terminal.  This gives properly formatted headings, bold, and tables
+        # in interactive use.  When piped/redirected, fall back to plain text
+        # for scripting compatibility.
+        elif HAS_RICH and fmt == "table" and not json_output and sys.stdout.isatty() and result.get("success"):
+            console.print(make_markdown(_strip_latex(content)))
+        else:
+            print(content, file=out, flush=True)
+        # A failed turn exits 1 in every format. Only table did; with --json a
+        # script got exit 0 and had to read the body to learn it had failed.
+        if not result.get("success"):
+            sys.exit(1)
+
+    async def run_watch(self, command_fn, interval: int, cmd_args: str):
+        """Run a command repeatedly with interval (like Unix watch)."""
+        try:
+            while True:
+                if not self.config.get("_quiet"):
+                    os.system("clear" if os.name == "posix" else "cls")
+                    ts = datetime.now().strftime("%H:%M:%S")
+                    if HAS_RICH:
+                        console.print(f"[dim]Every {interval}s | {ts} | Ctrl+C to stop[/dim]\n")
+                    else:
+                        print(f"Every {interval}s | {ts} | Ctrl+C to stop\n")
+
+                await command_fn(cmd_args)
+
+                await asyncio.sleep(interval)
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            if HAS_RICH:
+                console.print("\n[dim]Watch stopped[/dim]")
+            else:
+                print("\nStopped")
+
+
+def bind_to(namespace: dict) -> type:
+    """A copy of HeadlessMixin whose methods resolve bare names in ``namespace``."""
+    from aria_code.apps.cli.mixin_binding import bind_mixin
+
+    return bind_mixin(HeadlessMixin, namespace)
+
+
+__all__ = ["HeadlessMixin", "bind_to"]