aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/runtime/agent_profiles.py

@@ -0,0 +1,75 @@
+"""Domain-neutral task roles for the existing Aria runtime.
+
+Profiles narrow a task's instructions and available tools. They do not provide
+credentials, install integrations, choose another model, or grant permissions.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AgentProfile:
+    name: str
+    description: str
+    instructions: str
+    tools: frozenset[str] | None = None
+    writable: bool = False
+    max_rounds: int = 20
+    timeout_seconds: int = 300
+
+
+READ = frozenset({"read_file", "list_files", "search_code", "glob", "analyze_file", "notebook_read", "lsp_diagnostics"})
+RESEARCH = READ | {"web_search", "web_fetch"}
+WRITE = READ | {"write_file", "edit_file", "multi_edit", "apply_patch", "notebook_edit", "run_command"}
+
+PROFILES = {
+    p.name: p for p in (
+        AgentProfile("general", "General-purpose fallback for tasks that do not fit a narrower role.",
+                     "Complete the delegated goal using available tools. State missing capabilities and evidence explicitly.",
+                     writable=True, max_rounds=30),
+        AgentProfile("explorer", "Find and explain files, architecture and execution paths without edits.",
+                     "Read targeted sources, trace the actual execution path, and cite files and symbols. Do not implement changes.", READ),
+        AgentProfile("planner", "Turn a goal into an evidence-based plan, dependencies and acceptance criteria.",
+                     "Inspect the relevant context. Return a concrete plan, dependencies, assumptions and observable acceptance criteria. Do not implement it.", RESEARCH),
+        AgentProfile("researcher", "Research technical, product or business questions with source evidence.",
+                     "Search and read primary sources when available. Separate sourced facts, inferences and unknowns; include source locations and dates for time-sensitive claims. If search access is absent, say so.", RESEARCH),
+        AgentProfile("implementer", "Implement and test a bounded software change in an isolated workspace.",
+                     "Read relevant code before editing. Implement the requested scope and run appropriate checks. Report changed files, actual commands and failures. Never push, publish or deploy.", WRITE, writable=True, max_rounds=30),
+        AgentProfile("reviewer", "Independently inspect correctness, security and missing validation without edits.",
+                     "Review the actual sources and available evidence. Report actionable findings with file locations, severity and reasoning. Distinguish static review from executed tests; no findings does not prove correctness.", READ),
+        AgentProfile("data_analyst", "Analyze datasets, validate quality and produce reproducible calculations across domains.",
+                     "Inspect supplied data and its grain, schema and quality. Use verified tool outputs for calculations; never invent computed totals. Use command execution only under inherited host policy. Write outputs only when workspace-write was requested. If no computation tool is available, return a reproducible method and the limitation instead of pretending to execute it.", WRITE, writable=True),
+        AgentProfile("writer", "Draft and revise documents, specifications and content grounded in supplied sources.",
+                     "Use authorized context and source files. Preserve audience, voice and factual provenance. Write requested files only in the permitted workspace and read them back. Return drafts for review; never send messages or publish content.", WRITE, writable=True),
+    )
+}
+
+
+def get_profile(name: str = "general") -> AgentProfile:
+    try:
+        return PROFILES[name]
+    except KeyError:
+        raise ValueError(f"Unknown agent profile: {name}. Use list_agents to discover supported roles.") from None
+
+
+def tool_list_agents(params: dict) -> dict:
+    return {"success": True, "agents": [
+        {"name": p.name, "description": p.description,
+         "modes": ["read-only", "workspace-write"] if p.writable else ["read-only"],
+         "tool_policy": "inherit parent minus delegation" if p.tools is None else sorted(p.tools),
+         "max_rounds": p.max_rounds, "timeout_seconds": p.timeout_seconds}
+        for p in PROFILES.values()
+    ], "note": "Profiles use the existing Aria model/runtime. Tools are intersected with the host's actual tool registry; listed roles do not imply connected services. Command execution remains subject to the host permission policy."}
+
+
+DELEGATION_GUIDANCE = """General task delegation:
+- Aria handles software, research, data inspection, documents and other authorized tasks across domains.
+- Built-in roles: explorer (source exploration), planner (plans), researcher (sourced research), implementer (software changes), reviewer (independent review), data_analyst (datasets), writer (documents); general is the fallback.
+- Use list_agents to discover reusable roles; select one by its description and the task context, not a keyword router. Use spawn_task(agent=..., prompt=..., success_criteria=...) for a bounded independent task when delegation is useful. Keep simple/dependent work in the main conversation unless the user explicitly requests a delegate. Honor explicit delegation requests: do not replace a requested independent writer/researcher task with a draft produced in the parent conversation.
+- Discover relevant project skill/memory descriptions with list_task_context(agent=target_role), then pass only needed IDs in spawn_task.context_refs. Only explicit project auto entries load by default; no global memory scan occurs. Context provenance records source hashes, not proof of current facts. Never copy unrelated personal context into a delegate.
+- Give the delegate its goal, relevant source context and observable acceptance criteria. Inherit the current model and permissions; never delegate to bypass a denial or gain access.
+- Declare observable checks in the spawn_task checks argument when the goal permits artifact, tool or command predicates. Describing these checks in prompt/context does not declare them. For a file-based research task, use checks=[{"kind":"tool","tool":"read_file","path":"brief.md"},{"kind":"artifact","path":"brief.md","format":"text","min_bytes":1}] with the actual requested file. File checks read actual bounded workspace bytes; command checks require a zero exit code from the exact observed command and never execute additional commands. Checks cover only declared predicates, not semantic correctness.
+- Retrieve task_result before relying on a delegate. verified=true means the declared predicates passed; verified=null means no checks were requested: explicitly report that machine acceptance was not performed and never say those checks passed. Never call either a done status or a VERIFICATION heading independent acceptance. A spawned or done task is not proof that the user's goal was verified. Check the reported evidence, artifacts and blockers; disclose missing tools or failed checks.
+- Specialized financial and warehouse capabilities remain optional domain extensions. Do not impose stock symbols, trading signals or financial-evidence requirements on unrelated tasks.
+"""

aria_code/runtime/approval.py

@@ -0,0 +1,71 @@
+"""Approval decisions for tools that require user consent."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ApprovalDecision:
+    """Structured result from a tool approval prompt."""
+
+    approved: bool
+    policy: str | None = None
+    user_approved: bool = False
+    upgrade_policy: bool = False
+    auto_approve_session: bool = False
+    tool_scope: str = ""
+    command_prefix: tuple[str, ...] = ()
+    reason: str = ""
+    # What the user said instead of approving. A denial with feedback does
+    # not end the turn: the call is skipped and the model reads this.
+    feedback: str = ""
+
+    @classmethod
+    def allow(
+        cls,
+        *,
+        policy: str | None = None,
+        user_approved: bool = False,
+        upgrade_policy: bool = False,
+        auto_approve_session: bool = False,
+        tool_scope: str = "",
+        command_prefix: tuple[str, ...] = (),
+        reason: str = "",
+    ) -> "ApprovalDecision":
+        return cls(
+            approved=True,
+            policy=policy,
+            user_approved=user_approved,
+            upgrade_policy=upgrade_policy,
+            auto_approve_session=auto_approve_session,
+            tool_scope=tool_scope,
+            command_prefix=command_prefix,
+            reason=reason,
+        )
+
+    @classmethod
+    def deny(cls, reason: str = "", *, feedback: str = "") -> "ApprovalDecision":
+        return cls(approved=False, reason=reason, feedback=feedback.strip())
+
+    def as_declined_result(self) -> dict:
+        """What the model reads in place of a call the user declined with feedback."""
+        return {
+            "success": False,
+            "error": (
+                "The user declined this call and said: "
+                f"\"{self.feedback}\". Do what they asked instead; do not retry the same call."
+            ),
+            "declined_by_user": True,
+        }
+
+
+def apply_approval_decision(params: dict, decision: ApprovalDecision) -> dict:
+    """Apply execution-facing approval fields to tool params."""
+    if decision.policy is not None:
+        params["policy"] = decision.policy
+    if decision.user_approved:
+        params["user_approved"] = True
+    if decision.upgrade_policy:
+        params["_upgrade_policy"] = True
+    return params

aria_code/runtime/baseline.py

@@ -0,0 +1,219 @@
+"""Test baseline: was this check already failing before the change?
+
+A red check sends the model back to repair. When the test was failing before
+the task touched anything, that sends it to "fix" code unrelated to the
+request — or to give up on a task that was actually done. The baseline runs
+the failed command once more on the code as it was before the change and
+compares:
+
+* pytest: by test id (``FAILED tests/x.py::test_y``). Failures that also
+  fail on the baseline are pre-existing; the rest are the change's. The
+  baseline run continues past collection errors (see ``_keep_collecting``).
+* anything else: by exit status. A command that fails on the baseline too
+  is pre-existing as a whole.
+
+"Before the change" is the task's starting snapshot when the turn runs in a
+task worktree. Otherwise it is the working tree now with this turn's edits
+undone from their checkpoints — edits a shell command made are not
+recorded, so they are in the baseline too. Outside a git repository the
+working tree is copied instead of checked out, when it is small enough
+(``_COPY_MAX_FILES``/``_COPY_MAX_BYTES``); without a baseline every failure
+counts as the change's, and the model is sent to "fix" unrelated code.
+
+It runs only after a failure, in a scratch worktree removed straight after,
+and each command at most once per turn.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+import re
+import shutil
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Optional, Union
+
+from .task_worktree import TaskWorktreeError, checkout, remove_checkout, repository_root, snapshot
+
+logger = logging.getLogger(__name__)
+
+_PYTEST_FAILURE = re.compile(r"^(?:FAILED|ERROR)\s+(\S+?)(?:\s+-\s|$)", re.MULTILINE)
+
+# A workspace outside git is copied for its baseline only up to this size; a
+# turn started in a home directory must not copy the home directory.
+_COPY_MAX_FILES = 5_000
+_COPY_MAX_BYTES = 100 * 1024 * 1024
+_COPY_SKIPPED = frozenset({
+    ".git", ".hg", ".svn", "node_modules", ".venv", "venv", "__pycache__",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", ".tox", ".nox",
+})
+
+# ``(command, cwd) -> run result dict``, as the acceptance gate's runner returns.
+BaselineRunner = Callable[[str, str], Union[dict, Awaitable[dict]]]
+
+
+def failing_tests(output: str) -> frozenset[str]:
+    """pytest's failing test ids, from its short summary lines."""
+    return frozenset(match.group(1) for match in _PYTEST_FAILURE.finditer(output or ""))
+
+
+@dataclass(frozen=True)
+class Comparison:
+    preexisting: bool                    # every failure was already there
+    new_failures: tuple[str, ...] = ()   # test ids failing only after the change
+    old_failures: tuple[str, ...] = ()   # test ids failing before it too
+    note: str = ""
+
+
+def compare(after_output: str, after_failed: bool, before: Optional[tuple[int, str]]) -> Comparison:
+    """Classify a failed check against its baseline run ``(exit_code, output)``."""
+    if before is None or not after_failed:
+        return Comparison(preexisting=False)
+    before_code, before_output = before
+    if before_code == 0:
+        return Comparison(preexisting=False, note="passed before this change")
+    after_ids, before_ids = failing_tests(after_output), failing_tests(before_output)
+    if after_ids:
+        new = tuple(sorted(after_ids - before_ids))
+        old = tuple(sorted(after_ids & before_ids))
+        return Comparison(preexisting=not new, new_failures=new, old_failures=old,
+                          note="failing before this change" if not new else "")
+    return Comparison(preexisting=True, note="failing before this change")
+
+
+_PYTEST_COMMAND = re.compile(r"(?:^|[\s/])(?:py\.test|pytest)(?:\s|$)")
+
+
+def _keep_collecting(command: str) -> str:
+    """Let a pytest baseline run past collection errors.
+
+    Before the change a test file often cannot even be imported — it tests the
+    function the task is about to add — and pytest then stops at collection,
+    running nothing else. A test that was already red elsewhere is missing from
+    that baseline, so after the change it would look new and be "repaired".
+    """
+    if (not _PYTEST_COMMAND.search(command) or "--continue-on-collection-errors" in command
+            or re.search(r"[|;&<>`$]", command)):
+        return command
+    return f"{command} --continue-on-collection-errors"
+
+
+class Baseline:
+    def __init__(
+        self,
+        workspace: Path | str,
+        *,
+        run: BaselineRunner,
+        base_commit: str = "",
+        undo_since: Optional[int] = None,
+        session_id: str = "",
+        scratch_root: Path | str,
+    ) -> None:
+        self.workspace = Path(workspace).expanduser().resolve()
+        self.run = run
+        self.base_commit = base_commit
+        self.undo_since = undo_since
+        self.session_id = session_id
+        self.scratch_root = Path(scratch_root).expanduser()
+        self._results: dict[str, Optional[tuple[int, str]]] = {}
+
+    async def result(self, command: str) -> Optional[tuple[int, str]]:
+        """``(exit_code, output)`` of ``command`` before the change; None if unknown."""
+        if command not in self._results:
+            try:
+                self._results[command] = await self._run(_keep_collecting(command))
+            except Exception as exc:
+                logger.debug("baseline run failed: %s", exc)
+                self._results[command] = None
+        return self._results[command]
+
+    async def _run(self, command: str) -> Optional[tuple[int, str]]:
+        repo = repository_root(self.workspace)
+        destination = (self.scratch_root / f"baseline-{uuid.uuid4().hex[:8]}").resolve()
+        if repo is None:
+            if self.base_commit or not self._copy(destination):
+                return None
+            try:
+                self._undo_turn(self.workspace, destination)
+                raw = self.run(command, str(destination))
+                if inspect.isawaitable(raw):
+                    raw = await raw
+            finally:
+                shutil.rmtree(destination, ignore_errors=True)
+            return self._result(raw)
+        commit = self.base_commit or snapshot(repo)[0]
+        linked = checkout(repo, commit, destination)
+        try:
+            if not self.base_commit:
+                self._undo_turn(repo, destination)
+            inside = self.workspace.relative_to(repo) if self.workspace.is_relative_to(repo) else Path()
+            cwd = destination / inside
+            cwd.mkdir(parents=True, exist_ok=True)
+            raw = self.run(command, str(cwd))
+            if inspect.isawaitable(raw):
+                raw = await raw
+        finally:
+            remove_checkout(repo, destination, linked)
+        return self._result(raw)
+
+    @staticmethod
+    def _result(raw: Any) -> tuple[int, str]:
+        from .acceptance import _read_run_result
+
+        code, output, error = _read_run_result(raw)
+        return (code if not error else 1, output)
+
+    def _copy(self, destination: Path) -> bool:
+        """Copy the workspace to ``destination``; False (and nothing left) when too big."""
+        files: list[tuple[Path, Path]] = []
+        total = 0
+        for directory, dirnames, filenames in os.walk(self.workspace):
+            dirnames[:] = [name for name in dirnames if name not in _COPY_SKIPPED]
+            for name in filenames:
+                source = Path(directory) / name
+                if source.is_symlink():
+                    pass   # copied as a link: it may point outside the workspace
+                elif source.is_file():
+                    total += source.stat().st_size
+                else:
+                    continue
+                files.append((source, destination / source.relative_to(self.workspace)))
+                if len(files) > _COPY_MAX_FILES or total > _COPY_MAX_BYTES:
+                    return False
+        try:
+            for source, target in files:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source, target, follow_symlinks=False)
+        except OSError:
+            shutil.rmtree(destination, ignore_errors=True)
+            raise
+        destination.mkdir(parents=True, exist_ok=True)
+        return True
+
+    def _undo_turn(self, repo: Path, destination: Path) -> None:
+        """Put back what this turn's checkpointed edits replaced."""
+        if self.undo_since is None:
+            return
+        from .checkpoints import CheckpointStore
+
+        earliest: dict[str, Any] = {}
+        for record in reversed(CheckpointStore().since(self.undo_since, session_id=self.session_id or None)):
+            for file in record.files:
+                earliest.setdefault(file.path, file)   # oldest change holds the true "before"
+        for path, file in earliest.items():
+            try:
+                relative = Path(path).resolve().relative_to(repo)
+            except ValueError:
+                continue
+            target = destination / relative
+            if file.existed_before:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(file.before_content, encoding="utf-8")
+            elif target.exists():
+                target.unlink()
+
+
+__all__ = ["Baseline", "Comparison", "compare", "failing_tests", "TaskWorktreeError"]

aria_code/runtime/budget.py

@@ -0,0 +1,232 @@
+"""Token / 成本预算：给能自主跑多轮的 agent 一个花费上限。
+
+为什么需要：run_agent() 默认可以跑 30 轮，每轮都可能调云端模型；
+agents/team.py 还会并行拉起多个 agent。这些循环在无人看管时（定时任务、
+飞书 bot、后台 subagent）一旦进入一个"工具失败→重试→再失败"的死循环，
+会持续消耗真金白银，而现有的唯一护栏是轮数上限——轮数管不住单轮消耗，
+一轮塞进 200k token 的上下文和一轮塞进 2k，成本差两个数量级。
+
+设计要点：
+
+1. **本地模型不计费**。ollama / lmstudio / local 的边际成本是零，把它们计入
+   预算只会让本地用户莫名其妙被打断。这跟 /cost 命令已有的判断保持一致。
+
+2. **超限是暂停，不是抛异常**。异常会让调用方拿不到已经产出的中间结果；
+   返回一个明确的"已暂停"状态，调用方可以决定是展示给用户确认后继续，
+   还是就此收尾。这也是 pause/resume 语义能成立的前提。
+
+3. **预检查而非事后补记**。在发起下一轮之前判断"这一轮预计会花多少"，
+   而不是花完了才发现超了——后者每次都会超支一轮。
+
+4. **默认值保守但不碍事**。默认 2.0 美元/会话，够正常交互用很久，又能在
+   死循环烧掉几十美元之前叫停。设成 0 表示不限制（显式选择，不是默认）。
+
+价格表按 2026-08 的公开价格，只用于**估算**：真实账单以各家为准。宁可估高
+不估低——估低会让预算形同虚设。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Tuple
+
+__all__ = [
+    "BudgetConfig", "BudgetState", "BudgetTracker",
+    "BudgetExceeded", "estimate_cost_usd", "is_local_provider",
+]
+
+# 零边际成本的 provider —— 与 /cost 命令的判断保持一致
+_LOCAL_PROVIDERS = frozenset({"ollama", "ollama_cache", "local", "lmstudio"})
+
+# (输入, 输出) 美元 / 每百万 token。取各家公开价格的较高档，宁可估高。
+_PRICE_TABLE: Dict[str, Tuple[float, float]] = {
+    "openai":      (2.50, 10.00),
+    "anthropic":   (3.00, 15.00),
+    "deepseek":    (0.27,  1.10),
+    "groq":        (0.59,  0.79),
+    "siliconflow": (0.27,  1.10),
+    "dashscope":   (0.40,  1.20),
+    "moonshot":    (1.70,  1.70),
+    "zhipu":       (0.10,  0.10),
+    "together":    (0.88,  0.88),
+}
+_DEFAULT_PRICE = (2.00, 8.00)   # 未知 provider（含用户自定义的）按较贵档估
+
+
+def is_local_provider(provider: Optional[str]) -> bool:
+    return (provider or "").strip().lower() in _LOCAL_PROVIDERS
+
+
+def estimate_cost_usd(provider: Optional[str], input_tokens: int, output_tokens: int) -> float:
+    """估算一次调用的美元成本。本地 provider 恒为 0。"""
+    if is_local_provider(provider):
+        return 0.0
+    price_in, price_out = _PRICE_TABLE.get((provider or "").strip().lower(), _DEFAULT_PRICE)
+    return (max(0, input_tokens) * price_in + max(0, output_tokens) * price_out) / 1_000_000
+
+
+@dataclass(frozen=True)
+class BudgetConfig:
+    """预算上限。任一项设为 0 表示该项不限制。"""
+    max_usd: float = 2.0
+    max_tokens: int = 0
+    max_rounds: int = 0
+
+    @classmethod
+    def from_env(cls) -> "BudgetConfig":
+        """环境变量覆盖默认值，便于定时任务/容器里单独收紧或放开。"""
+        def _num(name: str, default: float) -> float:
+            raw = os.environ.get(name, "").strip()
+            if not raw:
+                return default
+            try:
+                return max(0.0, float(raw))
+            except ValueError:
+                return default
+
+        return cls(
+            max_usd=_num("ARIA_BUDGET_MAX_USD", 2.0),
+            max_tokens=int(_num("ARIA_BUDGET_MAX_TOKENS", 0)),
+            max_rounds=int(_num("ARIA_BUDGET_MAX_ROUNDS", 0)),
+        )
+
+    @property
+    def unlimited(self) -> bool:
+        return not (self.max_usd or self.max_tokens or self.max_rounds)
+
+
+@dataclass
+class BudgetState:
+    spent_usd: float = 0.0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    rounds: int = 0
+    billable_calls: int = 0        # 计费调用次数（本地调用不计）
+    per_provider: Dict[str, float] = field(default_factory=dict)
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+class BudgetExceeded(RuntimeError):
+    """仅供确实需要硬中断的调用方使用。默认路径不抛这个——见模块文档第 2 点。"""
+
+    def __init__(self, reason: str, state: BudgetState):
+        super().__init__(reason)
+        self.reason = reason
+        self.state = state
+
+
+class BudgetTracker:
+    """累计消耗并回答"还能不能再跑一轮"。
+
+    刻意不持有任何 provider 或循环对象：它只接收数字、返回判断，因此可以在
+    CLI 会话、后台 subagent、agents.team 并行编排里用同一套逻辑，也容易测试。
+    """
+
+    def __init__(self, config: Optional[BudgetConfig] = None):
+        self.config = config or BudgetConfig.from_env()
+        self.state = BudgetState()
+        self._paused_reason: Optional[str] = None
+
+    # ── 记账 ──────────────────────────────────────────────────────────
+    def record(self, provider: Optional[str], input_tokens: int, output_tokens: int) -> float:
+        """记录一次模型调用，返回本次估算成本。"""
+        cost = estimate_cost_usd(provider, input_tokens, output_tokens)
+        self.state.input_tokens += max(0, input_tokens)
+        self.state.output_tokens += max(0, output_tokens)
+        self.state.spent_usd += cost
+        if cost > 0:
+            self.state.billable_calls += 1
+            key = (provider or "unknown").strip().lower()
+            self.state.per_provider[key] = self.state.per_provider.get(key, 0.0) + cost
+        return cost
+
+    def record_round(self) -> None:
+        self.state.rounds += 1
+
+    def projected_next_round_usd(self) -> float:
+        """按已观测到的平均单轮成本，预测下一轮会花多少。
+
+        没有这个预测，闸门只能事后止损：$1 的预算实测会花到 $1.275——超支的
+        正是最后那一轮，而它恰恰可能是上下文最满、最贵的一轮。用历史均值做
+        预测，能在**发起调用之前**就拦住。
+
+        还没有任何计费轮次时返回 0（没有依据就不猜，第一轮总是放行）。
+
+        因此**第一轮永远无法被预算拦住**——预算比单轮成本还低时会超支一次。
+        这是有意的：宁可放行第一轮，也不要因为一个凭空的猜测把正常会话
+        堵死在起点。真要限制到单轮以下，应该用更小的模型或更短的上下文，
+        而不是指望预算闸门。
+        """
+        if self.state.rounds <= 0 or self.state.spent_usd <= 0:
+            return 0.0
+        return self.state.spent_usd / self.state.rounds
+
+    # ── 判断 ──────────────────────────────────────────────────────────
+    def check(self, *, projected_usd: float = 0.0, projected_tokens: int = 0) -> Optional[str]:
+        """返回超限原因；未超限返回 None。
+
+        projected_* 是"下一轮预计消耗"。传入它就变成**预检查**——在花掉之前
+        拦住，而不是花完才发现超了（后者每次都会超支一轮）。
+        """
+        cfg = self.config
+        if cfg.unlimited:
+            return None
+
+        if cfg.max_usd:
+            projected = self.state.spent_usd + max(0.0, projected_usd)
+            if projected >= cfg.max_usd:
+                return (f"预算上限 ${cfg.max_usd:.2f} 已达到"
+                        f"（已用 ${self.state.spent_usd:.4f}"
+                        f"{f'，本轮预计 ${projected_usd:.4f}' if projected_usd else ''}）")
+
+        if cfg.max_tokens:
+            projected_tok = self.state.total_tokens + max(0, projected_tokens)
+            if projected_tok >= cfg.max_tokens:
+                return (f"token 上限 {cfg.max_tokens:,} 已达到"
+                        f"（已用 {self.state.total_tokens:,}）")
+
+        if cfg.max_rounds and self.state.rounds >= cfg.max_rounds:
+            return f"轮数上限 {cfg.max_rounds} 已达到"
+
+        return None
+
+    def should_continue(self, *, projected_usd: float = 0.0, projected_tokens: int = 0) -> bool:
+        reason = self.check(projected_usd=projected_usd, projected_tokens=projected_tokens)
+        if reason:
+            self._paused_reason = reason
+        return reason is None
+
+    # ── 状态 ──────────────────────────────────────────────────────────
+    @property
+    def paused(self) -> bool:
+        return self._paused_reason is not None
+
+    @property
+    def paused_reason(self) -> Optional[str]:
+        return self._paused_reason
+
+    def resume(self, *, additional_usd: float = 0.0) -> None:
+        """用户确认后继续。可选地追加额度——不追加就会在下一次检查时再次暂停，
+        这是刻意的：确认一次只放行一次，避免"确认后无限继续"。
+        """
+        self._paused_reason = None
+        if additional_usd > 0:
+            self.config = BudgetConfig(
+                max_usd=self.config.max_usd + additional_usd,
+                max_tokens=self.config.max_tokens,
+                max_rounds=self.config.max_rounds,
+            )
+
+    def summary(self) -> str:
+        s = self.state
+        parts = [f"${s.spent_usd:.4f}", f"{s.total_tokens:,} tokens", f"{s.rounds} 轮"]
+        if self.config.max_usd:
+            pct = (s.spent_usd / self.config.max_usd * 100) if self.config.max_usd else 0
+            parts.append(f"用量 {pct:.0f}% / ${self.config.max_usd:.2f}")
+        if not s.billable_calls and s.total_tokens:
+            parts.append("（全部走本地模型，零成本）")
+        return " · ".join(parts)