CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Spec: Thread BoundModel through the agent loop
Status: Draft → user-confirmed design points 2026-06-08.
Goal
Make cubepi/agent/loop.py (and its callers in Agent and
cubepi/tracing/tracer.py) take a single BoundModel instead of a
provider: Provider, model: Model pair. After this change, the only
places that still see a bare Model are:
Providerprotocol / built-in provider implementations (correctly so — providers are below the binding layer).AgentState.modelfield (serialized; provider can't be pickled).- Tracing recorder reading
model.id/model.provider_idoff bound models or state.
User-facing code (Agent construction, middleware, examples, custom loop drivers) can stop carrying the unwrapped pair.
Why now
The 2026-06-08 BoundModel-methods PR (#154, merged as e917128) added
BoundModel.generate() / BoundModel.stream() and migrated
Middleware.extra_llm_calls() to return Iterable[BoundModel]. That left
agent/loop.py as the last load-bearing surface still threading the
unwrapped pair. The follow-up note in
dev/plans/2026-06-08-boundmodel-convenience-methods.md flagged this
explicitly.
Prior art notes
- langgraph and claude-code use string ids + a global provider
registry ("anthropic:claude-3-5-sonnet"). cubepi 0.8 deliberately chose
the opposite — explicit
provider.model("id")binding, no registry — so spec stays serializable and there's no global state. This spec preserves that choice; we only push the existingBoundModeldeeper into the internals. - pi-agent-core has no analog of
BoundModel; its loop takes a pre-bound callable. cubepi keeps explicit types instead of opaque closures, but the runtime effect is similar.
Design points (user-confirmed 2026-06-08)
AgentState.model: Modelstays as-is. State is part of the checkpointer schema; changing its shape forces a schema migration. Loop call sites inAgentswitch frommodel=self._state.modelto passingself._model(theBoundModel). The state'smodelfield remains as a historical / debug record of which spec was used.Resume trusts the caller. When the Agent restores from checkpointer,
self._state.modelcarries the original spec butself._model: BoundModel(set at__init__) is the source of truth for the next loop iteration. No mismatch check — the Agent's currentBoundModelruns; the state's spec is treated as an archived value. If a caller reconstructs an Agent with a different model after restart, that's an intentional model swap and the loop honors it._OneShotSessionmigrates in lock-step.tracer.oneshot()already takes aBoundModelat its public boundary; finish the migration by making_OneShotSessionitself hold aBoundModel(drops theprovider=..., model=model_specconstructor split insidetracer.py:573).
Scope
In scope
cubepi/agent/loop.py: collapseprovider: Provider, model: Modelintomodel: BoundModelacross the six function surfaces:run_agent_loop(public)run_agent_loop_continue(public)run_agent_loop_resume(internal — not in top-level__all__)_run_loop(private)_run_loop_inner(private)_stream_assistant_response(private)- Bodies: replace
await provider.stream(model=spec, ...)etc. withawait model.stream(...)/await model.generate(...).
cubepi/agent/agent.py:- Remove
self._provider: Provider = model.provider(line 165) — the field becomes redundant once loop takesBoundModel. - Replace three loop call sites (664, 688, 959): drop
provider=self._provider, model=self._state.model, passmodel=self._modelinstead. - Keep
self._state.model = model.specat construction (line 169) and leaveAgentState.modeltypedModel— see Design point 1.
- Remove
cubepi/tracing/tracer.py:573:- Migrate
_OneShotSession(defined attracer.py:36) to holdBoundModel._OneShotSession.generateswitches from internalprovider.generate(model=spec, ...)tobound.generate(...). oneshot()no longer needsprovider = model.provider; model_spec = model.spec(lines 477, 573).
- Migrate
cubepi/tracing/recorder.py:292: renamefor bound in extratofor model in extraper the BoundModel naming convention recorded in thefeedback_boundmodel_namingmemory. Update the local variables (spec = model.spec,provider = model.provider) to match.tests/agent/test_loop.py: migrate directrun_agent_loop(...)/run_agent_loop_continue(...)call sites to the new signature (provider=..., model=...→model=bound).CHANGELOG.md[Unreleased]: Breaking + Migration entries for the two publicly exported functions (run_agent_loop,run_agent_loop_continue).- Docs: regenerate API reference (
pnpm apiref) since thecubepitop-level module surface changed.
Out of scope
Providerprotocol and built-in provider implementations (anthropic.py,openai.py,openai_responses.py,faux.py) — they correctly takemodel: Model(the spec) because providers operate below the binding layer.cubepi/providers/models.pyhelpers — operate onModel(the spec).AgentStateshape / checkpointer schema — Design point 1.- Mid-run model swap APIs (e.g.,
agent.set_model(...)) — out of scope;self._modelremains set-once at__init__. - Provider registry / string-id resolution (langgraph style) — explicitly rejected at 0.8 and reaffirmed here.
Breaking surface
Two publicly exported functions change signature:
cubepi.run_agent_loopcubepi.run_agent_loop_continue
Both lose the provider: Provider keyword and replace model: Model
with model: BoundModel. Callers using these stateless-loop entry
points (uncommon — most users build Agent instances) must update.
This is the same shape of breakage as the
Middleware.extra_llm_calls() -> Iterable[BoundModel] change in #154:
documented in CHANGELOG.md under Breaking + Migration, no
backwards-compat shim per project policy
(feedback_breaking_no_shim).
Migration for callers:
# 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=...,
...
)
(run_agent_loop_resume also changes signature but is not in
cubepi/__init__.py's top-level __all__, so it's not a public API
break — internal callers in agent.py migrate together.)
Naming convention
Per feedback_boundmodel_naming: inside the framework, name BoundModel
parameters and locals model (not bound). Call sites read
await model.generate(...) / await model.stream(...), matching the
public Agent(model=...) / provider.model(...) ergonomics. This
includes the recorder.py for bound in extra cleanup.
Non-goals / explicitly-not-changing
Model(the spec class) name. Renaming toModelSpecfor clarity was discussed and deferred — the churn cost outweighs the naming benefit, andModel/BoundModelis a recognizable "data class vs runtime handle" pair (cf.URLvsURLConnection).- Public
Modelconstructor — direct use ofModel(...)remains valid (custom providers, test fixtures, advanced flows).