Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
feat(agent): prepare next model requests without running the loop (#3102)
Call Whitea3dcaa7bc360
diff --git a/core/agent_core/agent/loop.py b/core/agent_core/agent/loop.pyindex c58a17677..532cfc42d 100644--- a/core/agent_core/agent/loop.py+++ b/core/agent_core/agent/loop.py@@ -19,7 +19,7 @@ import secretsimport timefrom collections import dequefrom contextlib import asynccontextmanager, suppress-from copy import deepcopy+from copy import copy, deepcopyfrom dataclasses import asdict, dataclass, field, replacefrom typing import Any, AsyncIterator, Awaitable, Callable, Iterable, Literal, Mapping, Optional, Sequence, TypeVar@@ -70,10 +70,13 @@ from core.agent_core.agent.jobs import TrackingJobHostfrom core.agent_core.agent.lifecycle import RunAborted as _Aborted, RunScopefrom core.agent_core.agent.models import ModelRouter, ModelSelection, RetryPolicyfrom core.agent_core.agent.outcome import OutcomeOwner+from core.agent_core.agent.preview import ContextTransition, RequestPreviewfrom core.agent_core.agent.state import HookStateError, state_representationfrom core.agent_core.ai._common import endpoint_origin, native_hosted_tools, portable_endpoint, search_history_endpoint+from core.agent_core.ai.preview import preview_wire_requestfrom core.agent_core.ai.provider import (Done,+ MediaLoader,ModelEndpoint,ModelRequest,ProviderError,@@ -144,6 +147,7 @@ from core.agent_core.harness.projection import (ContextView,ProjectionError,context_view,+ open_tool_calls,project,validate_message_append,)@@ -334,6 +338,14 @@ class _Attempt:audited: bool = False+@dataclass(frozen=True)+class _PreparedConversation:+ request: ModelRequest+ tools: dict[str, Tool]+ view: ContextView+ budget: Budget | None++@dataclass(frozen=True)class _Outcome:ok: bool@@ -481,6 +493,75 @@ class Agent:seq = self._rows[-1].context_seq if self._rows else 0return Snapshot(self.session_id, seq, deepcopy(self._committed_state))+ async def dry_tick(+ self,+ *,+ selected: ModelSelection,+ entries: Sequence[ContextEntry] | None = None,+ context_seq: int | None = None,+ turn_inputs: Iterable[int] = (),+ gateway: bool = False,+ media_loader: MediaLoader | None = None,+ ) -> RequestPreview:+ """Reconstruct the next request at a committed cut, without running it.++ ``selected`` is explicit: resolving a router can activate a gateway or+ mutate its retry state. The host supplies a read-only route description.+ The current Agent configuration is used, not an invented historical+ system/tools/route snapshot. Hooks and pending client tools block a dry+ tick because their effects cannot safely be predicted. No hook, context+ transition, transcript write, model send or tool execution occurs here.+ """+ if context_seq is not None and (type(context_seq) is not int or context_seq < 0):+ raise ValueError("context_seq must be a nonnegative integer")+ async with self._lock:+ if self._running:+ raise RuntimeError("cannot preview an Agent with an active run")+ rows = deepcopy(list(entries if entries is not None else await self.store.load(self.session_id)))+ head = max((row.context_seq for row in rows), default=0)+ if context_seq is not None and context_seq > head:+ raise ValueError("context_seq is beyond the committed context")+ if context_seq is not None:+ rows = [row for row in rows if row.context_seq <= context_seq]+ projection = project(rows)+ snapshot = Snapshot(+ self.session_id, max((row.context_seq for row in rows), default=0), deepcopy(dict(projection.state))+ )+ if self.hooks or self.rehydrate is not None:+ return RequestPreview(snapshot, "unsupported_hooks")+ if open_tool_calls(rows):+ return RequestPreview(snapshot, "pending_tools")+ # Only detached preparation state changes. Dependencies are shared+ # read-only; none of the run, commit or execution methods is entered.+ preparing = copy(self)+ preparing._rows = rows+ preparing._ctx = RunContext(self.session_id, "", CancelToken(), deepcopy(dict(projection.state)))+ preparing._scope = RunScope(preparing._ctx.cancel)+ preparing._run_tools = None+ preparing._turn_inputs = {seq for seq in turn_inputs if 0 < seq <= snapshot.context_seq}+ preparing._unproductive = 0+ preparing._last_model_at = {}+ preparing._refusals = _Refusals(opaque=set(projection.opaque_refused))+ if preparing.context is not None:+ now = preparing.context.clock()+ preparing.context = replace(preparing.context, clock=lambda: now)+ route = preparing._refusals.render(deepcopy(selected), portable=False)+ prepared = await preparing._prepare_conversation(preparing.system, route)+ transition = (+ preparing._context_transition(prepared.request, prepared.view, prepared.budget, _Ladder())+ if prepared.budget is not None else None+ )+ facts = dict(+ request=prepared.request, capabilities=route.capabilities, budget=prepared.budget,+ turn_inputs=tuple(sorted(preparing._turn_inputs)),+ )+ if transition is not None:+ return RequestPreview(snapshot, "needs_context_transition", transition=transition, **facts)+ wire = await preview_wire_request(prepared.request, gateway=gateway, media_loader=media_loader)+ if isinstance(wire, ProviderError):+ return RequestPreview(snapshot, "preparation_error", error=wire, **facts)+ return RequestPreview(snapshot, "ready", wire=wire, **facts)+def run(self, input: AgentInput, *, turn_id: str) -> AsyncIterator[AgentEvent]:input = deepcopy(input)return self._pump(turn_id, lambda emit: self._drive(emit, input, consume=True))@@ -1630,18 +1711,44 @@ class Agent:last = used.get(_cache_of(endpoint_origin(endpoint)), max(used.values(), default=None))return last is not None and self.context.clock() - last > cache_ttl_s(endpoint)+ async def _prepare_conversation(self, system: str, selected: ModelSelection) -> _PreparedConversation:+ """Compose and budget before any context transition; also used by dry_tick."""+ view = context_view(self._rows)+ request, tools = await self._request(system, selected, messages=self._carried(view))+ plan = (+ budget(request, selected.capabilities, transcript=view.messages, anchor=last_anchor(self._rows, view))+ if self.context is not None else None+ )+ return _PreparedConversation(request, tools, view, plan)++ def _context_transition(+ self, request: ModelRequest, view: ContextView, plan: Budget, ladder: _Ladder,+ *, minimal_checked: bool = False,+ ) -> ContextTransition | None:+ """Select the next effect without applying it, for both live and dry preparation."""+ if (not plan.can_fit and not minimal_checked) or ladder.refused:+ return "context_relief"+ if self.context.clear_tool_results and (+ plan.est >= CLEAR_SOFT_RATIO * plan.threshold or self._cache_cold(request.endpoint)+ ) and clearable_results(view):+ return "clear_tool_results"+ if plan.est >= plan.threshold and not ladder.compacted and not self._stopped:+ if normal_cut(view.units, plan.keep, turn_inputs=self._turn_inputs, pinned=view.pinned) is not None:+ return "checkpoint"+ if plan.fits or ((ladder.summary_failed or self._stopped) and plan.can_fit):+ return None+ return "context_relief"+async def _compose(self, system: str, selected: ModelSelection, emit: Callable[..., Awaitable[None]], ladder: _Ladder) -> tuple[ModelRequest, dict[str, Tool]]:- """The conversation request pipeline (invariant 1)."""+ """Prepare, apply any required context transition, and prepare again."""while True:- view = context_view(self._rows)- request, tools = await self._request(system, selected, messages=self._carried(view))- if self.context is None:- return request, tools- plan = budget(request, selected.capabilities, transcript=view.messages, anchor=last_anchor(self._rows, view))- if not await self._stage(system, selected, request, view, plan, emit, ladder):- return request, tools+ prepared = await self._prepare_conversation(system, selected)+ if prepared.budget is None or not await self._stage(+ system, selected, prepared.request, prepared.view, prepared.budget, emit, ladder,+ ):+ return prepared.request, prepared.toolsasync def _stage(self,@@ -1658,13 +1765,12 @@ class Agent:Whether the run still takes checkpoints is read from its live bound at every decision, never kept: acheckpoint attempt in this pass can use it up."""- # Once the run takes no more checkpoints, only a drop can follow, and only for a request that cannot fit or- # that the provider refused; for one that will be sent as it is, nothing is built for a compaction.- compacting = not plan.can_fit or ladder.refused- if not self._stopped:- compacting = compacting or plan.est >= plan.threshold or not plan.fits- if compacting:- # A compaction may follow: what a person typed, for its memo, read off the event loop first.+ transition = self._context_transition(request, view, plan, ladder)+ if transition is None:+ return False+ # A compaction may follow: read memo input off the event loop only on+ # the live effect path. Dry preparation stops at the decision above.+ if transition != "clear_tool_results":await self._prefetch_typed(view)if not plan.can_fit:_, minimal = await self._minimal(system, selected, request, view, plan, carry=False)@@ -1677,17 +1783,16 @@ class Agent:if await self._fit_batch(view, (room - minimal.margin, room)):return Trueraise self._exhausted(request, view, plan, kind=self._cause(view, minimal))+ # The minimal check is admission, not a replacement for the normal+ # clear/checkpoint ladder. Keep that order even on oversized input.+ transition = self._context_transition(request, view, plan, ladder, minimal_checked=True)refused, ladder.refused = ladder.refused, False+ if transition == "clear_tool_results":+ await self._commit_context([("context_edit", clear_edit(target)) for target in clearable_results(view)])+ return Trueshrink = refusedif not shrink:- if self.context.clear_tool_results and (- plan.est >= CLEAR_SOFT_RATIO * plan.threshold or self._cache_cold(request.endpoint)- ):- targets = clearable_results(view)- if targets:- await self._commit_context([("context_edit", clear_edit(target)) for target in targets])- return True- if plan.est >= plan.threshold and not ladder.compacted and not self._stopped:+ if transition == "checkpoint":cut = normal_cut(view.units, plan.keep, turn_inputs=self._turn_inputs, pinned=view.pinned)if cut is not None:ladder.compacted = Truediff --git a/core/agent_core/agent/preview.py b/core/agent_core/agent/preview.pynew file mode 100644index 000000000..d0d11cb4b--- /dev/null+++ b/core/agent_core/agent/preview.py@@ -0,0 +1,33 @@+"""Detached diagnostics for one committed Agent context cut.++A preview is a current-code reconstruction. Only transport artifacts establish+historical sent bytes. Sensitive inputs and wire data deliberately have no repr.+"""+from __future__ import annotations++from dataclasses import dataclass, field+from typing import Literal++from core.agent_core.agent.hooks import Snapshot+from core.agent_core.ai.preview import WirePreview+from core.agent_core.ai.provider import ModelCapabilities, ModelRequest, ProviderError+from core.agent_core.harness.context import Budget++PreviewStatus = Literal[+ "ready", "needs_context_transition", "pending_tools", "unsupported_hooks", "preparation_error",+]+ContextTransition = Literal["clear_tool_results", "checkpoint", "context_relief"]+++@dataclass(frozen=True)+class RequestPreview:+ snapshot: Snapshot = field(repr=False)+ status: PreviewStatus+ request: ModelRequest | None = field(default=None, repr=False)+ capabilities: ModelCapabilities | None = None+ budget: Budget | None = None+ transition: ContextTransition | None = None+ wire: WirePreview | None = field(default=None, repr=False)+ error: ProviderError | None = field(default=None, repr=False)+ turn_inputs: tuple[int, ...] = ()+ mode: Literal["reconstructed"] = "reconstructed"diff --git a/core/agent_core/ai/preview.py b/core/agent_core/ai/preview.pynew file mode 100644index 000000000..ea7e83230--- /dev/null+++ b/core/agent_core/ai/preview.py@@ -0,0 +1,58 @@+"""Read-only provider preparation, using the adapters' production wire builders.++This prepares the first HTTP request only. It never opens a client, sends a+request, retries, or follows an Anthropic pause. Authentication remains in the+in-memory WireRequest; callers must not serialize it to a diagnostic artifact.+"""+from __future__ import annotations++import hashlib+from dataclasses import dataclass, field++import httpx++from core.agent_core.ai._common import WireRequest, endpoint_origin, prepare_messages+from core.agent_core.ai.provider import MediaLoader, ModelRequest, ProviderError+from core.agent_core.cancel import CancelToken+++@dataclass(frozen=True)+class WirePreview:+ wire: WireRequest = field(repr=False)+ body: bytes = field(repr=False)+ body_sha256: str+++async def preview_wire_request(+ request: ModelRequest, *, gateway: bool = False, media_loader: MediaLoader | None = None,+) -> WirePreview | ProviderError:+ """Compile without sending; use HTTPX's JSON encoder, as ``build_request`` does.++ The input must already have passed the Agent's context-transition check.+ Media is loaded through the same immutable snapshot loader as a real send.+ """+ from core.agent_core.ai import anthropic, google, openai_chat, openai_responses++ builders = {+ "anthropic": anthropic.wire_request,+ "openai_responses": openai_responses.wire_request,+ "openai_chat": openai_chat.wire_request,+ "google": google.wire_request,+ }+ protocol = request.endpoint.protocol+ builder = builders.get(protocol)+ if builder is None:+ raise ValueError(f"Unsupported preview protocol: {protocol}")+ prepared = await prepare_messages(+ request.messages, target=endpoint_origin(request.endpoint),+ supports_images=request.supports_images, protocol=protocol,+ media_loader=media_loader, cancel=CancelToken(), endpoint=request.endpoint,+ )+ if isinstance(prepared, ProviderError):+ return prepared+ messages, images = prepared+ wire = builder(request, messages, gateway=gateway, loaded_images=images)+ # AsyncClient.build_request delegates JSON serialization to Request, too.+ # No client construction (or environment/proxy/credential lookup) is needed.+ body = httpx.Request("POST", wire.url, headers=wire.headers, json=wire.body).content+ return WirePreview(wire, body, hashlib.sha256(body).hexdigest())diff --git a/docs/plans/agent-request-preview.md b/docs/plans/agent-request-preview.mdnew file mode 100644index 000000000..863da9d27--- /dev/null+++ b/docs/plans/agent-request-preview.md@@ -0,0 +1,50 @@+# Next-request preview and debug replay++## Contract++The Agent's next-request preparation is shared by its live loop and a read-only+`dry_tick`. A preview at a committed context cut uses current code, route, tools,+and system instructions. It is explicitly a reconstruction, not a claim about+historical wire bytes. Transport failure artifacts are the separate source of+historical actual bytes.++- Preview never enters a run, executes a tool, calls a generation model, invokes+ user hooks, writes transcript/state, or performs context relief/compaction.+- Preparation returns `needs_context_transition` when the live loop would first+ clear results, compact or relieve overflow. It does not advertise that candidate+ as the next send. Pending tools, active runs and arbitrary hooks are explicit+ blockers, not silently ignored work.+- Canonical preparation, refusal projection, budgeting and provider transforms+ reuse the live owners. All four wire protocols use their existing wire builders+ and the same HTTPX JSON serializer as transport.+- Snapshot metadata identifies session/cut, route, compiler/package version,+ configuration and request hash. A context sequence alone is not a frozen request.+- Protected local export contains complete bytes; ordinary CLI output contains+ summaries only. Credentials are never exported. Replay is opt-in, one HTTP+ request outside the Agent Loop, no client tool executor or automatic follow-up.+ Native server tools require an explicit acknowledgement; exact replay never+ silently removes a tool or rewrites a signed body.++## Ownership++This PR owns Agent preparation/preview, protected request export and local+single-request debugging. A separate transport-artifact PR owns pending/error+capture and retention, with no dependency on this PR's unmerged interfaces.+Neither changes historical rendering or claims to repair the investigated 400.++## Verification++Primary tests compare preview bytes against requests captured by a real HTTPX+MockTransport for every provider. State/store/tool/model spies enforce dry-run+boundaries. Context planning tests cover ready vs clear/checkpoint/overflow and+run the existing context suite to protect normal loop semantics. Historical cuts+must not include later refusals/checkpoints. CLI tests cover protected output,+local authorization and no generation on preview; replay tests prove one send,+no client tools and explicit native-tool consent.++## Delivery++Implement, focused checks, independent review, exact-head Codex review and CI,+merge. Then publish one GitHub-only pre-release, install its wheel on the host,+restart with durable continuation and verify the running version. Continue the+original investigation using this capability; do not resume the original task.diff --git a/tests/agent_core/agent/test_request_preview.py b/tests/agent_core/agent/test_request_preview.pynew file mode 100644index 000000000..2af460bd6--- /dev/null+++ b/tests/agent_core/agent/test_request_preview.py@@ -0,0 +1,148 @@+"""Dry ticks protect the first-send boundary, not a second imitation of the loop.++Existing loop tests exercise effects; they cannot establish that diagnostics are+read-only or that exported bytes match the adapter's actual HTTPX request.+"""+from copy import deepcopy+from dataclasses import replace++import httpx+import pytest++from core.agent_core.agent.hooks import Hooks+from core.agent_core.agent.loop import Agent+from core.agent_core.ai.provider import ModelCapabilities+from core.agent_core.ai.registry import ADAPTERS, create_adapter+from core.agent_core.harness.context import ContextConfig+from core.agent_core.messages import ToolCallBlock, ToolResultMessage, text+from tests.agent_core.fakes import (+ SELECTION, FakeJobHost, FakeModelRouter, FakeTool, InMemoryTranscriptStore,+ ScriptedProvider, assistant, input_row, user,+)+++def agent_for(router, store, **kwargs):+ return Agent(+ session_id="session", models=router, tools=kwargs.pop("tools", ()),+ hooks=kwargs.pop("hooks", ()), store=store, jobs=FakeJobHost(),+ cwd="/test-owned", system="Keep Unicode: 中文 and café", **kwargs,+ )++[email protected]("protocol", sorted(ADAPTERS))+async def test_dry_tick_matches_live_resume_transport_bytes_without_any_effect(protocol):+ sent = []++ def capture(request):+ sent.append(request)+ return httpx.Response(400, json={"error": {"message": "synthetic rejection"}})++ selected = replace(SELECTION, endpoint=replace(SELECTION.endpoint, protocol=protocol))+ store = InMemoryTranscriptStore()+ await store.consume_input("session", "input", user("Exact 中文 / quoted \" input"))+ tool = FakeTool("do_not_execute")+ before = deepcopy(store.__dict__)+ async with httpx.AsyncClient(transport=httpx.MockTransport(capture)) as client:+ adapter = create_adapter(protocol, client=client)+ router = FakeModelRouter(adapter, (selected,))+ agent = agent_for(router, store, tools=(tool,), context=ContextConfig())+ original_snapshot = agent.snapshot()+ preview = await agent.dry_tick(selected=selected)+ assert preview.status == "ready"+ assert preview.wire is not None+ assert preview.snapshot.context_seq == 1+ assert router.resolutions == 0 and router.protocols == [] and sent == []+ assert store.__dict__ == before and agent.snapshot() == original_snapshot+ assert tool.calls == []+ events = [event async for event in agent.resume(input_row("control", "not consumed"), turn_id="debug-test")]+ assert events[-1].reason == "error"+ assert len(sent) == 1+ assert sent[0].content == preview.wire.body+ assert sent[0].url == httpx.URL(preview.wire.wire.url)+ assert tool.calls == []+++async def test_preview_cut_excludes_later_state_and_refusals_and_detaches_its_inputs():+ store = InMemoryTranscriptStore()+ await store.consume_input("session", "first", user("earlier"))+ await store.append_payload("session", "agent_state", {"version": 1, "state": {"safe": [1]}})+ await store.append_payload("session", "replay_refusal", {+ "version": 1, "source_identity": "identity", "payloads": ["hosted"],+ })+ await store.consume_input("session", "later", user("must not enter the earlier cut"))+ router = FakeModelRouter(ScriptedProvider([]))+ agent = agent_for(router, store)+ before = deepcopy(store.__dict__)+ early = await agent.dry_tick(selected=SELECTION, context_seq=2)+ now = await agent.dry_tick(selected=SELECTION)+ assert early.status == now.status == "ready"+ assert early.snapshot.state == {"safe": [1]}+ assert early.request.endpoint.opaque_refused == frozenset()+ assert now.request.endpoint.opaque_refused == frozenset({("identity", "hosted")})+ assert b"must not enter" not in early.wire.body+ assert b"must not enter" in now.wire.body+ early.snapshot.state["safe"].append(2)+ assert store.__dict__ == before+ assert router.resolutions == 0+ with pytest.raises(ValueError, match="beyond"):+ await agent.dry_tick(selected=SELECTION, context_seq=5)+ with pytest.raises(ValueError, match="nonnegative"):+ await agent.dry_tick(selected=SELECTION, context_seq=True)++[email protected]("blocker", ["hook", "rehydrate", "pending"])+async def test_unpredictable_steps_are_reported_without_invoking_them(blocker):+ class UnsafeHook(Hooks):+ async def before_model(self, request, ctx):+ pytest.fail("dry_tick invoked a hook")++ def unsafe_rehydrate(state):+ pytest.fail("dry_tick invoked arbitrary rehydration")++ store = InMemoryTranscriptStore()+ await store.consume_input("session", "first", user("hello"))+ if blocker == "pending":+ await store.append_response("session", assistant("", calls=[ToolCallBlock("call", "side_effect", {})]), final=False)+ agent = agent_for(+ FakeModelRouter(ScriptedProvider([])), store,+ hooks=(UnsafeHook(),) if blocker == "hook" else (),+ rehydrate=unsafe_rehydrate if blocker == "rehydrate" else None,+ )+ before = deepcopy(store.__dict__)+ preview = await agent.dry_tick(selected=SELECTION)+ assert preview.status == ("pending_tools" if blocker == "pending" else "unsupported_hooks")+ assert preview.request is None and preview.wire is None+ assert store.__dict__ == before++[email protected]("transition", ["checkpoint", "context_relief", "clear_tool_results"])+async def test_context_effects_are_planned_not_applied(transition):+ store = InMemoryTranscriptStore(clock=lambda: 1.0)+ selected = replace(SELECTION, capabilities=ModelCapabilities(+ context_window=64_000, input_limit=32_000, max_output_tokens=4096, supports_tools=True,+ ))+ if transition == "clear_tool_results":+ selected = replace(selected, capabilities=replace(+ selected.capabilities, context_window=160_000, input_limit=128_000,+ ))+ for index in range(9):+ await store.consume_input("session", f"input{index}", user("question"))+ await store.append_response("session", assistant("", calls=[ToolCallBlock(f"call{index}", "read", {})]), final=False)+ await store.append_tool_result("session", ToolResultMessage(f"call{index}", "read", (text("x" * 25_000),)), details={})+ await store.append_response("session", assistant("answer"), final=True)+ elif transition == "checkpoint":+ for index in range(4):+ await store.consume_input("session", f"input{index}", user("x" * 24_000))+ await store.append_response("session", assistant("answer"), final=True)+ else:+ await store.consume_input("session", "huge", user("x" * 200_000))+ provider = ScriptedProvider([])+ agent = agent_for(FakeModelRouter(provider), store, context=ContextConfig(+ clear_tool_results=transition == "clear_tool_results", clock=lambda: 10_000.0,+ ))+ before = deepcopy(store.__dict__)+ preview = await agent.dry_tick(selected=selected)+ assert preview.status == "needs_context_transition"+ assert preview.transition == transition+ assert preview.request is not None and preview.wire is None+ assert provider.requests == [] and store.__dict__ == before