windcode 0.1.0__py3-none-any.whl

windcode/runtime/prompts.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from windcode.config import DelegationMode, PermissionMode
+from windcode.instructions import InstructionBlock
+from windcode.tools import ToolRegistry
+
+if TYPE_CHECKING:
+    from windcode.extensions.skills.tools import SkillSearchResult
+
+
+def build_system_prompt(
+    *,
+    workspace: Path,
+    permission_mode: PermissionMode,
+    instructions: tuple[InstructionBlock, ...],
+    tools: ToolRegistry,
+    delegation_mode: DelegationMode | None = None,
+    is_subagent: bool = False,
+    skills: tuple[SkillSearchResult, ...] = (),
+    mcp_direct_servers: tuple[str, ...] = (),
+    mcp_search_servers: tuple[str, ...] = (),
+    mcp_unavailable_servers: tuple[tuple[str, str], ...] = (),
+    memory_enabled: bool = False,
+) -> str:
+    tool_lines = "\n".join(f"- {schema.name}: {schema.description}" for schema in tools.schemas())
+    instruction_sections = "\n\n".join(
+        f"### {block.path}\n{block.content.rstrip()}" for block in instructions
+    )
+    extension_sections = ""
+    if skills:
+        skill_lines = "\n".join(
+            f"- ${item.name}: {item.description} [source: {item.source_id}]" for item in skills
+        )
+        extension_sections += (
+            f"\n\n## Agent Skills\n{skill_lines}\n"
+            "需要某个明确匹配的 Skill 时直接调用 load_skill, 不确定时最多调用一次 "
+            "search_skills 后选择准确名称加载。不得尝试加载列表之外、未启用或未信任的 Skill; "
+            "同一 Skill 不得重复加载。用户以 $name 显式选择的 Skill 已由运行时加载, "
+            "无需再次调用 load_skill。"
+        )
+    if mcp_direct_servers:
+        server_lines = "\n".join(f"- {server_id}" for server_id in sorted(mcp_direct_servers))
+        extension_sections += (
+            f"\n\n## MCP 服务器 (工具已直接可用)\n{server_lines}\n"
+            "这些服务器的工具已列在上方“可用工具”中, 直接按名称调用即可, "
+            "无需再调用 search_mcp_tools 搜索或启用。"
+        )
+    if mcp_search_servers:
+        server_lines = "\n".join(f"- {server_id}" for server_id in sorted(mcp_search_servers))
+        extension_sections += (
+            f"\n\n## MCP 服务器 (按需启用)\n{server_lines}\n"
+            "先检查上方可用工具; 已存在目标 MCP 工具时必须直接调用, 不得重复搜索。"
+            "目标尚不可用时调用一次 search_mcp_tools 并传关键词; 唯一匹配会自动启用并返回 "
+            "call_name, 随后直接调用它。只有返回多个匹配时, 才再调用一次 "
+            "search_mcp_tools(query='select:<id>') 选择目标。已启用工具会在后续运行中复用。"
+        )
+    if mcp_unavailable_servers:
+        server_lines = "\n".join(
+            f"- {server_id}: {reason}" for server_id, reason in sorted(mcp_unavailable_servers)
+        )
+        extension_sections += (
+            f"\n\n## MCP 服务器 (本次运行不可用)\n{server_lines}\n"
+            "这些服务器已经配置, 因此不得声称 Windcode 没有 MCP 集成。"
+            "它们当前不能调用; 可使用 list_mcp_servers 核实状态, 并向用户准确说明原因。"
+        )
+    delegation = ""
+    if is_subagent:
+        delegation = (
+            "\n\n## 子智能体约束\n"
+            "你是单层临时子智能体, 只执行收到的自包含任务; 不得继续委派, 也不得直接询问用户。"
+        )
+    elif delegation_mode is DelegationMode.EXPLICIT:
+        delegation = (
+            "\n\n## 委派策略: explicit\n"
+            "仅当用户明确要求委派、并行或使用子智能体时, 才可调用子智能体工具。"
+            "创建后调用 wait_subagents 一次等待结果; 禁止循环调用 list_subagents。"
+            "子智能体可按运行网络策略和权限审批访问外部网络。"
+        )
+    elif delegation_mode is DelegationMode.PROACTIVE:
+        delegation = (
+            "\n\n## 委派策略: proactive\n"
+            "可在任务确实独立且适合并行时主动委派; 必须保持任务有界、状态可见并统一汇总。"
+            "创建后调用 wait_subagents 一次等待结果; 禁止循环调用 list_subagents。"
+            "子智能体可按运行网络策略和权限审批访问外部网络。"
+        )
+    if memory_enabled:
+        memory_policy = (
+            "\n\n## 长期记忆主动查询\n"
+            "当用户明确要求记住、写入长期记忆或表达等价意图时, 必须调用 "
+            "memory_write。只有工具返回 stored 或 already_exists 后才能声称已经记住; "
+            "工具失败、未调用或仅计划保存时不得声称写入成功。不得擅自保存普通对话、"
+            "临时状态、推测或工具输出。"
+            "当用户明确要求查看、列出、搜索、核对或回忆长期记忆时, 必须调用 memory_list、"
+            "memory_search 或 memory_get, 并基于工具实际结果回答。宽泛的‘看看长期记忆’调用 "  # noqa: RUF001
+            "memory_list; 带主题的请求调用 memory_search; 查看单条详情调用 memory_get。"
+            "memory_list 和 memory_search 默认同时返回 active 与 candidate; 回答时必须明确区分"
+            "已生效记忆和待确认候选, 不得因候选未注入自动上下文而声称记录不存在。"
+            "不得使用 glob、grep、read_file、shell 或其他工作区工具代替长期记忆查询。"
+            "自动注入的记忆只用于当前任务上下文, 不能冒充主动查询结果。"
+            "搜索无结果时直接说明没有匹配记忆, 不得转而扫描仓库。"
+        )
+    else:
+        memory_policy = (
+            "\n\n## 长期记忆主动查询\n"
+            "本次运行未启用长期记忆工具。用户要求查看长期记忆时应准确说明长期记忆已禁用或"
+            "不可用, 不得搜索工作区文件来代替记忆查询。"
+        )
+    return (
+        "你是 Windcode, 在终端中帮助用户完成软件工程任务的本地编码 Agent.\n"
+        "最终面向用户的回复可使用 GitHub 风格 Markdown。仅在有助于阅读时使用标题、"
+        "列表、表格、引用、强调、行内代码和围栏代码块; 保持结构克制且内容简洁。\n"
+        "先判断用户是否提出了明确且需要项目上下文的编码任务. "
+        "对于问候、闲聊、一般知识问题或不涉及当前项目的问题, 直接回答, "
+        "不得读取文件、执行命令、搜索或以任何方式检查工作区.\n"
+        "只有在用户明确请求的任务确实需要项目上下文时才使用工具; "
+        "不要为了了解项目而主动勘察工作区. 如果任务意图不明确, 先向用户提一个简短问题.\n"
+        "明确的编码任务一旦开始, 持续执行到任务完成、取消、预算耗尽或不可恢复错误.\n"
+        "所有工具错误都应作为结果处理; 不要虚构文件内容、命令结果或测试通过状态.\n"
+        "完成时必须基于实际工具记录汇总文件变化、验证命令、退出码和失败项.\n\n"
+        "不要输出任何的emoji、表情符号或非 ASCII 字符"
+        f"工作区: {workspace.resolve()}\n"
+        f"权限模式: {permission_mode.value}. 模型不得自行扩大权限或切换模式.\n\n"
+        f"## 可用工具\n{tool_lines or '- 无'}\n\n"
+        f"## 项目指令 (按根目录到当前目录排列, 后者优先)\n"
+        f"{instruction_sections or '无项目指令'}"
+        f"{extension_sections}"
+        f"{memory_policy}"
+        f"{delegation}"
+    )

windcode/runtime/report.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, cast
+
+from windcode.domain.events import RunResult
+from windcode.domain.models import Usage
+from windcode.domain.tools import ToolResult
+
+_TEST_COMMAND = re.compile(r"(?:^|\s)(?:pytest|pyright|ruff|npm\s+test|pnpm\s+test|cargo\s+test)\b")
+
+
+@dataclass(frozen=True, slots=True)
+class ToolExecutionRecord:
+    tool_name: str
+    arguments: Mapping[str, Any]
+    result: ToolResult
+
+
+def build_run_result(
+    final_text: str,
+    records: tuple[ToolExecutionRecord, ...],
+    *,
+    usage: Usage | None = None,
+) -> RunResult:
+    changed_files: list[str] = []
+    verification: list[str] = []
+    failed_verification = False
+    for record in records:
+        path = record.result.data.get("path")
+        action = record.result.data.get("action")
+        if isinstance(path, str) and isinstance(action, str) and path not in changed_files:
+            changed_files.append(path)
+        changes = record.result.data.get("changes")
+        if isinstance(changes, list):
+            raw_changes = cast(list[object], changes)
+            for change in raw_changes:
+                if isinstance(change, Mapping):
+                    raw_change = cast(Mapping[object, object], change)
+                    changed_path = raw_change.get("path")
+                    if isinstance(changed_path, str) and changed_path not in changed_files:
+                        changed_files.append(changed_path)
+        if record.tool_name == "shell":
+            command = record.arguments.get("command")
+            exit_code = record.result.data.get("exit_code")
+            if isinstance(command, str) and _TEST_COMMAND.search(command):
+                verification.append(f"{command} (exit {exit_code})")
+                failed_verification = failed_verification or exit_code != 0
+
+    if failed_verification:
+        status = "failed"
+    elif changed_files and not verification:
+        status = "unverified"
+    else:
+        status = "completed"
+    return RunResult(
+        status=status,
+        final_text=final_text,
+        changed_files=tuple(changed_files),
+        verification=tuple(verification),
+        usage=usage or Usage(),
+    )

windcode/runtime/retry.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import asyncio
+import random
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import replace
+from typing import cast
+
+from windcode.domain.errors import WindcodeError
+from windcode.domain.messages import Message, ReasoningBlock
+from windcode.domain.models import ModelEvent, ModelRequest
+from windcode.providers import ModelTarget
+from windcode.providers.errors import map_provider_error
+
+RetryCallback = Callable[[ModelTarget, int, WindcodeError], Awaitable[None]]
+FallbackCallback = Callable[[ModelTarget, ModelTarget, WindcodeError], Awaitable[None]]
+SleepCallback = Callable[[float], Awaitable[None]]
+
+
+def portable_messages(messages: tuple[Message, ...]) -> tuple[Message, ...]:
+    portable: list[Message] = []
+    for message in messages:
+        content = tuple(
+            replace(block, opaque={}) if isinstance(block, ReasoningBlock) else block
+            for block in message.content
+        )
+        portable.append(replace(message, content=content, provider_metadata={}))
+    return tuple(portable)
+
+
+async def stream_with_retry(
+    chain: tuple[ModelTarget, ...],
+    request: ModelRequest,
+    *,
+    on_retry: RetryCallback,
+    on_fallback: FallbackCallback,
+    max_retries: int = 2,
+    sleep: SleepCallback = asyncio.sleep,
+) -> AsyncIterator[tuple[ModelTarget, ModelEvent]]:
+    if not chain:
+        raise ValueError("model chain cannot be empty")
+    current_request: ModelRequest = request
+    for target_index, target in enumerate(chain):
+        attempts = 0
+        while True:
+            provider_request = replace(current_request, model=target.model)
+            try:
+                async for event in target.transport.stream(provider_request):
+                    yield target, event
+                return
+            except BaseException as exc:
+                if isinstance(exc, asyncio.CancelledError):
+                    raise
+                error = map_provider_error(exc)
+                if error.retryable and attempts < max_retries:
+                    attempts += 1
+                    await on_retry(target, attempts, error)
+                    delay = min(4.0, 0.25 * (2 ** (attempts - 1)))
+                    await sleep(delay * random.uniform(0.8, 1.2))
+                    continue
+                has_fallback = target_index + 1 < len(chain)
+                if error.fallback_allowed and has_fallback:
+                    fallback = chain[target_index + 1]
+                    await on_fallback(target, fallback, error)
+                    current_request = cast(
+                        ModelRequest,
+                        replace(
+                            current_request,
+                            messages=portable_messages(current_request.messages),
+                        ),
+                    )
+                    break
+                raise error from exc

windcode/runtime/scheduler.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+from uuid import uuid4
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.policy import (
+    ApprovalChoice,
+    PolicyAction,
+    PolicyDecision,
+    PolicyEngine,
+    PolicyRequest,
+)
+from windcode.tools.filesystem import resolve_path
+from windcode.tools.registry import ToolRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledCall:
+    call_id: str
+    tool_name: str
+    arguments: Mapping[str, Any]
+    origin: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledResult:
+    call_id: str
+    result: ToolResult
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyConstraints:
+    additional_effects: frozenset[ToolEffect] = frozenset()
+    reject_reason: str | None = None
+
+
+ApprovalHandler = Callable[[PolicyRequest, PolicyDecision], Awaitable[ApprovalChoice]]
+BeforeExecute = Callable[[ScheduledCall, PolicyRequest], Awaitable[None]]
+BeforePolicy = Callable[[ScheduledCall, ToolContext], Awaitable[PolicyConstraints]]
+PermissionObserver = Callable[[ScheduledCall, PolicyRequest, PolicyDecision], Awaitable[None]]
+AfterExecute = Callable[[ScheduledCall, PolicyRequest, ToolResult], Awaitable[None]]
+SessionApprovalRecorder = Callable[[PolicyRequest], None]
+
+
+class ToolScheduler:
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        policy: PolicyEngine,
+        *,
+        approval_handler: ApprovalHandler | None = None,
+        before_execute: BeforeExecute | None = None,
+        before_policy: BeforePolicy | None = None,
+        permission_observer: PermissionObserver | None = None,
+        after_execute: AfterExecute | None = None,
+        session_approval_recorder: SessionApprovalRecorder | None = None,
+    ) -> None:
+        self.registry = registry
+        self.policy = policy
+        self.approval_handler = approval_handler
+        self.before_execute = before_execute
+        self.before_policy = before_policy
+        self.permission_observer = permission_observer
+        self.after_execute = after_execute
+        self.session_approval_recorder = session_approval_recorder
+
+    def _policy_request(
+        self,
+        call: ScheduledCall,
+        context: ToolContext,
+        additional_effects: frozenset[ToolEffect] = frozenset(),
+    ) -> PolicyRequest:
+        tool = self.registry.get(call.tool_name)
+        effects = set(tool.effects)
+        effects.update(additional_effects)
+        raw_path = call.arguments.get("path")
+        path = str(raw_path) if isinstance(raw_path, str) else None
+        if path is not None and not resolve_path(context.workspace, path).inside_workspace:
+            effects.add(ToolEffect.OUTSIDE_WORKSPACE)
+        if call.tool_name == "shell" and call.arguments.get("network") is True:
+            effects.add(ToolEffect.NETWORK)
+        command = call.arguments.get("command")
+        safe_command = command if isinstance(command, str) else None
+        return PolicyRequest(
+            request_id=uuid4().hex,
+            call_id=call.call_id,
+            tool_name=call.tool_name,
+            effects=frozenset(effects),
+            summary=f"执行工具: {call.tool_name}",
+            path=path,
+            command=safe_command,
+        )
+
+    async def _execute_one(self, call: ScheduledCall, context: ToolContext) -> ScheduledResult:
+        try:
+            constraints = (
+                await self.before_policy(call, context)
+                if self.before_policy is not None
+                else PolicyConstraints()
+            )
+            if constraints.reject_reason is not None:
+                return ScheduledResult(
+                    call.call_id,
+                    ToolResult(
+                        constraints.reject_reason,
+                        is_error=True,
+                        data={"error": "extension_rejected"},
+                    ),
+                )
+            request = self._policy_request(call, context, constraints.additional_effects)
+        except KeyError as exc:
+            return ScheduledResult(
+                call.call_id,
+                ToolResult(
+                    output=str(exc),
+                    is_error=True,
+                    data={"error": "unknown_tool", "tool": call.tool_name},
+                ),
+            )
+        decision = self.policy.evaluate(request)
+        if self.permission_observer is not None:
+            await self.permission_observer(call, request, decision)
+        if decision.action is PolicyAction.DENY:
+            return ScheduledResult(
+                call.call_id,
+                ToolResult(
+                    output=decision.reason,
+                    is_error=True,
+                    data={"error": "policy_denied", "risk": decision.risk.value},
+                ),
+            )
+        if decision.action is PolicyAction.ASK:
+            if self.approval_handler is None:
+                return ScheduledResult(
+                    call.call_id,
+                    ToolResult(
+                        output=decision.reason,
+                        is_error=True,
+                        data={"error": "approval_required", "risk": decision.risk.value},
+                    ),
+                )
+            choice = await self.approval_handler(request, decision)
+            if choice is ApprovalChoice.DENY:
+                return ScheduledResult(
+                    call.call_id,
+                    ToolResult(
+                        output="user denied the operation",
+                        is_error=True,
+                        data={"error": "approval_denied"},
+                    ),
+                )
+            if choice is ApprovalChoice.ALLOW_SESSION:
+                self.policy.approve_for_session(request)
+                if self.session_approval_recorder is not None:
+                    self.session_approval_recorder(request)
+        if self.before_execute is not None:
+            await self.before_execute(call, request)
+        result = await self.registry.execute(call.tool_name, context, call.arguments)
+        if self.after_execute is not None:
+            await self.after_execute(call, request, result)
+        return ScheduledResult(call.call_id, result)
+
+    def _is_read_only(self, call: ScheduledCall) -> bool:
+        try:
+            return self.registry.get(call.tool_name).effects <= {ToolEffect.READ}
+        except KeyError:
+            return False
+
+    async def execute(
+        self,
+        calls: tuple[ScheduledCall, ...],
+        context: ToolContext,
+    ) -> tuple[ScheduledResult, ...]:
+        results: list[ScheduledResult] = []
+        index = 0
+        while index < len(calls):
+            if not self._is_read_only(calls[index]):
+                results.append(await self._execute_one(calls[index], context))
+                index += 1
+                continue
+            end = index
+            while end < len(calls) and self._is_read_only(calls[end]):
+                end += 1
+            batch = calls[index:end]
+            batch_results = await asyncio.gather(
+                *(self._execute_one(call, context) for call in batch)
+            )
+            results.extend(batch_results)
+            index = end
+        return tuple(results)

windcode/runtime/subagents/__init__.py

@@ -0,0 +1,28 @@
+from windcode.runtime.subagents.approvals import ApprovalRouter
+from windcode.runtime.subagents.budgets import (
+    AggregateBudget,
+    AggregateBudgetExceeded,
+    AggregateUsage,
+)
+from windcode.runtime.subagents.coordinator import (
+    SubagentCoordinator,
+    SubagentCoordinatorError,
+)
+from windcode.runtime.subagents.factory import ChildRuntime, ChildRuntimeFactory
+from windcode.runtime.subagents.roles import ROLE_POLICIES, RolePolicy, resolve_role_tools
+from windcode.runtime.subagents.verification import VerificationRunner
+
+__all__ = [
+    "ROLE_POLICIES",
+    "AggregateBudget",
+    "AggregateBudgetExceeded",
+    "AggregateUsage",
+    "ApprovalRouter",
+    "ChildRuntime",
+    "ChildRuntimeFactory",
+    "RolePolicy",
+    "SubagentCoordinator",
+    "SubagentCoordinatorError",
+    "VerificationRunner",
+    "resolve_role_tools",
+]

windcode/runtime/subagents/approvals.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from uuid import uuid4
+
+from windcode.domain.events import ApprovalRequested, ApprovalResponse
+from windcode.domain.subagents import SubagentRole
+from windcode.policy.models import (
+    ApprovalChoice,
+    PolicyDecision,
+    PolicyRequest,
+    summarize_policy_arguments,
+)
+
+
+@dataclass(slots=True)
+class _PendingApproval:
+    subagent_id: str
+    future: asyncio.Future[ApprovalChoice]
+
+
+class ApprovalRouter:
+    def __init__(
+        self,
+        *,
+        parent_session_id: str,
+        parent_run_id: str,
+        publish: Callable[[ApprovalRequested], Awaitable[None]],
+    ) -> None:
+        self.parent_session_id = parent_session_id
+        self.parent_run_id = parent_run_id
+        self.publish = publish
+        self._pending: dict[str, _PendingApproval] = {}
+
+    async def request(
+        self,
+        subagent_id: str,
+        role: SubagentRole,
+        request: PolicyRequest,
+        decision: PolicyDecision,
+    ) -> ApprovalChoice:
+        parent_request_id = uuid4().hex
+        future: asyncio.Future[ApprovalChoice] = asyncio.get_running_loop().create_future()
+        self._pending[parent_request_id] = _PendingApproval(subagent_id, future)
+        arguments_summary = summarize_policy_arguments(request)
+        try:
+            await self.publish(
+                ApprovalRequested(
+                    event_id=uuid4().hex,
+                    session_id=self.parent_session_id,
+                    run_id=self.parent_run_id,
+                    turn=0,
+                    request_id=parent_request_id,
+                    summary=request.summary,
+                    risk=decision.risk.value,
+                    choices=tuple(choice.value for choice in decision.choices),
+                    subagent_id=subagent_id,
+                    subagent_role=role.value,
+                    tool_name=request.tool_name,
+                    arguments_summary=arguments_summary,
+                )
+            )
+            return await future
+        finally:
+            self._pending.pop(parent_request_id, None)
+
+    def respond(self, response: ApprovalResponse) -> None:
+        try:
+            pending = self._pending[response.request_id]
+        except KeyError as exc:
+            raise ValueError(f"no pending subagent approval: {response.request_id}") from exc
+        try:
+            choice = ApprovalChoice(response.decision)
+        except ValueError:
+            choice = ApprovalChoice.DENY
+        if not pending.future.done():
+            pending.future.set_result(choice)
+
+    def cancel(self, subagent_id: str) -> None:
+        for pending in tuple(self._pending.values()):
+            if pending.subagent_id == subagent_id and not pending.future.done():
+                pending.future.cancel()
+
+    @property
+    def pending_count(self) -> int:
+        return len(self._pending)

windcode/runtime/subagents/budgets.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from time import monotonic
+
+
+class AggregateBudgetExceeded(RuntimeError):
+    def __init__(self, budget: str) -> None:
+        self.scope = "aggregate"
+        self.budget = budget
+        super().__init__(f"aggregate subagent budget exhausted: {budget}")
+
+
+@dataclass(frozen=True, slots=True)
+class AggregateUsage:
+    model_steps: int
+    tool_calls: int
+    runtime_seconds: float
+
+
+class AggregateBudget:
+    def __init__(
+        self,
+        *,
+        max_model_steps: int,
+        max_tool_calls: int,
+        max_runtime_seconds: float,
+    ) -> None:
+        self.max_model_steps = max_model_steps
+        self.max_tool_calls = max_tool_calls
+        self.max_runtime_seconds = max_runtime_seconds
+        self._model_steps = 0
+        self._tool_calls = 0
+        self._started_at = monotonic()
+        self._lock = asyncio.Lock()
+
+    async def consume_model_step(self) -> None:
+        async with self._lock:
+            self.consume_model_step_nowait()
+
+    async def consume_tool_calls(self, count: int = 1) -> None:
+        if count < 1:
+            raise ValueError("tool call count must be positive")
+        async with self._lock:
+            self.consume_tool_calls_nowait(count)
+
+    async def check_runtime(self) -> None:
+        async with self._lock:
+            self._check_runtime_unlocked()
+
+    async def usage(self) -> AggregateUsage:
+        async with self._lock:
+            return AggregateUsage(
+                model_steps=self._model_steps,
+                tool_calls=self._tool_calls,
+                runtime_seconds=max(0.0, monotonic() - self._started_at),
+            )
+
+    def _check_runtime_unlocked(self) -> None:
+        if monotonic() - self._started_at >= self.max_runtime_seconds:
+            raise AggregateBudgetExceeded("runtime_seconds")
+
+    def check_runtime_nowait(self) -> None:
+        self._check_runtime_unlocked()
+
+    def consume_model_step_nowait(self) -> None:
+        self._check_runtime_unlocked()
+        if self._model_steps >= self.max_model_steps:
+            raise AggregateBudgetExceeded("model_steps")
+        self._model_steps += 1
+
+    def consume_tool_calls_nowait(self, count: int = 1) -> None:
+        if count < 1:
+            raise ValueError("tool call count must be positive")
+        self._check_runtime_unlocked()
+        if self._tool_calls + count > self.max_tool_calls:
+            raise AggregateBudgetExceeded("tool_calls")
+        self._tool_calls += count