Przeglądaj źródła

feat: Phase 3 — P2 competitiveness improvements (T18-T22)

- T18: AgentTracer — OpenTelemetry-compatible tracing (graceful degradation)
- T19: TokenBudget — token consumption tracking and enforcement
- T20: ConcurrentTool — concurrency safety declarations for tools
- T21: RateLimiter — token bucket rate limiting (sync + async)
- T22: ResilientMCPClient — circuit breaker, retry, tool discovery cache
- 21 integration tests (all passing)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
kenny67nju 7 miesięcy temu
rodzic
commit
1d4199c549

+ 1 - 1
ENGINEERING_GAP_ANALYSIS.md

@@ -1257,7 +1257,7 @@ Phase 3 (P2): 竞争力提升                  [4-6 周]
 
 ### Phase 3: P2 竞争力提升 + 安全加固
 
-- [ ] **T18: OpenTelemetry 集成** [2d]
+- [x] **T18: OpenTelemetry 集成** [2d]
   - `InstrumentedExecutor`: 每个 reduce 步骤生成 span
   - Attributes: term.name, input.length, tokens.used, duration_ms
   - 依赖: T03

+ 43 - 0
lambdagent/concurrent_tools.py

@@ -0,0 +1,43 @@
+"""
+lambdagent.concurrent_tools — Tool concurrency safety declarations
+
+Tools can declare whether they are safe for concurrent execution.
+The executor uses this to parallelize safe tools and serialize unsafe ones.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, List
+from .core import Term, Context
+from .primitives import Tool
+
+
+class ConcurrentTool(Tool):
+    """Tool with explicit concurrency safety declaration."""
+
+    def __init__(self, name: str, fn: Callable, concurrent_safe: bool = False,
+                 description: str = ""):
+        super().__init__(name, fn)
+        self.concurrent_safe = concurrent_safe
+        self.description = description
+
+
+def partition_by_safety(tools: List[ConcurrentTool]) -> tuple:
+    """Split tools into (safe, unsafe) groups.
+
+    Returns:
+        (safe_tools, unsafe_tools) - safe can run in parallel, unsafe must be sequential
+    """
+    safe = [t for t in tools if getattr(t, 'concurrent_safe', False)]
+    unsafe = [t for t in tools if not getattr(t, 'concurrent_safe', False)]
+    return safe, unsafe
+
+
+# Pre-built concurrent-safe tool constructors
+def read_tool(name: str, fn: Callable) -> ConcurrentTool:
+    """Create a read-only (concurrent-safe) tool."""
+    return ConcurrentTool(name, fn, concurrent_safe=True)
+
+def write_tool(name: str, fn: Callable) -> ConcurrentTool:
+    """Create a write (not concurrent-safe) tool."""
+    return ConcurrentTool(name, fn, concurrent_safe=False)

+ 142 - 0
lambdagent/observability.py

@@ -0,0 +1,142 @@
+"""
+lambdagent.observability — Structured observability for agent execution
+
+Provides OpenTelemetry-compatible tracing for β-reductions.
+Works without otel dependency (graceful degradation to no-op).
+"""
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class SpanRecord:
+    """A single tracing span."""
+    name: str
+    start_time: float
+    end_time: float = 0
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    status: str = "ok"
+    parent_id: Optional[str] = None
+    span_id: str = ""
+
+    @property
+    def duration_ms(self) -> float:
+        return (self.end_time - self.start_time) * 1000
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "span_id": self.span_id,
+            "parent_id": self.parent_id,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "duration_ms": self.duration_ms,
+            "attributes": self.attributes,
+            "status": self.status,
+        }
+
+
+class AgentTracer:
+    """Lightweight tracer for agent execution.
+
+    Collects spans locally. Can export to OpenTelemetry if available.
+    """
+
+    def __init__(self, service_name: str = "lambdagent"):
+        self.service_name = service_name
+        self.spans: list[SpanRecord] = []
+        self._otel_tracer = None
+        self._span_counter = 0
+        self._try_init_otel()
+
+    def _try_init_otel(self):
+        """Try to initialize OpenTelemetry tracer. No-op if not installed."""
+        try:
+            from opentelemetry import trace
+            self._otel_tracer = trace.get_tracer(self.service_name)
+        except ImportError:
+            pass
+
+    def _next_id(self) -> str:
+        self._span_counter += 1
+        return f"span_{self._span_counter:06d}"
+
+    @contextmanager
+    def span(self, name: str, parent_id: Optional[str] = None, **attributes):
+        """Create a tracing span."""
+        span_id = self._next_id()
+        record = SpanRecord(
+            name=name,
+            start_time=time.time(),
+            span_id=span_id,
+            parent_id=parent_id,
+            attributes=attributes,
+        )
+
+        # OTel span if available
+        otel_span = None
+        otel_ctx = None
+        if self._otel_tracer:
+            try:
+                otel_span = self._otel_tracer.start_span(name, attributes=attributes)
+                otel_ctx = otel_span
+            except Exception:
+                pass
+
+        try:
+            yield record
+            record.status = "ok"
+        except Exception as e:
+            record.status = f"error: {type(e).__name__}"
+            record.attributes["error"] = str(e)
+            raise
+        finally:
+            record.end_time = time.time()
+            self.spans.append(record)
+            if otel_span:
+                try:
+                    for k, v in record.attributes.items():
+                        otel_span.set_attribute(str(k), str(v) if not isinstance(v, (int, float, bool)) else v)
+                    otel_span.end()
+                except Exception:
+                    pass
+
+    def record_reduction(self, term_name: str, term_type: str, input_val: Any,
+                        output_val: Any, duration_ms: float, model: str = "",
+                        tokens: int = 0, parent_id: str = None):
+        """Record a β-reduction as a span."""
+        self.spans.append(SpanRecord(
+            name=f"reduce.{term_type}.{term_name}",
+            start_time=time.time() - duration_ms / 1000,
+            end_time=time.time(),
+            span_id=self._next_id(),
+            parent_id=parent_id,
+            attributes={
+                "term.name": term_name,
+                "term.type": term_type,
+                "input.length": len(str(input_val)),
+                "output.length": len(str(output_val)),
+                "model": model,
+                "tokens.used": tokens,
+                "duration_ms": duration_ms,
+            },
+        ))
+
+    def export_json(self) -> list:
+        """Export all spans as JSON-serializable list."""
+        return [s.to_dict() for s in self.spans]
+
+    def summary(self) -> str:
+        """Human-readable summary of traced execution."""
+        if not self.spans:
+            return "No spans recorded."
+        total_ms = sum(s.duration_ms for s in self.spans)
+        lines = [f"Trace: {len(self.spans)} spans, {total_ms:.0f}ms total"]
+        for s in self.spans:
+            status = "\u2713" if s.status == "ok" else "\u2717"
+            lines.append(f"  {status} {s.name} ({s.duration_ms:.0f}ms)")
+        return "\n".join(lines)

+ 97 - 0
lambdagent/rate_limiter.py

@@ -0,0 +1,97 @@
+"""
+lambdagent.rate_limiter — Token bucket rate limiter for LLM API calls
+
+Prevents API rate limit errors by throttling requests.
+Supports both sync and async usage.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+
+
+class RateLimiter:
+    """Token bucket rate limiter.
+
+    Usage:
+        limiter = RateLimiter(requests_per_minute=60)
+        limiter.acquire()  # blocks if rate exceeded
+        # or
+        await limiter.aacquire()  # async version
+    """
+
+    def __init__(self, requests_per_minute: int = 60):
+        self.rpm = requests_per_minute
+        self._tokens = float(requests_per_minute)
+        self._last_refill = time.monotonic()
+        self._lock = threading.Lock()
+        self._async_lock = None  # Lazy init
+        self._total_acquired = 0
+        self._total_waited_ms = 0
+
+    def _refill(self):
+        """Refill tokens based on elapsed time."""
+        now = time.monotonic()
+        elapsed = now - self._last_refill
+        self._tokens = min(self.rpm, self._tokens + elapsed * (self.rpm / 60.0))
+        self._last_refill = now
+
+    def acquire(self) -> float:
+        """Acquire one token. Blocks if necessary. Returns wait time in seconds."""
+        with self._lock:
+            self._refill()
+            if self._tokens >= 1:
+                self._tokens -= 1
+                self._total_acquired += 1
+                return 0.0
+
+            # Calculate wait time
+            wait = (1 - self._tokens) / (self.rpm / 60.0)
+
+        time.sleep(wait)
+
+        with self._lock:
+            self._refill()
+            self._tokens = max(0, self._tokens - 1)
+            self._total_acquired += 1
+            self._total_waited_ms += wait * 1000
+
+        return wait
+
+    async def aacquire(self) -> float:
+        """Async version of acquire."""
+        if self._async_lock is None:
+            self._async_lock = asyncio.Lock()
+
+        async with self._async_lock:
+            self._refill()
+            if self._tokens >= 1:
+                self._tokens -= 1
+                self._total_acquired += 1
+                return 0.0
+
+            wait = (1 - self._tokens) / (self.rpm / 60.0)
+
+        await asyncio.sleep(wait)
+
+        async with self._async_lock:
+            self._refill()
+            self._tokens = max(0, self._tokens - 1)
+            self._total_acquired += 1
+            self._total_waited_ms += wait * 1000
+
+        return wait
+
+    @property
+    def available_tokens(self) -> float:
+        with self._lock:
+            self._refill()
+            return self._tokens
+
+    def summary(self) -> str:
+        return (
+            f"RateLimiter({self.rpm} rpm): "
+            f"{self._total_acquired} acquired, "
+            f"{self._total_waited_ms:.0f}ms total wait"
+        )

+ 152 - 0
lambdagent/resilient_mcp.py

@@ -0,0 +1,152 @@
+"""
+lambdagent.resilient_mcp — Resilient MCP client with connection pooling
+
+Wraps MCP calls with circuit breaker, retry, and tool discovery caching.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+import urllib.request
+import urllib.error
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .retry import RetryPolicy, CircuitBreaker, with_retry_sync
+
+
+@dataclass
+class MCPToolSchema:
+    """Cached tool schema from MCP discovery."""
+    name: str
+    description: str = ""
+    input_schema: Dict = field(default_factory=dict)
+
+
+class ResilientMCPClient:
+    """MCP client with circuit breaker, retry, and tool discovery caching.
+
+    Features:
+      - Circuit breaker: fast-fail when server is down
+      - Retry with exponential backoff for transient errors
+      - Tool discovery caching: avoid repeated list_tools calls
+      - Connection reuse via urllib keep-alive
+    """
+
+    def __init__(self, url: str, endpoint: str = "", headers: Dict[str, str] = None,
+                 timeout: int = 30, retry_policy: RetryPolicy = None,
+                 circuit_breaker: CircuitBreaker = None, name: str = ""):
+        self.url = url.rstrip("/")
+        self.endpoint = endpoint
+        self.headers = headers or {}
+        self.timeout = timeout
+        self.name = name or url
+        self.retry_policy = retry_policy or RetryPolicy(
+            max_attempts=2, base_delay=1.0, retryable_errors=(TimeoutError, ConnectionError, OSError)
+        )
+        self.circuit = circuit_breaker or CircuitBreaker(
+            failure_threshold=3, reset_timeout=30.0, name=f"mcp:{name or url}"
+        )
+        self._tool_cache: Optional[List[MCPToolSchema]] = None
+        self._cache_time: float = 0
+        self._cache_ttl: float = 300  # 5 min cache for tool discovery
+        self._call_count: int = 0
+        self._error_count: int = 0
+
+    @property
+    def full_url(self) -> str:
+        return f"{self.url}{self.endpoint}"
+
+    def call_tool(self, tool_name: str, arguments: Any, timeout: int = None) -> str:
+        """Call an MCP tool with circuit breaker + retry."""
+        timeout = timeout or self.timeout
+
+        def _do_call():
+            return self.circuit.call_sync(
+                lambda: self._raw_call(tool_name, arguments, timeout)
+            )
+
+        try:
+            result = with_retry_sync(_do_call, self.retry_policy)
+            self._call_count += 1
+            return result
+        except Exception as e:
+            self._error_count += 1
+            return f"[MCP_ERROR: {self.name}/{tool_name}] {e}"
+
+    def list_tools(self, force_refresh: bool = False) -> List[MCPToolSchema]:
+        """List available tools. Uses cache unless expired or forced."""
+        now = time.time()
+        if not force_refresh and self._tool_cache is not None:
+            if now - self._cache_time < self._cache_ttl:
+                return self._tool_cache
+
+        try:
+            body = json.dumps({
+                "jsonrpc": "2.0", "id": 1,
+                "method": "tools/list", "params": {}
+            }).encode("utf-8")
+
+            req_headers = {"Content-Type": "application/json"}
+            req_headers.update(self.headers)
+
+            req = urllib.request.Request(self.full_url, data=body,
+                                        headers=req_headers, method="POST")
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+
+            tools_data = data.get("result", {}).get("tools", [])
+            self._tool_cache = [
+                MCPToolSchema(
+                    name=t.get("name", ""),
+                    description=t.get("description", ""),
+                    input_schema=t.get("inputSchema", {}),
+                )
+                for t in tools_data
+            ]
+            self._cache_time = now
+            return self._tool_cache
+        except Exception:
+            return self._tool_cache or []
+
+    def _raw_call(self, tool_name: str, arguments: Any, timeout: int) -> str:
+        """Raw MCP tool call via HTTP."""
+        if isinstance(arguments, str):
+            try:
+                arguments = json.loads(arguments)
+            except (json.JSONDecodeError, ValueError):
+                arguments = {"input": arguments}
+
+        body = json.dumps({
+            "jsonrpc": "2.0", "id": 1,
+            "method": "tools/call",
+            "params": {"name": tool_name, "arguments": arguments},
+        }).encode("utf-8")
+
+        req_headers = {"Content-Type": "application/json"}
+        req_headers.update(self.headers)
+
+        req = urllib.request.Request(self.full_url, data=body,
+                                    headers=req_headers, method="POST")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+
+        if "result" in data:
+            result = data["result"]
+            if isinstance(result, dict):
+                content = result.get("content", [])
+                if content and isinstance(content, list):
+                    return content[0].get("text", str(result))
+                return str(result)
+            return str(result)
+        elif "error" in data:
+            raise RuntimeError(f"MCP error: {data['error']}")
+        return str(data)
+
+    def summary(self) -> str:
+        return (
+            f"ResilientMCPClient({self.name}): "
+            f"{self._call_count} calls, {self._error_count} errors, "
+            f"circuit={self.circuit.state}"
+        )

+ 227 - 0
lambdagent/tests/test_phase3.py

@@ -0,0 +1,227 @@
+"""
+Integration tests for Phase 3: P2 Competitiveness Improvements
+
+Tests:
+  - T18: OpenTelemetry integration (AgentTracer)
+  - T19: Token budget management
+  - T20: Tool concurrency safety
+  - T21: Rate limiter
+  - T22: Resilient MCP client
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+import pytest
+
+
+# ════════════════════════════════════════════════════════════
+# T18: Observability (AgentTracer)
+# ════════════════════════════════════════════════════════════
+
+class TestObservability:
+    def test_tracer_span(self):
+        from lambdagent.observability import AgentTracer
+        tracer = AgentTracer("test")
+        with tracer.span("test_op", key="value") as span:
+            time.sleep(0.01)
+        assert len(tracer.spans) == 1
+        assert tracer.spans[0].name == "test_op"
+        assert tracer.spans[0].attributes["key"] == "value"
+        assert tracer.spans[0].duration_ms >= 10
+
+    def test_tracer_error_span(self):
+        from lambdagent.observability import AgentTracer
+        tracer = AgentTracer("test")
+        with pytest.raises(ValueError):
+            with tracer.span("failing_op") as span:
+                raise ValueError("boom")
+        assert len(tracer.spans) == 1
+        assert "error" in tracer.spans[0].status
+
+    def test_record_reduction(self):
+        from lambdagent.observability import AgentTracer
+        tracer = AgentTracer("test")
+        tracer.record_reduction("think", "Lam", "input", "output", 150.0,
+                                model="claude-3", tokens=500)
+        assert len(tracer.spans) == 1
+        assert tracer.spans[0].attributes["tokens.used"] == 500
+
+    def test_export_json(self):
+        from lambdagent.observability import AgentTracer
+        tracer = AgentTracer("test")
+        with tracer.span("op1"):
+            pass
+        exported = tracer.export_json()
+        assert len(exported) == 1
+        assert "name" in exported[0]
+        assert "duration_ms" in exported[0]
+
+    def test_summary(self):
+        from lambdagent.observability import AgentTracer
+        tracer = AgentTracer("test")
+        with tracer.span("op1"):
+            pass
+        s = tracer.summary()
+        assert "1 spans" in s
+
+
+# ════════════════════════════════════════════════════════════
+# T19: Token Budget
+# ════════════════════════════════════════════════════════════
+
+class TestTokenBudget:
+    def test_basic_tracking(self):
+        from lambdagent.token_budget import TokenBudget
+        budget = TokenBudget(max_tokens=1000)
+        assert budget.remaining == 1000
+        budget.record(100, 50, model="claude-3")
+        assert budget.used == 150
+        assert budget.remaining == 850
+
+    def test_can_afford(self):
+        from lambdagent.token_budget import TokenBudget
+        budget = TokenBudget(max_tokens=100)
+        assert budget.can_afford(50)
+        assert budget.can_afford(99)
+        assert not budget.can_afford(100)
+
+    def test_budget_exhausted_error(self):
+        from lambdagent.token_budget import TokenBudget, BudgetExhaustedError
+        budget = TokenBudget(max_tokens=100)
+        budget.record(60, 50)
+        with pytest.raises(BudgetExhaustedError):
+            budget.check()
+
+    def test_by_model_tracking(self):
+        from lambdagent.token_budget import TokenBudget
+        budget = TokenBudget(max_tokens=10000)
+        budget.record(100, 50, model="claude-3")
+        budget.record(200, 100, model="gpt-4")
+        budget.record(50, 25, model="claude-3")
+        assert budget._by_model["claude-3"] == 225
+        assert budget._by_model["gpt-4"] == 300
+
+    def test_estimate_cost(self):
+        from lambdagent.token_budget import TokenBudget
+        budget = TokenBudget()
+        assert budget.estimate_cost("hello world") == 2  # 11 chars / 4
+
+
+# ════════════════════════════════════════════════════════════
+# T20: Tool concurrency safety
+# ════════════════════════════════════════════════════════════
+
+class TestConcurrentTools:
+    def test_concurrent_tool_creation(self):
+        from lambdagent.concurrent_tools import ConcurrentTool
+        safe = ConcurrentTool("search", lambda x: x, concurrent_safe=True)
+        unsafe = ConcurrentTool("write", lambda x: x, concurrent_safe=False)
+        assert safe.concurrent_safe is True
+        assert unsafe.concurrent_safe is False
+
+    def test_partition_by_safety(self):
+        from lambdagent.concurrent_tools import ConcurrentTool, partition_by_safety
+        tools = [
+            ConcurrentTool("read1", lambda x: x, concurrent_safe=True),
+            ConcurrentTool("write1", lambda x: x, concurrent_safe=False),
+            ConcurrentTool("read2", lambda x: x, concurrent_safe=True),
+        ]
+        safe, unsafe = partition_by_safety(tools)
+        assert len(safe) == 2
+        assert len(unsafe) == 1
+
+    def test_helper_constructors(self):
+        from lambdagent.concurrent_tools import read_tool, write_tool
+        r = read_tool("search", lambda x: x)
+        w = write_tool("save", lambda x: x)
+        assert r.concurrent_safe is True
+        assert w.concurrent_safe is False
+
+
+# ════════════════════════════════════════════════════════════
+# T21: Rate Limiter
+# ════════════════════════════════════════════════════════════
+
+class TestRateLimiter:
+    def test_basic_acquire(self):
+        from lambdagent.rate_limiter import RateLimiter
+        limiter = RateLimiter(requests_per_minute=600)  # 10/sec
+        wait = limiter.acquire()
+        assert wait == 0.0
+
+    def test_rate_limiting(self):
+        from lambdagent.rate_limiter import RateLimiter
+        limiter = RateLimiter(requests_per_minute=60)  # 1/sec
+        # Drain all tokens
+        for _ in range(60):
+            limiter.acquire()
+        # Next should have to wait
+        t0 = time.time()
+        limiter.acquire()
+        elapsed = time.time() - t0
+        assert elapsed >= 0.5  # Should wait ~1 second
+
+    def test_async_acquire(self):
+        from lambdagent.rate_limiter import RateLimiter
+        limiter = RateLimiter(requests_per_minute=600)
+
+        async def _run():
+            wait = await limiter.aacquire()
+            return wait
+
+        loop = asyncio.get_event_loop()
+        wait = loop.run_until_complete(_run())
+        assert wait == 0.0
+
+    def test_summary(self):
+        from lambdagent.rate_limiter import RateLimiter
+        limiter = RateLimiter(60)
+        limiter.acquire()
+        s = limiter.summary()
+        assert "1 acquired" in s
+
+
+# ════════════════════════════════════════════════════════════
+# T22: Resilient MCP Client
+# ════════════════════════════════════════════════════════════
+
+class TestResilientMCP:
+    def test_client_creation(self):
+        from lambdagent.resilient_mcp import ResilientMCPClient
+        client = ResilientMCPClient("http://localhost:8080", name="test")
+        assert client.name == "test"
+        assert client.full_url == "http://localhost:8080"
+
+    def test_tool_cache(self):
+        from lambdagent.resilient_mcp import ResilientMCPClient
+        client = ResilientMCPClient("http://localhost:8080")
+        # Manually set cache
+        from lambdagent.resilient_mcp import MCPToolSchema
+        client._tool_cache = [MCPToolSchema(name="test_tool", description="A test")]
+        client._cache_time = time.time()
+        tools = client.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "test_tool"
+
+    def test_call_tool_with_offline_server(self):
+        from lambdagent.resilient_mcp import ResilientMCPClient
+        from lambdagent.retry import RetryPolicy
+        client = ResilientMCPClient(
+            "http://localhost:99999",
+            retry_policy=RetryPolicy(max_attempts=1, base_delay=0.01),
+            name="offline",
+        )
+        result = client.call_tool("test", {"input": "hello"})
+        assert "MCP_ERROR" in result
+
+    def test_summary(self):
+        from lambdagent.resilient_mcp import ResilientMCPClient
+        client = ResilientMCPClient("http://localhost:8080", name="test")
+        s = client.summary()
+        assert "test" in s
+        assert "0 calls" in s
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v", "--tb=short"])

+ 77 - 0
lambdagent/token_budget.py

@@ -0,0 +1,77 @@
+"""
+lambdagent.token_budget — Token budget tracking and enforcement
+
+Tracks token consumption across agent execution and prevents
+budget overrun by raising BudgetExhaustedError.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict
+
+from .core import LambdagentError
+
+
+class BudgetExhaustedError(LambdagentError):
+    """Raised when token budget is exhausted."""
+    def __init__(self, budget: int, used: int):
+        self.budget = budget
+        self.used = used
+        super().__init__(f"Token budget exhausted: {used}/{budget} tokens used")
+
+
+@dataclass
+class TokenBudget:
+    """Track and enforce token consumption limits."""
+    max_tokens: int = 100000
+    used: int = 0
+    _by_model: Dict[str, int] = field(default_factory=dict)
+    _by_step: list = field(default_factory=list)
+
+    def estimate_cost(self, text: str) -> int:
+        """Rough token count estimate (4 chars ≈ 1 token)."""
+        return len(text) // 4
+
+    def can_afford(self, estimated_tokens: int) -> bool:
+        """Check if budget can afford estimated_tokens more."""
+        return self.used + estimated_tokens < self.max_tokens
+
+    def can_afford_prompt(self, prompt: str) -> bool:
+        """Check if budget can afford sending this prompt."""
+        return self.can_afford(self.estimate_cost(prompt))
+
+    def record(self, input_tokens: int, output_tokens: int, model: str = "",
+               step: int = -1):
+        """Record token consumption."""
+        total = input_tokens + output_tokens
+        self.used += total
+        if model:
+            self._by_model[model] = self._by_model.get(model, 0) + total
+        if step >= 0:
+            self._by_step.append({"step": step, "input": input_tokens,
+                                  "output": output_tokens, "model": model})
+
+    def check(self):
+        """Raise BudgetExhaustedError if budget exceeded."""
+        if self.used >= self.max_tokens:
+            raise BudgetExhaustedError(self.max_tokens, self.used)
+
+    @property
+    def remaining(self) -> int:
+        return max(0, self.max_tokens - self.used)
+
+    @property
+    def utilization(self) -> float:
+        """Budget utilization as fraction (0.0 to 1.0+)."""
+        return self.used / self.max_tokens if self.max_tokens > 0 else 0
+
+    def summary(self) -> str:
+        lines = [
+            f"Token Budget: {self.used:,}/{self.max_tokens:,} ({self.utilization:.1%})",
+            f"  Remaining: {self.remaining:,}",
+        ]
+        if self._by_model:
+            lines.append("  By model:")
+            for model, tokens in sorted(self._by_model.items()):
+                lines.append(f"    {model}: {tokens:,}")
+        return "\n".join(lines)