CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Loop BoundModel Migration Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans or superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Push BoundModel through cubepi/agent/loop.py and its consumers (Agent, tracer.oneshot's _OneShotSession, the recorder cleanup, the loop tests) in one atomic refactor, so the only places that still see a bare Model are the Provider protocol / impls and the serializable AgentState.model field.
Architecture: Collapse provider: Provider, model: Model → model: BoundModel across six loop function signatures (run_agent_loop, run_agent_loop_continue, run_agent_loop_resume, _run_loop, _run_loop_inner, _stream_assistant_response). The single in-body provider call (provider.stream(...) at loop.py:723) becomes model.stream(...) via the BoundModel.stream convenience added in #154. All consumers (Agent.__init__ + three loop call sites, _OneShotSession and tracer.oneshot, the recorder.py for bound in extra rename, tests/agent/test_loop.py direct call sites) flip in the same commit. Tests stay green at every commit boundary.
Tech Stack: Python 3.11+, dataclasses, BoundModel (added in #154), pytest with asyncio_mode=auto, FauxProvider for deterministic tests, ruff, mypy.
File Structure
- Modify
cubepi/agent/loop.py— six function signatures loseprovider: Provider, gainmodel: BoundModel; one body call (line 723) flips tomodel.stream(...);Provider/Modelimports drop. - Modify
cubepi/agent/agent.py— removeself._provider: Provider = model.provider(line 165); the three loop call sites (664, 688, 959) replaceprovider=self._provider, model=self._state.modelwithmodel=self._model;Providerimport drops if unused. - Modify
cubepi/tracing/tracer.py—_OneShotSessiondataclass (~line 36) holdsBoundModelinstead of splitprovider+model;_OneShotSession.generatecallsbound.generate(...); theoneshot()body (provider = model.provider; model_spec = model.spec;_OneShotSession(provider=..., model=model_spec, ...)) simplifies to pass theBoundModelthrough. - Modify
cubepi/tracing/recorder.py:292— renamefor bound in extra→for model in extra, plus the localspec = bound.spec/provider = bound.provider→spec = model.spec/provider = model.provider. (Cosmetic, perfeedback_boundmodel_namingconvention.) - Modify
tests/agent/test_loop.py— delete themake_model()helper; everyprovider = FauxProvider(); ... provider=provider, model=make_model()block becomesprovider = FauxProvider(provider_id="faux"); ... model=provider.model("faux-1"). Drop unusedModelimport if applicable. - Modify
CHANGELOG.md[Unreleased]— Breaking + Migration entries for the two publicly exported functions (cubepi.run_agent_loop,cubepi.run_agent_loop_continue). - Modify
website/docs/api/*.mdx— regenerate viapnpm apirefsince thecubepitop-level surface changed.
Task 1: Atomic BoundModel migration (loop + agent + tracer + recorder + tests)
Why atomic: loop.py is the producer of the new signature; Agent, _OneShotSession, the loop tests, and (cosmetically) the recorder all consume. Splitting these commits would leave any intermediate commit with broken tests. Same rationale as Task 3 in the #154 plan.
- Step 0: Confirm scope by greppping for any external callers we'd miss
cd /home/chris/cubepi/.worktrees/2026-06-08-loop-boundmodel
grep -rn "run_agent_loop\|_run_loop\|_stream_assistant_response\|_OneShotSession" cubepi/ tests/ examples/ --include="*.py"
Expected hits: cubepi/__init__.py (re-exports), cubepi/agent/__init__.py (re-exports), cubepi/agent/agent.py (callers), cubepi/agent/loop.py (definitions), cubepi/tracing/tracer.py (_OneShotSession), tests/agent/test_loop.py (direct callers). If anything else shows up (e.g. an example script using run_agent_loop directly), fold it into the migration.
- Step 1: Baseline test run
uv run pytest tests/ -x 2>&1 | tail -3
Expected: PASS. Record the totals — must be the same after Task 1.
- Step 2: Migrate
cubepi/agent/loop.pysignatures + body
Edit each of the six functions: replace provider: Provider, + model: Model, (two lines) with model: BoundModel, (one line). Then in _stream_assistant_response (around line 723), replace:
stream = await provider.stream(
model=model,
messages=messages,
system_prompt=system_prompt,
tools=tools,
options=options,
)
with:
stream = await model.stream(
messages=messages,
system_prompt=system_prompt,
tools=tools,
options=options,
)
Update imports at the top of the file: drop Model and Provider from the cubepi.providers.base import line, add BoundModel. Verify with grep -n "Provider\b\|Model\b" cubepi/agent/loop.py — after editing, neither bare name should appear in the file body (only as BoundModel).
Internal call sites between the six functions: each _run_loop/_run_loop_inner call previously passed provider=provider, model=model — switch to model=model (the BoundModel parameter).
- Step 3: Migrate
cubepi/agent/agent.py
Three changes in agent.py:
(a) Drop self._provider: Provider = model.provider (line 165). The self._model field already holds the same provider via self._model.provider.
(b) Update the three loop call sites (around lines 664, 688, 959). Currently each looks like:
lambda signal: run_agent_loop(
...
provider=self._provider,
model=self._state.model,
...
)
Replace with:
lambda signal: run_agent_loop(
...
model=self._model,
...
)
(self._state.model was the spec; self._model is the BoundModel — that's the source of truth post-migration.)
(c) Drop Provider from imports if no longer used (verify with grep -n "Provider\b" cubepi/agent/agent.py — only BaseProvider-style names should remain, if any).
self._state.model = model.spec at construction (around line 169) stays as-is. The AgentState.model: Model field stays as-is. (Design point 1 in the spec.)
- Step 4: Migrate
_OneShotSession+tracer.oneshot()
In cubepi/tracing/tracer.py, _OneShotSession (around line 36) is a dataclass holding provider + model + run. Change to hold a single model: BoundModel + run. Find the call sites:
_OneShotSession.generate(...)body: replace internalprovider.generate(...)(currently passesmodel=self.model) withself.model.generate(...).Tracer.oneshot()(around line 419): the linesprovider = model.provider; model_spec = model.specand the_OneShotSession(provider=provider, model=model_spec, run=run)instantiation. Replace with_OneShotSession(model=model, run=run). Drop the two local variables.
The public Tracer.oneshot(*, model: BoundModel, ...) signature is unchanged — only internals migrate.
- Step 5: Rename
for bound in extra→for model in extrain recorder
In cubepi/tracing/recorder.py:292, the current block:
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)
becomes:
for model in extra:
spec = model.spec
key = (spec.provider_id, spec.id)
if key != agent_key:
self._extra_call_models.add(key)
provider = model.provider
if id(provider) in seen:
continue
seen.add(id(provider))
_subscribe(provider)
Pure cosmetic — no behavior change. Matches the feedback_boundmodel_naming convention. No imports change.
- Step 6: Migrate
tests/agent/test_loop.pyto the new signature
Two edits:
(a) Delete the make_model() helper (lines 29–30).
(b) Every test method has a block like:
provider = FauxProvider()
# ...
result = await run_agent_loop(
...
provider=provider,
model=make_model(),
...
)
Change to:
provider = FauxProvider(provider_id="faux")
# ...
result = await run_agent_loop(
...
model=provider.model("faux-1"),
...
)
Drop Model from the top-level cubepi.providers.base import if it's no longer referenced elsewhere in the file (verify with grep -n "\bModel\b" tests/agent/test_loop.py).
- Step 7: Run the affected suites, then the full sweep + lint + types
uv run pytest tests/agent/ tests/tracing/ -v 2>&1 | tail -10
Expected: PASS. Specifically tests/agent/test_loop.py should report the same number of tests passing as before.
uv run pytest tests/ -x 2>&1 | tail -3
uv run ruff check cubepi/ tests/
uv run ruff format --check cubepi/ tests/
uv run mypy cubepi
Expected: all green. If ruff format flags reformatting, run uv run ruff format cubepi/ tests/ then re-check.
- Step 8: Commit
git add cubepi/agent/loop.py cubepi/agent/agent.py cubepi/tracing/tracer.py cubepi/tracing/recorder.py tests/agent/test_loop.py
git commit -m "refactor(agent): thread BoundModel through loop, agent, oneshot, recorder"
Task 2: CHANGELOG
- Step 1: Add Breaking + Migration entries under
[Unreleased]
In CHANGELOG.md, extend the existing [Unreleased] block (which already contains the BoundModel.generate/stream + extra_llm_calls entries from #154) with one new Breaking bullet:
- **`cubepi.run_agent_loop` and `cubepi.run_agent_loop_continue` take
`model: BoundModel`** instead of separate `provider: Provider, model: Model`
kwargs. The stateless-loop entry points used by callers who drive the loop
outside of `Agent` must update. The `Agent` API is unchanged — it has always
taken `model: BoundModel`.
And one new Migration example:
- Stateless-loop callers (uncommon — most users build an `Agent`):
```python
# Before
await run_agent_loop(
prompts=[...],
context=ctx,
provider=provider,
model=model_spec,
convert_to_llm=...,
emit=...,
)
# After
await run_agent_loop(
prompts=[...],
context=ctx,
model=provider.model("id", ...),
convert_to_llm=...,
emit=...,
)
- [ ] **Step 2: Commit**
```bash
git add CHANGELOG.md
git commit -m "docs(changelog): record run_agent_loop BoundModel migration"
Task 3: Regenerate API reference docs
- Step 1: Run apiref
cd website && pnpm apiref 2>&1 | tail -10 && cd -
Expected: a handful of website/docs/api/*.mdx files update — at minimum cubepi.mdx (signature of run_agent_loop / run_agent_loop_continue) and cubepi-middleware.mdx (which had a stale extra_llm_calls() -> Iterable[tuple[Provider, Model]] line from #154 that this regen also fixes).
- Step 2: Verify the stale references are gone
grep -rn "extra_llm_calls.*tuple\|tuple\[Provider, Model\]\|provider: Provider,\s*model: Model" website/docs/api/
Expected: no hits.
- Step 3: Diff sanity check + commit
git status website/docs/api/
git diff --stat website/docs/api/
Confirm the diff only touches the expected mdx files (signatures involving run_agent_loop*, extra_llm_calls, and possibly oneshot).
git add website/docs/api/
git commit -m "docs(apiref): regenerate after BoundModel loop migration"
Task 4: Open PR + PR codex review loop
- Step 1: Push branch
git push -u origin 2026-06-08-loop-boundmodel
- Step 2: Open PR
gh pr create --title "refactor(agent): thread BoundModel through loop, oneshot, recorder" --body "$(cat <<'EOF'
## Summary
- Migrate `cubepi/agent/loop.py` (6 function signatures) from `provider: Provider, model: Model` → `model: BoundModel`. The single in-body `provider.stream(...)` flips to `model.stream(...)` via the convenience added in #154.
- `Agent.__init__` drops the redundant `self._provider` field; three loop call sites pass `model=self._model` instead of the split pair. `AgentState.model: Model` field unchanged — it stays serializable for the checkpointer.
- `_OneShotSession` (used by `tracer.oneshot()`) holds a `BoundModel` internally; `oneshot()` no longer extracts `provider` / `model_spec` separately.
- Recorder cleanup: `for bound in extra` → `for model in extra` per the `feedback_boundmodel_naming` convention.
- `tests/agent/test_loop.py` migrated; `make_model()` helper removed in favor of inline `provider.model("faux-1")`.
- API reference regenerated.
## Workflow
- Spec at `dev/specs/2026-06-08-loop-boundmodel.md` (user-confirmed design: AgentState.model stays Model, resume trusts caller, OneShot migrates lock-step).
- Plan at `dev/plans/2026-06-08-loop-boundmodel.md`.
- Per user direction, skipped local codex review on spec/plan/code — going straight to PR codex review.
## Breaking
`cubepi.run_agent_loop` and `cubepi.run_agent_loop_continue` change signature. See `CHANGELOG.md` Breaking + Migration sections under `[Unreleased]`.
## 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 3: Enter PR codex review loop
Poll the PR every ~2 minutes; for every codex finding, evaluate against project policy (feedback_breaking_no_shim, feedback_boundmodel_naming), fix or push back with rationale, push commit(s), reply @codex review again. Repeat until clean. Merge after CI + codex both green.
Self-Review
- Spec coverage — every spec scope item maps to a Task 1 step:
- Loop six function migration → Step 2.
- Agent: drop
_provider, three call sites → Step 3. _OneShotSession+tracer.oneshot()→ Step 4.- Recorder rename → Step 5.
tests/agent/test_loop.pymigration → Step 6.- CHANGELOG → Task 2.
- apiref → Task 3.
- Atomicity — Task 1 is one commit covering loop + agent + tracer + recorder + tests; producer/consumer flip together so
pytest -xstays green at every commit boundary. - Placeholders — none. Every step has the actual code change or a concrete grep / pytest / commit command.
- Naming convention — every variable rename and parameter name uses
model: BoundModelperfeedback_boundmodel_naming. No leftoverbound/bound_model. - Out of scope — Provider protocol & impls,
AgentStateshape,Modelrename, mid-run model swap. All match the spec.
Follow-ups (out of scope)
None for this work. The original Follow-up #2 from the #154 plan is what this plan executes; no further follow-ups required.