CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
plan: BoundModel convenience methods + middleware migration
xf gongaf70d7af6ca4
diff --git a/dev/plans/2026-06-08-boundmodel-convenience-methods.md b/dev/plans/2026-06-08-boundmodel-convenience-methods.mdnew file mode 100644index 0000000..5d3a67c--- /dev/null+++ b/dev/plans/2026-06-08-boundmodel-convenience-methods.md@@ -0,0 +1,726 @@+# BoundModel Convenience Methods Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++**Goal:** Let `BoundModel` directly drive a provider call (`await bound.generate(...)` / `await bound.stream(...)`), and propagate that ergonomics into middleware so we stop splitting `BoundModel` back into `(Provider, Model)` everywhere.++**Architecture:** Add two forwarding methods to the existing `@dataclass(frozen=True) BoundModel` that delegate to `self.provider.stream` / `self.provider.generate` with `model=self.spec`. Then migrate the two middleware seams that still expose the unwrapped pair:+1. `cubepi/middleware/compaction/summarizer.py::summarize` takes `model: BoundModel` and uses `model.generate(...)`.+2. `Middleware.extra_llm_calls()` returns `Iterable[BoundModel]` instead of `Iterable[tuple[Provider, Model]]`; `cubepi/tracing/recorder.py` is the only consumer and unwraps it.++**Non-goals:** Touching `Agent.__init__` / `cubepi/agent/loop.py` call sites is out of scope — they still pass `provider=` and `model=` separately and the loop module's signature is wide. Leave a follow-up note.++**Tech Stack:** Python 3.11+, Pydantic v2 (`Model` spec only — `BoundModel` is a stdlib `dataclass`), pytest with `asyncio_mode=auto`, `FauxProvider` for deterministic provider tests, ruff, mypy.++---++## File Structure++- **Modify** `cubepi/providers/base.py` — add `BoundModel.stream` and `BoundModel.generate` methods (lines 93–96 today).+- **Modify** `cubepi/middleware/compaction/summarizer.py` — `summarize()` signature: `provider: Provider, model: Model` → `model: BoundModel`.+- **Modify** `cubepi/middleware/compaction/__init__.py` — drop split fields; keep one `self._summary_model: BoundModel`; `extra_llm_calls()` returns `(self._summary_model,)`.+- **Modify** `cubepi/middleware/base.py` — `extra_llm_calls` return type → `Iterable[BoundModel]`; refresh docstring; drop now-unused `Model` import if applicable.+- **Modify** `cubepi/tracing/recorder.py` (around line 289) — adapt consumer loop to iterate `BoundModel`.+- **Create** `tests/providers/test_bound_model_calls.py` — focused forwarding tests for the two new methods on `BoundModel` (uses a small recording fake provider for `generate`, `FauxProvider` + queued response for `stream`).+- **Modify** `tests/middleware/compaction/test_summarizer.py` — three `summarize(provider=..., model=...)` call sites migrate to `summarize(model=BoundModel(provider=..., spec=...))`.+- **Modify** `tests/tracing/test_recorder.py` — three middleware mocks (`extra_llm_calls` at lines ~666, ~706, ~735) return `BoundModel` instead of tuples.+- **Modify** `website/docs/agents/providers.md` (or whichever current providers page documents `provider.model(...)`) — add a one-paragraph note that the returned `BoundModel` is itself callable via `.stream()` / `.generate()`.++`tests/middleware/test_compaction.py` already constructs `CompactionMiddleware(summary_model=BoundModel(...), ...)` (line 75), so the public-API surface needs no test changes there. Recorder tests at `tests/tracing/test_recorder.py:515` / `:591` likewise construct `BoundModel(...)` directly and stay green through both Task 3 (internal call-site change) and Task 4 (field collapse + extra_llm_calls shape change).++---++## Task 1: `BoundModel.generate` forwards to the bound provider++**Files:**+- Modify: `cubepi/providers/base.py:93-96`+- Test: `tests/providers/test_bound_model_calls.py` (new)++- [ ] **Step 1: Write the failing test**++We use a small recording provider (not `FauxProvider`) because the goal here is to verify *forwarding semantics* — that `BoundModel.generate` calls `self.provider.generate(model=self.spec, **kwargs)` exactly. `FauxProvider` without a queued response just emits an error message, which would mask whether forwarding worked.++```python+# tests/providers/test_bound_model_calls.py+from __future__ import annotations++from typing import Any++import pytest++from cubepi.providers.base import (+ AssistantMessage,+ BaseProvider,+ Message,+ Model,+ StreamOptions,+ TextContent,+ ToolDefinition,+ UserMessage,+)+++class _RecordingProvider(BaseProvider):+ def __init__(self) -> None:+ super().__init__(provider_id="rec")+ self.generate_calls: list[dict[str, Any]] = []+ self.stream_calls: list[dict[str, Any]] = []++ async def generate( # type: ignore[override]+ self,+ model: Model,+ messages: list[Message],+ *,+ system_prompt: str = "",+ tools: list[ToolDefinition] | None = None,+ options: StreamOptions | None = None,+ max_output_tokens: int | None = None,+ temperature: float | None = None,+ thinking: Any = None,+ thinking_budgets: Any = None,+ ) -> AssistantMessage:+ self.generate_calls.append(+ {+ "model": model,+ "messages": messages,+ "system_prompt": system_prompt,+ "tools": tools,+ "options": options,+ "max_output_tokens": max_output_tokens,+ "temperature": temperature,+ "thinking": thinking,+ "thinking_budgets": thinking_budgets,+ }+ )+ return AssistantMessage(+ content=[TextContent(text="ok")],+ provider_id=model.provider_id,+ model_id=model.id,+ )+++async def test_bound_model_generate_forwards_to_provider() -> None:+ provider = _RecordingProvider()+ bound = provider.model("model-x", temperature=0.5)+ messages = [UserMessage(content=[TextContent(text="hi")])]++ response = await bound.generate(+ messages=messages,+ system_prompt="be brief",+ max_output_tokens=64,+ temperature=0.0,+ thinking="off",+ )++ assert isinstance(response, AssistantMessage)+ assert response.provider_id == "rec"+ assert response.model_id == "model-x"++ assert len(provider.generate_calls) == 1+ call = provider.generate_calls[0]+ assert call["model"] is bound.spec+ assert call["messages"] is messages+ assert call["system_prompt"] == "be brief"+ assert call["max_output_tokens"] == 64+ assert call["temperature"] == 0.0+ assert call["thinking"] == "off"+```++- [ ] **Step 2: Run test to verify it fails**++```bash+cd /home/chris/cubepi/.worktrees/2026-06-08-boundmodel-methods+uv run pytest tests/providers/test_bound_model_calls.py::test_bound_model_generate_forwards_to_provider -v+```++Expected: FAIL with `AttributeError: 'BoundModel' object has no attribute 'generate'`.++- [ ] **Step 3: Add `generate` to `BoundModel`**++In `cubepi/providers/base.py`, replace the existing class body (currently lines 93–96):++```python+@dataclass(frozen=True)+class BoundModel:+ provider: "Provider"+ spec: Model++ async def generate(+ self,+ messages: list["Message"],+ *,+ system_prompt: str = "",+ tools: list["ToolDefinition"] | None = None,+ options: "StreamOptions | None" = None,+ max_output_tokens: int | None = None,+ temperature: float | None = None,+ thinking: "ThinkingLevel | None" = None,+ thinking_budgets: "ThinkingBudgets | None" = None,+ ) -> "AssistantMessage":+ return await self.provider.generate(+ model=self.spec,+ messages=messages,+ system_prompt=system_prompt,+ tools=tools,+ options=options,+ max_output_tokens=max_output_tokens,+ temperature=temperature,+ thinking=thinking,+ thinking_budgets=thinking_budgets,+ )+```++The string annotations avoid forward-reference issues — `Provider`, `Message`, `ToolDefinition`, `StreamOptions`, `ThinkingLevel`, `ThinkingBudgets`, and `AssistantMessage` are all defined *below* `BoundModel` in this file. Keep `from __future__ import annotations` if it's already at the top (check line 1); if it is, plain (unstringed) annotations are also fine — prefer that for readability.++- [ ] **Step 4: Run test to verify it passes**++```bash+uv run pytest tests/providers/test_bound_model_calls.py::test_bound_model_generate_forwards_to_provider -v+```++Expected: PASS.++- [ ] **Step 5: Commit**++```bash+git add cubepi/providers/base.py tests/providers/test_bound_model_calls.py+git commit -m "feat(providers): add BoundModel.generate convenience method"+```++---++## Task 2: `BoundModel.stream` forwards to the bound provider++**Files:**+- Modify: `cubepi/providers/base.py` (the `BoundModel` class added in Task 1)+- Test: `tests/providers/test_bound_model_calls.py`++- [ ] **Step 1: Append the failing test**++Stream needs a real `MessageStream`, so use `FauxProvider` with a queued response (cheaper than reimplementing the stream protocol in the recording fake). Add `FauxProvider` + `faux_assistant_message` to the imports at the top of the test file.++```python+from cubepi.providers.faux import FauxProvider, faux_assistant_message+++async def test_bound_model_stream_forwards_to_provider() -> None:+ provider = FauxProvider(provider_id="faux")+ provider.set_responses([faux_assistant_message("hello")])+ bound = provider.model("faux-1")++ stream = await bound.stream(+ messages=[UserMessage(content=[TextContent(text="hi")])],+ system_prompt="be brief",+ )++ events: list[str] = []+ async for event in stream:+ events.append(event.type)+ if event.type in ("done", "error"):+ break+ result = await stream.result()++ assert "start" in events+ assert "done" in events+ assert result.model_id == "faux-1"+ assert result.provider_id == "faux"+```++- [ ] **Step 2: Run test to verify it fails**++```bash+uv run pytest tests/providers/test_bound_model_calls.py::test_bound_model_stream_forwards_to_provider -v+```++Expected: FAIL with `AttributeError: 'BoundModel' object has no attribute 'stream'`.++- [ ] **Step 3: Add `stream` to `BoundModel`**++Append to the class body added in Task 1 (above `generate`, to match the order in `Provider` protocol):++```python+ async def stream(+ self,+ messages: list["Message"],+ *,+ system_prompt: str = "",+ tools: list["ToolDefinition"] | None = None,+ options: "StreamOptions | None" = None,+ ) -> "MessageStream":+ return await self.provider.stream(+ model=self.spec,+ messages=messages,+ system_prompt=system_prompt,+ tools=tools,+ options=options,+ )+```++`MessageStream` is also defined below — use the same string-annotation strategy as in Task 1.++- [ ] **Step 4: Run both BoundModel tests + the existing bound-model test file**++```bash+uv run pytest tests/providers/test_bound_model_calls.py tests/providers/test_bound_model.py -v+```++Expected: PASS for all (`test_bound_model.py` exercises construction, the new file exercises calls).++- [ ] **Step 5: Run type check on providers/**++```bash+uv run mypy cubepi/providers/base.py+```++Expected: no new errors. If mypy complains about `MessageStream` forward refs and `from __future__ import annotations` is *not* at the top, add it.++- [ ] **Step 6: Commit**++```bash+git add cubepi/providers/base.py tests/providers/test_bound_model_calls.py+git commit -m "feat(providers): add BoundModel.stream convenience method"+```++---++## Task 3: Migrate `summarize()` to take a `BoundModel` (signature-only)++**Files:**+- Modify: `cubepi/middleware/compaction/summarizer.py:55-80`+- Modify: `cubepi/middleware/compaction/__init__.py` (call site inside `transform_context` only — `__init__` and `extra_llm_calls` untouched)+- Modify: `tests/middleware/compaction/test_summarizer.py` (three call sites at lines ~60, ~85, ~119)++**Scope discipline:** This task only changes the `summarize` boundary. `CompactionMiddleware` keeps its `_summary_provider` + `_summary_model: Model` split fields and its existing `extra_llm_calls()` *unchanged* — Task 4 collapses them. This keeps the intermediate commit fully working (compaction tests + recorder tests both pass after Task 3).++- [ ] **Step 1: Run the existing compaction + summarizer tests as a baseline**++```bash+uv run pytest tests/middleware/test_compaction.py tests/middleware/compaction/test_summarizer.py tests/tracing/test_recorder.py -v+```++Expected: PASS. Record the totals — we need them all to still pass after Task 3.++- [ ] **Step 2: Update `summarize()` signature**++In `cubepi/middleware/compaction/summarizer.py`, replace the function header and the provider call site. Replace the import block + the function body (lines 6-14 imports, lines 55-80 function):++```python+from cubepi.middleware.compaction.state import CompactionState, message_refs+from cubepi.providers.base import (+ BoundModel,+ Message,+ StreamOptions,+ TextContent,+ ToolCall,+ UserMessage,+)+# ...++async def summarize(+ *,+ model: BoundModel,+ messages_to_summarize: list[Message],+ existing: CompactionState | None,+ max_summary_tokens: int = 1024,+ abort_signal: asyncio.Event | None = None,+) -> CompactionState:+ system_prompt = SUMMARIZER_SYSTEM_PROMPT+ if existing and existing.summary:+ system_prompt += "\n\n" + EXISTING_SUMMARY_SUFFIX.format(prev=existing.summary)++ response = await model.generate(+ messages=[+ UserMessage(+ content=[TextContent(text=_format_transcript(messages_to_summarize))]+ )+ ],+ system_prompt=system_prompt,+ options=StreamOptions(signal=abort_signal),+ max_output_tokens=max_summary_tokens,+ temperature=0.0,+ thinking="off",+ )+```++Remove `Model` and `Provider` from the imports (now unused inside this file).++- [ ] **Step 3: Update the `summarize` call site in `CompactionMiddleware`**++In `cubepi/middleware/compaction/__init__.py`, **only** the call inside `transform_context` changes. Do NOT touch `__init__` or `extra_llm_calls()` in this task.++Replace the existing `summarize(...)` call (the block around `try: new_state = await summarize(...)`) with:++```python+ try:+ new_state = await summarize(+ model=BoundModel(+ provider=self._summary_provider,+ spec=self._summary_model,+ ),+ messages_to_summarize=messages[boundary:new_boundary],+ existing=state,+ max_summary_tokens=self._max_summary_tokens,+ abort_signal=signal,+ )+```++`BoundModel` is already imported at the top of this file. The `extra_llm_calls()` method below still returns `((self._summary_provider, self._summary_model),)` — leave it; Task 4 handles it.++- [ ] **Step 4: Migrate `tests/middleware/compaction/test_summarizer.py` to the new signature**++This file has three `summarize(provider=..., model=...)` call sites (around lines 60, 85, 119). All three need to wrap the provider + model in a `BoundModel`. Example for the first call site:++```python+# At the top, extend the imports:+from cubepi.providers.base import (+ AssistantMessage,+ BoundModel,+ Message,+ Model,+ StreamOptions,+ TextContent,+ ToolCall,+ ToolDefinition,+ UserMessage,+)++# Then replace each `summarize(provider=provider, model=model, ...)` with:+result = await summarize(+ model=BoundModel(provider=provider, spec=model),+ messages_to_summarize=[...],+ existing=None,+ max_summary_tokens=512,+ abort_signal=signal,+)+```++`_FakeProvider` (defined in the same file) only implements `generate` — that's fine because `BoundModel.generate` delegates to `self.provider.generate(model=self.spec, ...)`, so `_FakeProvider.generate` receives the same kwargs it does today and the `provider.calls[0]["max_output_tokens"]` style assertions stay green.++Do all three call sites in one edit. Don't change the `_FakeProvider` definition or the assertions.++- [ ] **Step 5: Run the touched test suites**++```bash+uv run pytest tests/middleware/compaction/test_summarizer.py tests/middleware/test_compaction.py tests/tracing/test_recorder.py -v+```++Expected: same PASS totals as Step 1 (no behavior change). If `test_summarizer.py` fails, the migration in Step 4 missed a call site.++- [ ] **Step 6: Commit**++```bash+git add cubepi/middleware/compaction/summarizer.py cubepi/middleware/compaction/__init__.py tests/middleware/compaction/test_summarizer.py+git commit -m "refactor(compaction): summarize() takes BoundModel"+```++---++## Task 4: Collapse compaction fields + `extra_llm_calls()` returns `Iterable[BoundModel]`++**Files:**+- Modify: `cubepi/middleware/base.py:96-116`+- Modify: `cubepi/middleware/compaction/__init__.py` (`__init__`, the `summarize` call site, and `extra_llm_calls`)+- Modify: `cubepi/tracing/recorder.py:286-299`+- Test: `tests/tracing/test_recorder.py` (three mocks at ~666, ~706, ~735)++This task does the atomic switchover: one `BoundModel` field instead of split provider+spec, and a `BoundModel`-shaped `extra_llm_calls()` API. All four pieces (base, compaction impl, recorder consumer, recorder test mocks) flip together to keep tests green.++- [ ] **Step 0: Confirm no third-party `extra_llm_calls` overrides exist**++```bash+grep -rn "extra_llm_calls" cubepi/ tests/ --include="*.py"+```++Expected hits: the base definition, the compaction override, the recorder consumer, and four test references (`tests/tracing/test_recorder.py`). If anything else shows up, fold it into the migration before continuing.++- [ ] **Step 1: Update the base interface and docstring**++In `cubepi/middleware/base.py`, replace lines 96–116 (the `extra_llm_calls` method) and adjust imports:++```python+from cubepi.providers.base import AssistantMessage, BoundModel, Message # drop Model, Provider+```++(Keep `Provider` only if it's still referenced elsewhere in the file — currently it isn't outside `extra_llm_calls`'s annotation, so drop it. Same for `Model`. Verify with `grep -n "Provider\b\|Model\b" cubepi/middleware/base.py` after editing.)++```python+ def extra_llm_calls(self) -> Iterable[BoundModel]:+ """Declare LLM calls this middleware drives outside the agent's main+ bound model.++ Each entry is a ``BoundModel`` — the same handle the user gets from+ ``provider.model(...)``. ``cubepi.tracing.Recorder`` uses these to:++ * Subscribe listeners on any provider the recorder isn't already+ watching, so the resulting calls show up in the trace tree+ alongside the agent's own chat spans.+ * Identify middleware-owned calls by ``(spec.provider_id, spec.id)``+ so they don't overwrite the root ``invoke_agent`` span's+ attribution (provider name, system prompt hash, tool list). This+ model-based gate is what handles the common "reuse one provider+ client, swap the model" pattern — listener identity alone would+ attribute the middleware's first call to the agent.++ Default is empty — middlewares that do not call any LLM directly+ need not override.+ """+ return ()+```++- [ ] **Step 2: Collapse `CompactionMiddleware` fields and update `extra_llm_calls`**++In `cubepi/middleware/compaction/__init__.py`, three changes in one pass:++**(a)** Replace `__init__`:++```python+ def __init__(+ self,+ *,+ summary_model: BoundModel,+ max_tokens_before_compact: int,+ keep_recent_messages: int = 8,+ max_summary_tokens: int = 1024,+ min_compact_messages: int = 4,+ ) -> None:+ self._summary_model = summary_model+ self._max_tokens_before = max_tokens_before_compact+ self._keep_recent = keep_recent_messages+ self._max_summary_tokens = max_summary_tokens+ self._min_compact = min_compact_messages+```++**(b)** Simplify the `summarize` call inside `transform_context` — Task 3 set it to `BoundModel(provider=self._summary_provider, spec=self._summary_model)`; now it's just:++```python+ try:+ new_state = await summarize(+ model=self._summary_model,+ messages_to_summarize=messages[boundary:new_boundary],+ existing=state,+ max_summary_tokens=self._max_summary_tokens,+ abort_signal=signal,+ )+```++**(c)** Replace `extra_llm_calls`:++```python+ def extra_llm_calls(self) -> tuple[BoundModel, ...]:+ # Surface the bound summary model so ``cubepi.tracing.Recorder`` can+ # both subscribe its listeners (the summarizer's chat span lands in+ # the trace) AND identify the summary call by spec — important when+ # the summary model's provider is the same instance as the agent's+ # main provider, the common "reuse the client, swap the model"+ # pattern.+ return (self._summary_model,)+```++Drop `Model` and `Provider` from the imports at the top of this file (no longer referenced).++- [ ] **Step 3: Update the recorder consumer**++In `cubepi/tracing/recorder.py`, around lines 286–299, replace the unpacking loop. The current code is:++```python+for p, m in extra:+ key = (m.provider_id, m.id)+ if key != agent_key:+ self._extra_call_models.add(key)+ if id(p) in seen:+ continue+ seen.add(id(p))+ _subscribe(p)+```++Replace with:++```python+for bound in extra:+ spec = bound.spec+ key = (spec.provider_id, spec.id)+ if key != agent_key:+ self._extra_call_models.add(key)+ provider = bound.provider+ if id(provider) in seen:+ continue+ seen.add(id(provider))+ _subscribe(provider)+```++Add `BoundModel` to the file's imports if not already imported (the surrounding code uses `Model`, `Provider`, etc., from `cubepi.providers.base`).++- [ ] **Step 4: Update the three mocks in the recorder tests**++In `tests/tracing/test_recorder.py`, three middleware classes return from `extra_llm_calls`. They are NOT interchangeable — each exercises a different recorder branch, so spell out the per-test replacement instead of applying one template. `BoundModel` is already imported at line 22 of the test file.++**(a)** `_SameModelMiddleware` (around line 666): exercises the "same `(provider_id, id)` as the agent's bound model — must be excluded from `_extra_call_models`" branch. The mock takes `provider` and `model` via its constructor and stores them on `self._p` / `self._m`.++```python+ def extra_llm_calls(self):+ return [BoundModel(provider=self._p, spec=self._m)]+```++**(b)** `_DuckMiddleware` (around line 706): exercises the "provider not derived from `BaseProvider` is skipped in `_subscribe`" branch. The provider here MUST stay `_DuckProvider()` — using the agent's BaseProvider would silently kill the branch this test exists to cover. The model field is `self._m` from the middleware's constructor.++```python+ def extra_llm_calls(self):+ return [BoundModel(provider=_DuckProvider(), spec=self._m)]+```++`BoundModel` is a `@dataclass(frozen=True)`; even though `provider: Provider` is a `runtime_checkable` `Protocol`, dataclasses don't enforce protocol membership at construction, so `_DuckProvider` is accepted just like the current tuple form. The recorder's `_subscribe` check is still what skips it downstream.++**(c)** `_BoomMiddleware` (around line 735): raises before returning, so the return shape doesn't matter. **Do not change this class.**++After editing, verify the test method names that contain the changed classes still pass intact:++```bash+uv run pytest tests/tracing/test_recorder.py -k "extra_llm_calls or extra_provider_not_baseprovider" -v+```++Expected: all PASS — in particular the duck-provider test must still hit the "skipped non-BaseProvider" branch (you can sanity-check by reading the recorder's `_subscribe` and confirming the same code path runs).++- [ ] **Step 5: Run the recorder + middleware test suites**++```bash+uv run pytest tests/tracing/test_recorder.py tests/middleware/ -v+```++Expected: PASS. Any new failure here means the consumer or a mock wasn't fully migrated.++- [ ] **Step 6: Full test sweep + lint + types**++```bash+uv run pytest tests/ -x+uv run ruff check cubepi/ tests/+uv run ruff format --check cubepi/ tests/+uv run mypy cubepi+```++Expected: all green. (`pytest -x` stops at the first failure so issues surface fast.)++- [ ] **Step 7: Commit**++```bash+git add cubepi/middleware/base.py cubepi/middleware/compaction/__init__.py cubepi/tracing/recorder.py tests/tracing/test_recorder.py+git commit -m "refactor(middleware): extra_llm_calls returns BoundModel"+```++---++## Task 5: Document the new ergonomics++**Files:**+- Modify: `website/docs/agents/providers.md` (or the closest existing page; verify with `ls website/docs/agents/ website/docs/getting-started/`)++CLAUDE.md requires user-facing docs in the same PR. `BoundModel.generate` / `.stream` are now part of the public surface.++- [ ] **Step 1: Locate the providers doc**++```bash+grep -rln "provider.model(" website/docs/ | head -5+```++Open the page that introduces `provider.model("...")` (most likely `website/docs/agents/providers.md` or the getting-started page).++- [ ] **Step 2: Add a short subsection right after the `provider.model(...)` introduction**++Insert (adjust heading level to match neighbours):++```markdown+### Calling a bound model directly++`provider.model(...)` returns a `BoundModel` that you can invoke without+fishing the provider out again:++```python+bound = provider.model("claude-sonnet-4-6")++# Single-shot call.+reply = await bound.generate(+ messages=[UserMessage(content=[TextContent(text="hi")])],+ system_prompt="Be brief.",+)++# Streaming.+stream = await bound.stream(messages=[...])+async for event in stream:+ ...+```++Both methods forward to the bound provider with `model=bound.spec` — useful+for utilities (e.g. summarizers, classifiers) where you already hold a+`BoundModel` and want to skip the agent loop.+```++- [ ] **Step 3: Verify docs build**++```bash+cd website && pnpm typecheck && cd -+```++Expected: PASS. (If `pnpm` isn't set up locally, skip; CI will catch.)++- [ ] **Step 4: Commit**++```bash+git add website/docs/+git commit -m "docs(providers): document BoundModel.generate/stream"+```++---++## Task 6 (gated): Local codex review loop++**Per CLAUDE.md, ask the user before starting this loop.** Do not enter it autonomously.++- [ ] **Step 1: Ask the user**++> "Code is done and tests green. Want me to run the `codex:rescue` local review loop now?"++- [ ] **Step 2: If yes, run the loop**++Use the `codex:rescue` subagent to review the diff. Iterate until codex reports no remaining issues. Push fixups as separate commits — do not amend.++- [ ] **Step 3: Open the PR**++```bash+git push -u origin 2026-06-08-boundmodel-methods+gh pr create --title "feat(providers): BoundModel.generate/stream + middleware migration" --body "$(cat <<'EOF'+## Summary+- Add `BoundModel.generate` / `BoundModel.stream` convenience methods+- `CompactionMiddleware` summarizer takes `BoundModel` instead of `(Provider, Model)`+- `Middleware.extra_llm_calls()` returns `Iterable[BoundModel]`; tracing recorder + tests adapted+- Doc note added on the providers page++## Test plan+- [x] `uv run pytest tests/`+- [x] `uv run ruff check cubepi/ tests/`+- [x] `uv run ruff format --check cubepi/ tests/`+- [x] `uv run mypy cubepi`+EOF+)"+```++- [ ] **Step 4: Enter the PR codex review loop**++Poll `gh api repos/cubeplexai/cubepi/pulls/<#>/comments` every ~2 minutes, resolve feedback, reply `@codex review again` on the PR after pushing fixes. Repeat until clean and CI is green. Then merge.++---++## Self-Review (run before handing off)++1. **Spec coverage** — every item from the conversation is mapped to a task:+ - "Add `BoundModel.generate/stream`" → Task 1, Task 2.+ - "`summarize()` takes `BoundModel`" → Task 3.+ - "`extra_llm_calls()` returns `Iterable[BoundModel]`" → Task 4.+ - Consumer updates (recorder + test mocks) → Task 4 Steps 3–4.+ - Docs requirement (CLAUDE.md) → Task 5.+2. **Placeholders** — none. Every code step has the actual code; commands are concrete.+3. **Type consistency** — `BoundModel.generate` / `BoundModel.stream` signatures mirror `Provider.generate` / `Provider.stream` exactly (verified against `cubepi/providers/base.py:579-603`). Field name `self._summary_model: BoundModel` is used consistently in Tasks 3 and 4.++## Follow-ups (out of scope)++- `Agent.__init__` still does `self._provider = model.provider` then passes them separately into `cubepi/agent/loop.py`. The loop module's `provider=` / `model=` signature is wide enough that converting it deserves its own plan. Track separately.