Skip to content

armgit / avibe

Public Imported from GitHub
0

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.

fix(agent-core): estimate replayed reasoning by its usage, keep the anchor across clearing, clear on each route's cache lifetime (#2485)

Call White3cfc141daf20
diff --git a/core/agent_core/agent/loop.py b/core/agent_core/agent/loop.py
index 862528c99..74fb852b2 100644
--- a/core/agent_core/agent/loop.py
+++ b/core/agent_core/agent/loop.py
@@ -67,8 +67,10 @@ from core.agent_core.agent.lifecycle import RunAborted as _Aborted, RunScope
from core.agent_core.agent.models import ModelRouter, ModelSelection, RetryPolicy
from core.agent_core.agent.outcome import OutcomeOwner
from core.agent_core.agent.state import HookStateError, state_representation
+from core.agent_core.ai._common import endpoint_origin
from core.agent_core.ai.provider import (
Done,
+ ModelEndpoint,
ModelRequest,
ProviderError,
TextDelta,
@@ -89,6 +91,7 @@ from core.agent_core.harness.context import (
StateRequest,
add_usage,
budget,
+ cache_ttl_s,
checkpoint_block,
checkpoint_max_tokens,
checkpoint_repair,
@@ -125,6 +128,7 @@ from core.agent_core.harness.store import ContextEntry, EntryKind, TranscriptSto
from core.agent_core.messages import (
AssistantMessage,
Message,
+ Origin,
TextBlock,
ToolCallBlock,
ToolResultMessage,
@@ -173,6 +177,12 @@ class _Exhausted(Exception):
_CHECKPOINT_REQUEST = checkpoint_request()
+def _cache_of(origin: Origin) -> tuple[str, str]:
+ """The upstream prompt cache an origin's requests use: its provider and model (C-9 section 3). The protocol that
+ reaches the gateway, converted or not (a Google hop is called over Chat), does not change the cache."""
+ return origin.provider, origin.model
+
+
async def _silent(*_: Any, **__: Any) -> None:
"""A side turn's emit: it shows nothing (C-10 section 7)."""
@@ -280,7 +290,9 @@ class Agent:
self._turn_inputs: set[int] = set()
# The run's attempt ledger (C-9): every model attempt, in order.
self._attempts: list[_Attempt] = []
- self._last_model_at: Optional[float] = None
+ # When each upstream prompt cache was last used in this Agent: the end of its latest model call, by the provider
+ # and model that served it (``_cache_of``, C-9 section 3).
+ self._last_model_at: dict[tuple[str, str], float] = {}
self._seq = 0
def set_tools(self, tools: Sequence[Tool]) -> None:
@@ -738,10 +750,12 @@ class Agent:
await emit(AssistantTextDelta, delta=event.delta)
elif isinstance(event, ThinkingDelta):
await emit(AssistantThinkingDelta, delta=event.delta)
- if self.context is not None:
- self._last_model_at = self.context.clock()
if terminal is None:
terminal = ProviderError("unknown", "Provider stream ended without a terminal event.", False)
+ if self.context is not None:
+ served = terminal.message if isinstance(terminal, Done) else terminal.partial
+ upstream = served.origin if served is not None else endpoint_origin(request.endpoint)
+ self._last_model_at[_cache_of(upstream)] = self.context.clock()
self._attempts.append(
_Attempt(
purpose,
@@ -1187,14 +1201,20 @@ class Agent:
# C-10 section 7), ``_commit_context`` (3), ``self._attempts`` with ``_settle_attempts`` and ``side_turn``'s
# one audit (4), ``harness.context.budget`` (5), and ``_model`` (6, admission).
- def _cache_cold(self) -> bool:
- """No model request for longer than the provider cache TTL (section 3)."""
- last = self._last_model_at
- for row in reversed(self._rows):
+ def _cache_cold(self, endpoint: ModelEndpoint) -> bool:
+ """The provider cache of the request's route has gone unused longer than it stays warm (section 3).
+
+ Its use is the latest model call's end or response row's commit served by the route's upstream cache
+ (``_cache_of``), so a long response counts as use until it ends, and a restarted Agent reads the rows. A route
+ with no use in the Session yet takes the latest use of any route: every error leans toward a warm cache.
+ """
+ used = dict(self._last_model_at)
+ for row in self._rows:
if row.kind == "response" and row.created_at is not None:
- last = row.created_at if last is None else max(last, row.created_at)
- break
- return last is not None and self.context.clock() - last > self.context.cache_ttl_s
+ cache = _cache_of(row.message.origin)
+ used[cache] = max(used.get(cache, row.created_at), row.created_at)
+ 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 _compose(
self, system: str, selected: ModelSelection, emit: Callable[..., Awaitable[None]], ladder: _Ladder
@@ -1242,7 +1262,7 @@ class Agent:
shrink = refused
if not shrink:
if self.context.clear_tool_results and (
- plan.est >= CLEAR_SOFT_RATIO * plan.threshold or self._cache_cold()
+ plan.est >= CLEAR_SOFT_RATIO * plan.threshold or self._cache_cold(request.endpoint)
):
targets = clearable_results(view)
if targets:
diff --git a/core/agent_core/harness/context.py b/core/agent_core/harness/context.py
index 1f0deaada..54725667e 100644
--- a/core/agent_core/harness/context.py
+++ b/core/agent_core/harness/context.py
@@ -23,7 +23,7 @@ from dataclasses import dataclass, field
from typing import Any, Callable, Collection, Mapping, Optional, Protocol, Sequence
from core.agent_core.ai._common import endpoint_origin
-from core.agent_core.ai.provider import ModelCapabilities, ModelRequest
+from core.agent_core.ai.provider import ModelCapabilities, ModelEndpoint, ModelRequest
from core.agent_core.harness.projection import ContextView, Unit, context_view
from core.agent_core.harness.store import ContextEntry
from core.agent_core.messages import (
@@ -55,6 +55,10 @@ THRESHOLD_RATIO = 0.9
KEEP_MAX = 20_000
KEEP_RATIO = 0.25
IMAGE_TOKENS = 1_600
+#: A replayed response that reports no usage counts its opaque reasoning payloads at their UTF-8 bytes / this (section
+#: 2): the fewest bytes per reasoning token measured, Anthropic signatures 6.3-7.2 and OpenAI Responses items about 17,
+#: so it errs high, up to about 2.9 times on the latter.
+PAYLOAD_BYTES_PER_TOKEN = 6
#: Each artifact list a checkpoint row keeps this many paths, most recently touched first, and marks whether earlier
#: ones were pushed out; what the model reads shows a 4,000th of the route's window of them, between
#: ``ARTIFACTS_SHOWN_MIN`` and this (section 7).
@@ -73,7 +77,15 @@ CLEAR_MIN_TOKENS = 20_000
CLEAR_KEEP_RESULTS = 5
CLEAR_PROTECTED_TURNS = 2
CLEARABLE_TOOLS = frozenset({"read", "bash"})
-CACHE_TTL_S = 300.0
+#: How long a route's provider prompt cache stays warm after its last use, in seconds, by cache family (section 3):
+#: the documented lifetime of the cache mode Vibey requests for the conversation, where clearable results live.
+#: ``anthropic``: the message breakpoints' ``cache_control`` is ephemeral with no ``ttl``, 5 minutes, refreshed on use.
+#: ``openai-gpt-5.6``: OpenAI models from GPT-5.6 keep a prefix 30 minutes after its last write or reuse, the default
+#: and only ``prompt_cache_options.ttl``; Vibey sends none.
+CACHE_TTLS: Mapping[str, float] = {"anthropic": 300.0, "openai-gpt-5.6": 1_800.0}
+#: Any other route, or one not identified unambiguously: clearing a warm cache costs a full-price re-read of the
+#: context, while leaving a cold one only keeps some old output, so an unknown lifetime counts as an hour.
+CACHE_TTL_UNKNOWN_S = 3_600.0
CLEARED_PLACEHOLDER = (
"[Old tool result cleared to save context. Re-run the tool or re-read the file if you need it again.]"
)
@@ -204,7 +216,6 @@ class ContextConfig:
#: This Session's scratch directory; checkpoint turns may write only there.
scratch_dir: Optional[str] = None
clear_tool_results: bool = True
- cache_ttl_s: float = CACHE_TTL_S
clock: Callable[[], float] = field(default=time.time, repr=False)
@@ -220,20 +231,43 @@ def _utf8(value: str) -> int:
def message_tokens(message: Message) -> int:
- """UTF-8 bytes / 4 of everything replayed, with a fixed cost per image."""
+ """``tokens()`` of a message as replayed (section 2): UTF-8 bytes / 4 of its text, its thinking text, and each tool
+ call's name and JSON arguments, 1,600 per image, and, when it carries an opaque reasoning payload, its reasoning
+ in place of the payload's size."""
size = 0
images = 0
+ signed = 0 # thinking text that rides with a payload: the reported reasoning covers it
+ payload: Optional[int] = None # UTF-8 bytes of its opaque payloads, None without any
for block in message.content:
if isinstance(block, TextBlock):
size += _utf8(block.text) if block.text is not None else block.ref.bytes
elif isinstance(block, ImageBlock):
images += 1
elif isinstance(block, ThinkingBlock):
- size += _utf8(block.text) + _utf8(block.signature or "")
+ if block.signature is None:
+ size += _utf8(block.text)
+ else:
+ signed += _utf8(block.text)
+ payload = (payload or 0) + _utf8(block.signature)
elif isinstance(block, ToolCallBlock):
arguments = json.dumps(block.arguments, ensure_ascii=False, separators=(",", ":"))
- size += _utf8(block.name) + _utf8(arguments) + _utf8(block.signature or "")
- return math.ceil(size / 4) + images * IMAGE_TOKENS
+ size += _utf8(block.name) + _utf8(arguments)
+ if block.signature is not None:
+ payload = (payload or 0) + _utf8(block.signature)
+ reasoning = 0 if payload is None else max(math.ceil(signed / 4), _reasoning(message, payload))
+ return math.ceil(size / 4) + images * IMAGE_TOKENS + reasoning
+
+
+def _reasoning(message: Message, payload: int) -> int:
+ """What a message's opaque reasoning payloads of ``payload`` bytes cost when replayed (section 2): the reasoning
+ tokens its usage reports, else its output tokens, which include them; without usage, the bytes over
+ ``PAYLOAD_BYTES_PER_TOKEN``. A failed or aborted partial's payloads cost nothing: it is never replayed."""
+ if not isinstance(message, AssistantMessage) or message.stop_reason in ("error", "aborted"):
+ return 0
+ usage = message.usage
+ if usage is None:
+ return math.ceil(payload / PAYLOAD_BYTES_PER_TOKEN)
+ return usage.output_tokens if usage.reasoning_tokens is None else usage.reasoning_tokens
def messages_tokens(messages: Sequence[Message]) -> int:
@@ -286,7 +320,7 @@ class Anchor:
#: What its request carried from the transcript, before the response.
transcript: tuple[Message, ...]
response: AssistantMessage
- #: UTF-8/4 of the whole request it answered, as sent (``ModelResponse.request.tokens``).
+ #: ``tokens()`` of the whole request it answered, as sent (``ModelResponse.request.tokens``).
request_tokens: int
@@ -300,7 +334,7 @@ def _valid_usage(message: Optional[Message]) -> bool:
def sent_tokens(request: ModelRequest) -> int:
- """UTF-8/4 of a whole request: system prompt, tool definitions, and messages."""
+ """``tokens()`` of a whole request (section 2): system prompt, tool definitions, and messages."""
return request_tokens(request.system, request.tools, request.messages)
@@ -335,23 +369,41 @@ def checkpoint_max_tokens(capabilities: ModelCapabilities, configured: int) -> i
def _estimate(request: ModelRequest, transcript: Sequence[Message], anchor: Optional[Anchor]) -> int:
- """The anchored usage while it holds, adjusted by the UTF-8/4 delta of everything else; else UTF-8/4.
-
- The anchor holds while the request goes to the route that answered it and the transcript up to its response
- is unchanged. A changed system prompt, tool set, or rehydrated state does not invalidate it: the request's
- own UTF-8/4 size carries the delta.
+ """The anchored usage while it holds, grown by the ``tokens()`` of what changed since; else ``tokens()`` of the
+ request (section 2).
+
+ The anchor holds while the request goes to the route that answered it and the transcript up to its response is
+ the one its request carried, but for the content of tool results, all that clearing and a cut to fit change. The
+ growth is the larger of the whole request's and the transcript's own: a stored request size adds a changed system
+ prompt, tool set, or rehydrated state, and never takes away more than the transcript accounts for. While a tool
+ result before the response differs, the estimate is at least ``tokens()`` of the request, since what the change
+ removed is a local estimate taken from a provider count.
"""
whole = sent_tokens(request)
- if anchor is not None and anchor.response.origin == endpoint_origin(request.endpoint):
- sent = len(anchor.transcript)
- if (
- len(transcript) > sent
- and transcript[sent] == anchor.response
- and tuple(transcript[:sent]) == anchor.transcript
- ):
- usage = usage_total(anchor.response.usage)
- return max(0, usage + whole - anchor.request_tokens - message_tokens(anchor.response))
- return whole
+ if anchor is None or anchor.response.origin != endpoint_origin(request.endpoint):
+ return whole
+ sent = len(anchor.transcript)
+ if len(transcript) <= sent or transcript[sent] != anchor.response:
+ return whole
+ edited = False
+ for now, then in zip(transcript, anchor.transcript):
+ if now == then:
+ continue
+ if not _same_result(now, then):
+ return whole
+ edited = True
+ growth = max(whole - anchor.request_tokens, messages_tokens(transcript) - messages_tokens(anchor.transcript))
+ est = usage_total(anchor.response.usage) - message_tokens(anchor.response) + growth
+ return max(est, whole) if edited else est
+
+
+def _same_result(now: Message, then: Message) -> bool:
+ """The same tool result but for its content: call id, tool name, and error flag unchanged (section 2)."""
+ return (
+ isinstance(now, ToolResultMessage)
+ and isinstance(then, ToolResultMessage)
+ and (now.tool_call_id, now.tool_name, now.is_error) == (then.tool_call_id, then.tool_name, then.is_error)
+ )
def fit_result(
@@ -424,7 +476,27 @@ def budget(
return Budget(window, limit, output, margin, threshold, keep, _estimate(request, transcript, anchor))
-# --- clearing (context.md section 4) ------------------------------------------------
+# --- clearing (context.md sections 3 and 4) -------------------------------------------
+
+#: An official OpenAI GPT model id, parsed whole: ``gpt-<major>[.<minor>]``, then an optional ``-<suffix>``.
+_GPT_MODEL = re.compile(r"gpt-(\d+)(?:\.(\d+))?(?:-[a-z0-9]+(?:[.-][a-z0-9]+)*)?", re.ASCII)
+
+
+def cache_ttl_s(endpoint: ModelEndpoint) -> float:
+ """How long the provider cache of a request's route stays warm (section 3): its family's documented lifetime in
+ ``CACHE_TTLS``, else ``CACHE_TTL_UNKNOWN_S``."""
+ family = _cache_family(endpoint)
+ return CACHE_TTL_UNKNOWN_S if family is None else CACHE_TTLS[family]
+
+
+def _cache_family(endpoint: ModelEndpoint) -> Optional[str]:
+ """The route's cache family from its provider, protocol, and whole model id; None unless unambiguous."""
+ if endpoint.provider == "anthropic" and endpoint.protocol == "anthropic":
+ return "anthropic"
+ gpt = _GPT_MODEL.fullmatch(endpoint.model_id) if endpoint.provider == "openai" else None
+ if gpt is not None and (int(gpt[1]), int(gpt[2] or 0)) >= (5, 6):
+ return "openai-gpt-5.6"
+ return None
def clearable_results(view: ContextView) -> tuple[ContextEntry, ...]:
diff --git a/docs/plans/agent-core-contracts/context.md b/docs/plans/agent-core-contracts/context.md
index ba92519ca..ce6424122 100644
--- a/docs/plans/agent-core-contracts/context.md
+++ b/docs/plans/agent-core-contracts/context.md
@@ -1,9 +1,11 @@
# C-9 Context management
-Frozen 2026-10-04 by owner decision. The `harness` owns the rules (`core/agent_core/harness/context.py`,
-`projection.py`); the loop applies them before every model request (`core/agent_core/agent/loop.py`); the adapter
-supplies the Session-specific parts (§9). Row shapes: [`transcript-rows.schema.json`](transcript-rows.schema.json);
-events: [`agent-event.schema.json`](agent-event.schema.json).
+Frozen 2026-10-04 by owner decision; amended 2026-10-12 by owner decision (the estimate of opaque reasoning payloads
+and the anchor's validity, §2; the cache lifetime per route, §3). The `harness` owns the rules
+(`core/agent_core/harness/context.py`, `projection.py`); the loop applies them before every model request
+(`core/agent_core/agent/loop.py`); the adapter supplies the Session-specific parts (§9). Row shapes:
+[`transcript-rows.schema.json`](transcript-rows.schema.json); events:
+[`agent-event.schema.json`](agent-event.schema.json).
Three tiers, cheapest first:
@@ -51,25 +53,47 @@ fit: at `est = T` it uses a few hundred tokens of `M` for the checkpoint request
## 2. Token estimate
`tokens(x) = ceil(utf8_bytes(x) / 4)`: characters / 4 undercounts Chinese by about 65%, UTF-8 bytes / 4 is within 6%.
-A message counts its text, its thinking text and signature (replayed reasoning payloads), each tool call's name,
-JSON arguments, and signature, and 1,600 tokens per image.
+A message counts its text, its thinking text, each tool call's name and JSON arguments, and 1,600 tokens per image.
+
+An opaque reasoning payload (a thinking or tool-call `signature`, redacted thinking: Anthropic's signed thinking, an
+OpenAI Responses reasoning item's `encrypted_content`, and the like) is never counted like text. It is
+ciphertext, about 17 UTF-8 bytes per reasoning token on OpenAI Responses, so bytes / 4 overstated a replayed item
+about 4.3 times. A message carrying one counts, once, the larger of its signed thinking text and its reasoning: the
+`reasoning_tokens` its usage reports, else its `output_tokens`, which include them; a response that reports no usage
+counts its payloads' UTF-8 bytes / 6, the fewest bytes per reasoning token measured (Anthropic signatures 6.3-7.2,
+OpenAI Responses items about 17), so it errs high. A failed or aborted partial's payloads count nothing: it is never
+replayed (C-1). Measured on recorded Sessions: OpenAI Responses bills a replayed reasoning item at about its
+`reasoning_tokens`; Anthropic bills replayed thinking at about its `reasoning_tokens` until a tool result before it
+is edited, and not after that, which the next response's usage shows. A payload sent to another origin is dropped
+(C-1); it still counts, until that route's first answer anchors.
The **anchor** is the latest response in the context that neither failed nor was aborted, reports non-zero usage,
and records the request it answered on its row (`ModelResponse.request.tokens`: `tokens()` of that whole request as
sent). It is rebuilt from the rows, so it holds across a new Agent and a new Turn.
```text
-est = usage(R) + tokens(this request) - R.request.tokens - tokens(R) while the anchor R holds
- = tokens(this request) otherwise
+est = usage(R) - tokens(R) + growth while the anchor R holds
+growth = max(tokens(this request) - R.request.tokens, tokens(transcript) - tokens(R's transcript))
+est = max(est, tokens(this request)) while a tool result before R differs (b)
+ = tokens(this request) otherwise
usage(R) = input_tokens + cache_read_tokens + cache_write_tokens + output_tokens
```
-The anchor holds while (a) this request goes to the route that answered it (`R.origin` equals the request
-endpoint's origin, because tokenizers differ), and (b) the transcript up to `R` is unchanged: the messages the rows
-put before `R` now are the ones they put before it when `R`'s request was built, and `R` follows them. A checkpoint,
-or an edit of a result before `R`, breaks (b). A changed system prompt, tool set, or rehydrated state
-does not invalidate the anchor: the difference between this request's `tokens()` and `R.request.tokens` carries it.
-So does anything after `R`, an edit there included.
+`transcript` is what the rows put in this request (rehydrated messages aside); `R's transcript` is what they put
+before `R` when its request was built. The anchor holds while (a) this request goes to the route that answered it
+(`R.origin` equals the request endpoint's origin, because tokenizers differ), and (b) the transcript up to `R` is the
+one `R`'s request carried, the content of tool results aside: the messages the rows put before `R` now are the ones
+they put there then, but a tool result's content may differ (its call id, tool name, and error flag the same), and
+`R` follows them. Clearing (§4) and a cut to fit (§3) change only that content, so the anchor survives them and the
+growth takes away what they removed by its `tokens()`; what they removed is a local estimate taken from a provider
+count, so while such a change stands the estimate is never below `tokens(this request)`. A checkpoint breaks (b), and
+so does any other change before `R`. A changed system prompt, tool set, or rehydrated state does not invalidate the
+anchor: the difference between this request's `tokens()` and `R.request.tokens` carries it, but only to add, since
+the growth is never less than the transcript's own. So a recorded size larger than what the transcript's growth
+explains (a row recorded under another estimate rule, such as one that counted payload ciphertext) cannot take the
+estimate below `usage(R)` and what follows `R`. No rule version is recorded, so such a size hides growth of the
+system prompt, tools, or rehydrated state up to its excess, until the next response anchors. Anything after `R`, an
+edit there included, counts by its `tokens()`.
## 3. Before every model request
@@ -89,8 +113,9 @@ before a retry alike:
to its own tool results (§6), one helper for both. The run continues and compacts as usual. A batch that does not
fit even with every result cut to its note, or a last unit that is an input, stops the run: the provider never
sees the request. A batch that fits once the conversation moves out is never cut; the ladder makes room for it.
-2. **Clear** (§4) when the provider cache is cold (no model request for longer than the cache TTL, 300 s by
- default; after a restart, measured from the latest response row's `created_at`) or `est >= 0.8 * T`.
+2. **Clear** (§4) when the provider cache is cold (the request's route has not used it for longer than its
+ lifetime, below; after a restart, measured from the response rows' `created_at`) or `est >= 0.8 * T`, which does
+ not depend on the lifetime.
3. **Checkpoint** when `est >= T`, the run has not stopped compacting (§10), and there is something to summarize,
at most once per model request: a normal checkpoint (§6, reason `threshold`) when the fork it would send can fit,
otherwise the overflow ladder from (b) (§8, reason `overflow`). A checkpoint request that overflows continues at
@@ -100,6 +125,24 @@ before a retry alike:
provider judges. Once the run has stopped compacting nothing is compacted at all: a request that cannot fit, or
that the provider refuses as overflow, ends the run `context_exhausted` (§10).
+The cache lifetime is the documented lifetime of the cache mode Vibey requests for the conversation, where clearable
+results live, resolved on every request from the route's provider, protocol, and whole model id
+(`harness/context.py`, `CACHE_TTLS`):
+
+| Route | Lifetime |
+| --- | --- |
+| provider `anthropic` on the Anthropic protocol: the message breakpoints' `cache_control` is ephemeral, with no `ttl` | 300 s, refreshed on use |
+| provider `openai`, a model id `gpt-<major>[.<minor>][-<suffix>]` from GPT-5.6: `prompt_cache_options.ttl` is 30 minutes, its default and only value, and Vibey sends none | 1,800 s |
+| any other route, or one not identified unambiguously (older OpenAI models, other vendors on either protocol, relays) | 3,600 s |
+
+Clearing a warm cache forces a full-price re-read of the context, while skipping a clear on a cold one only keeps
+some old output, so an unknown lifetime counts as an hour, and relays and subscription sources that keep a shorter
+one err toward warm. The idle time is the route's own cache's: it runs from the later of the latest model call's end
+and the latest response's commit served by the same provider and model as the request's route (the protocol that
+reaches the gateway, converted or not, does not change the cache), which overstates warmth by a response's duration,
+the same safe direction; another route's use never refreshes it. A route with no use in the Session yet takes the
+latest use of any route.
+
A request the provider rejects as overflow (`ProviderError.kind == "overflow"`, classified by
`ai/errors.is_overflow_message`, HTTP 413, and `context_length_exceeded`) before anything was streamed, and with no
content in its partial, enters the overflow ladder (§8) and is rebuilt and sent again. Any other overflow is never
@@ -119,7 +162,7 @@ each is sent only when it can fit.
`{"target_event_id": <tool_result row id>, "replacement": {"text": PLACEHOLDER}, "reason": "clear_old_tool_result"}`.
- `PLACEHOLDER` = `[Old tool result cleared to save context. Re-run the tool or re-read the file if you need it again.]`
- Projection keeps the call id, name, and error flag, and replaces the content with the placeholder. The latest
- edit of a target wins.
+ edit of a target wins. The estimate's anchor survives it (§2).
## 5. Cut point
@@ -357,6 +400,8 @@ The loop takes a `ContextConfig` (`harness/context.py`); without one, no context
ends the run `context_exhausted`, as in P1. The adapter supplies the following; Vibey's are in
`modules/agents/vibey` (`agent.py`, `context.py`, `store.py`), and every Turn of it runs with a `ContextConfig`.
+- The route's identity: its endpoint's `provider`, `protocol`, and `model_id` (the hop's `provider` and
+ `runtime_model`), from which the loop resolves the cache lifetime on every request (§3); nothing configures it.
- The limits (§1): the route's capabilities come from the Model Hub model definition the user edits
(`context_window`, `max_output_tokens`; `input_limit` stays unknown until Model Hub stores one, so `L_in = W`), and
the Agent asks for `min(max_output_tokens, floor(W / 4))` (the maximum 8,192 when unknown) on every hop it resolves,
@@ -451,7 +496,9 @@ every-exit audit: `test_loop.py`) that fails when its order or owner is broken.
exit but an abort, whichever step ends it (compose, provider, admission, the host's state or hint, building the
row, commit). A failed request or a host failure after the model answered is a failed checkpoint, counted by the
run's bound; an engine error building the row, or a failed commit, ends the run with nothing landed (invariant 3).
-5. **Route-scoped anchors.** An anchor answered by another origin (provider, api, model) is invalid (§2).
+5. **Route- and transcript-scoped anchors.** An anchor answered by another origin (provider, api, model) is invalid,
+ and so is one whose transcript a checkpoint, or any change but a tool result's content, altered; while a tool
+ result before it differs, the estimate is at least the request's own `tokens()` (§2).
6. **One admission path.** Every response, of every purpose (conversation, checkpoint), and every partial with
content is admitted in one place, the model call, before anything acts on it: it must be valid after the
committed rows and, in a checkpoint turn, the turn's own request and messages (projection's rules: canonical
diff --git a/docs/plans/agent-core-contracts/transcript-rows.schema.json b/docs/plans/agent-core-contracts/transcript-rows.schema.json
index 080432318..a3091b784 100644
--- a/docs/plans/agent-core-contracts/transcript-rows.schema.json
+++ b/docs/plans/agent-core-contracts/transcript-rows.schema.json
@@ -49,7 +49,7 @@
"tokens": {
"type": "integer",
"minimum": 0,
- "description": "UTF-8/4 tokens of the whole request: system prompt, tool definitions, and messages."
+ "description": "tokens() of the whole request (context.md section 2): system prompt, tool definitions, and messages at UTF-8 bytes / 4, 1,600 per image, and each opaque reasoning payload at its response's reported reasoning, never as text."
}
}
}
diff --git a/docs/plans/avibe-agent-core.md b/docs/plans/avibe-agent-core.md
index 39ca416ab..62ccf663d 100644
--- a/docs/plans/avibe-agent-core.md
+++ b/docs/plans/avibe-agent-core.md
@@ -188,10 +188,11 @@ and `bash` results with `context_edit` rows, on by default; and a checkpoint wri
function derives the rest and `est` from the final request, immediately before it is sent.
`M = min(max(8,000, 3% W), W / 8)`, `T = min(L_in - O - M, 0.9 W)`.
- **Trigger** before every model request, including inside the tool loop, on the final request (in v1 no user hook
- runs with context management): `est` is the usage of the latest response stored with its request facts, adjusted by the UTF-8 bytes / 4
- difference between this request and that one (1,600 per image), while that request went to the same route and the
- transcript up to the response is unchanged; otherwise UTF-8 bytes / 4 of the whole request. Compact when
- `est >= T`.
+ runs with context management): `est` is the usage of the latest response stored with its request facts, adjusted by the
+ estimate's difference between this request and that one, while that request went to the same route and the
+ transcript up to the response is unchanged but for tool-result content (then never below the request's own
+ estimate); otherwise the estimate of the whole request: UTF-8 bytes / 4, 1,600 per image, and an opaque reasoning
+ payload at its response's reported reasoning, never as text. Compact when `est >= T`.
- **Cut** before a user message or before an assistant message whose tool batch follows it, keeping
`min(20K, 0.25 T)` verbatim; a cut inside the in-flight Turn keeps its inputs (the first and each steer) as they
were, images included. A tool batch that cannot fit even with the conversation moved out is cut to fit, each
diff --git a/tests/agent_core/agent/test_compaction.py b/tests/agent_core/agent/test_compaction.py
index 7f0a13710..75275c777 100644
--- a/tests/agent_core/agent/test_compaction.py
+++ b/tests/agent_core/agent/test_compaction.py
@@ -53,6 +53,7 @@ from core.agent_core.harness.context import (
from core.agent_core.harness.projection import context_view, project
from core.agent_core.messages import (
AssistantMessage,
+ Origin,
TextBlock,
ThinkingBlock,
ToolCallBlock,
@@ -1266,19 +1267,29 @@ async def test_one_compaction_is_in_flight_per_session():
assert len(model.checkpoint_requests) == 1
-async def test_clearing_runs_when_the_cache_is_cold_and_spares_recent_turns():
+#: An official OpenAI GPT model (a 30-minute prompt cache, section 3) and Anthropic, whose message breakpoints Vibey
+#: caches for 5 minutes; ``ENDPOINT``'s test provider is a route of unknown lifetime, an hour.
+GPT = ModelEndpoint("openai_responses", "http://model.invalid", "gpt-6-astra", "", provider="openai")
+CLAUDE = ModelEndpoint("anthropic", "http://model.invalid", "claude-opus-5-5", "", provider="anthropic")
+
+
[email protected]("endpoint,lifetime", [(CLAUDE, 300), (GPT, 1_800), (ENDPOINT, 3_600)])
+async def test_clearing_runs_once_the_route_cache_has_gone_cold_and_spares_recent_turns(endpoint, lifetime):
now = [1_000.0]
store = InMemoryTranscriptStore(clock=lambda: now[0])
context = ContextConfig(clock=lambda: now[0])
- script = [*_long_context(9), [Done(assistant("one"))], [Done(assistant("two"))], [Done(assistant("three"))]]
+ script = [*_long_context(9), *([Done(assistant(word))] for word in ("one", "two", "three", "four"))]
model = Model(script)
- agent = make_agent(model, store=store, tools=[reader(tokens(6_000))], selection=LARGE, context=context)
+ route = ModelSelection(endpoint, LARGE.capabilities)
+ agent = make_agent(model, store=store, tools=[reader(tokens(6_000))], selection=route, context=context)
await run(agent, row="turn-1")
await run(agent, row="turn-2")
+ now[0] += lifetime # idle exactly as long as the route's cache lives: still warm
+ await run(agent, row="turn-3")
assert not [row for row in await store.load("session") if row.kind == "context_edit"] # warm, below 0.8 T
results = deepcopy([row for row in await store.load("session") if row.kind == "tool_result"])
- now[0] += 301 # idle past the cache TTL
- await run(agent, row="turn-3")
+ now[0] += lifetime + 1 # idle past it
+ await run(agent, row="turn-4")
rows = await store.load("session")
edits = [row for row in rows if row.kind == "context_edit"]
by_id = {row.row_id: row.message.tool_call_id for row in results}
@@ -1291,6 +1302,119 @@ async def test_clearing_runs_when_the_cache_is_cold_and_spares_recent_turns():
assert store.transactions == [["context_edit"] * 4] # one transition, one transaction
+#: A Model Hub Google hop as the adapter calls it: over Chat at the gateway, while the served-hop report names the
+#: Google protocol the gateway converted to (C-6). Its cache lifetime is unknown: an hour.
+GEMINI = ModelEndpoint("openai_chat", "http://model.invalid", "gemini-3-pro", "", provider="google")
+GEMINI_SERVED = Origin("google", "google", "gemini-3-pro")
+
+
+async def routed_turn(store, now, endpoint, scripts, row, served=None):
+ """One Turn in a new Agent over ``store`` on ``endpoint``, its replies served as ``served`` (the endpoint's own
+ origin by default); the ``context_edit`` rows after it."""
+ origin = served or endpoint_origin(endpoint)
+ model = Model([[replace(event, message=replace(event.message, origin=origin)) for event in s] for s in scripts])
+ route = ModelSelection(endpoint, LARGE.capabilities)
+ context = ContextConfig(clock=lambda: now[0])
+ agent = make_agent(model, store=store, tools=[reader(tokens(6_000))], selection=route, context=context)
+ assert (await run(agent, row=row))[-1].reason == "completed"
+ return [row for row in await store.load("session") if row.kind == "context_edit"]
+
+
+async def test_a_route_cache_counts_only_its_own_use():
+ # Ten minutes after Claude's last reply, GPT answers for the first time: a route with no use yet takes the latest
+ # use of any route, well inside GPT's 30 minutes, so nothing clears. A minute later the Session is back on Claude,
+ # whose own cache went unused for eleven minutes: cold, although another route answered a minute ago.
+ now = [1_000.0]
+ store = InMemoryTranscriptStore(clock=lambda: now[0])
+ await routed_turn(store, now, CLAUDE, [*_long_context(9), [Done(assistant("one"))]], "turn-1")
+ await routed_turn(store, now, CLAUDE, [[Done(assistant("two"))]], "turn-2")
+ now[0] += 600
+ assert not await routed_turn(store, now, GPT, [[Done(assistant("three"))]], "turn-3")
+ now[0] += 60
+ assert len(await routed_turn(store, now, CLAUDE, [[Done(assistant("four"))]], "turn-4")) == 4
+
+
+async def test_a_converted_route_cache_is_its_upstream_provider_and_model():
+ # A Google hop's replies are served as the Google protocol though the request went over Chat: its cache is still
+ # its own. Fifty minutes after its last reply it is warm (an hour, unknown lifetime); after another route answers,
+ # it goes cold once its own reply is over an hour old, although that route answered under twelve minutes ago.
+ now = [1_000.0]
+ store = InMemoryTranscriptStore(clock=lambda: now[0])
+ await routed_turn(store, now, GEMINI, [*_long_context(9), [Done(assistant("one"))]], "turn-1", GEMINI_SERVED)
+ await routed_turn(store, now, GEMINI, [[Done(assistant("two"))]], "turn-2", GEMINI_SERVED)
+ now[0] += 3_000
+ assert not await routed_turn(store, now, GEMINI, [[Done(assistant("three"))]], "turn-3", GEMINI_SERVED)
+ now[0] += 3_000
+ assert not await routed_turn(store, now, ENDPOINT, [[Done(assistant("four"))]], "turn-4")
+ now[0] += 700
+ assert len(await routed_turn(store, now, GEMINI, [[Done(assistant("five"))]], "turn-5", GEMINI_SERVED)) == 4
+
+
+async def test_pressure_clearing_runs_on_a_warm_cache():
+ # From 0.8 T old results clear whatever the cache's lifetime (section 3): on this window T = 59,904, and nine
+ # results of 6,000 tokens hold 0.9 T. The third Turn is the first whose old results are not protected.
+ route = ModelSelection(ENDPOINT, replace(SELECTION.capabilities, context_window=72_000, input_limit=None))
+ script = [*_long_context(9), *([Done(assistant(word))] for word in ("one", "two", "three"))]
+ model = Model(script, [[Done(assistant(CHECKPOINT))]])
+ agent = make_agent(model, tools=[reader(tokens(6_000))], selection=route)
+ for turn in ("turn-1", "turn-2", "turn-3"):
+ assert (await run(agent, row=turn))[-1].reason == "completed"
+ edits = [row for row in await agent.store.load("session") if row.kind == "context_edit"]
+ assert [row.payload["reason"] for row in edits] == ["clear_old_tool_result"] * 4
+ assert not model.checkpoint_requests
+
+
+def responses_reply(*calls: ToolCallBlock, reasoning: int, value: str = ""):
+ """A script answering on ``GPT`` with a Responses reasoning item of 17 bytes of ciphertext per reasoning token, billed
+ as the OpenAI route was measured to bill: the request's bytes / 4 without the ciphertext, plus the reported
+ reasoning of every item it replays."""
+
+ def script(request):
+ visible, replayed = 0, 0
+ for message in request.messages:
+ for block in message.content:
+ if isinstance(block, (TextBlock, ThinkingBlock)):
+ visible += len(block.text.encode())
+ elif isinstance(block, ToolCallBlock):
+ visible += len(block.name.encode()) + len(json.dumps(block.arguments, separators=(",", ":")))
+ if isinstance(message, AssistantMessage) and any(
+ isinstance(block, ThinkingBlock) and block.signature for block in message.content
+ ):
+ replayed += message.usage.reasoning_tokens
+ billed = request_tokens(request.system, request.tools, ()) + -(-visible // 4) + replayed
+ item = {"type": "reasoning", "id": "rs_0", "encrypted_content": "A" * (17 * reasoning), "summary": []}
+ content = (ThinkingBlock("", signature=json.dumps(item)), *((text(value),) if value else ()), *calls)
+ usage = Usage(input_tokens=billed, output_tokens=reasoning + 20, reasoning_tokens=reasoning)
+ return [Done(AssistantMessage(content, endpoint_origin(GPT), "tool_use" if calls else "stop", usage=usage))]
+
+ return script
+
+
[email protected]("idle_s,cleared", [(1_302, 0), (1_860, 4)])
+async def test_a_return_to_a_long_reasoning_session_never_checkpoints_at_57_percent(idle_s, cleared):
+ # The incident: a gpt-6-astra Session about 57% of T into its window (here 102,000 of T = 180,000), its 36,400
+ # reasoning tokens replayed as 155,000 tokens of ciphertext by UTF-8 / 4. After 21.7 minutes away its 30-minute
+ # cache is still warm and nothing clears; after 31 minutes four old results clear, the anchor still holds, and
+ # the estimate falls by what they held. Neither checkpoints.
+ now = [1_000.0]
+ store = InMemoryTranscriptStore(clock=lambda: now[0])
+ reads = [responses_reply(ToolCallBlock(f"r{index}", "read", {"path": "f"}), reasoning=4_000) for index in range(9)]
+ script = [*reads, *(responses_reply(value=word, reasoning=200) for word in ("noted", "two", "three"))]
+ model = Model(script, [[Done(assistant(CHECKPOINT))]])
+ route = ModelSelection(GPT, LARGE.capabilities)
+ context = ContextConfig(clock=lambda: now[0])
+ agent = make_agent(model, store=store, tools=[reader(tokens(7_300))], selection=route, context=context)
+ await run(agent, row="turn-1")
+ await run(agent, row="turn-2")
+ billed = [row.message.usage.input_tokens for row in await store.load("session") if row.kind == "response"]
+ assert 0.55 * 180_000 < billed[-1] < 0.6 * 180_000
+ now[0] += idle_s
+ events = await run(agent, row="turn-3")
+ assert events[-1].reason == "completed" and not model.checkpoint_requests
+ edits = [row for row in await store.load("session") if row.kind == "context_edit"]
+ assert len(edits) == cleared and len(model.conversation_requests) == 12
+
+
async def test_chinese_output_reaches_the_threshold_by_its_utf8_size():
chinese = "压缩" * 3_000 # 6,000 characters, 18,000 bytes: 4,500 tokens, where characters / 4 says 1,500
model = Model(growing(5), [[Done(assistant(CHECKPOINT))]])
diff --git a/tests/agent_core/agent/test_context.py b/tests/agent_core/agent/test_context.py
index 0ceb4e5a7..c111f2bcb 100644
--- a/tests/agent_core/agent/test_context.py
+++ b/tests/agent_core/agent/test_context.py
@@ -7,6 +7,8 @@ the checkpoint's model-facing text and row.
from __future__ import annotations
+import base64
+import json
import math
import os
import random
@@ -22,6 +24,7 @@ from core.agent_core.harness.context import (
CLEARED_PLACEHOLDER,
ITEM_BYTES,
budget,
+ cache_ttl_s,
carried_skills,
CHECKPOINT_REPAIR,
checkpoint_block,
@@ -108,12 +111,75 @@ def test_the_estimate_counts_utf8_bytes_so_chinese_is_not_undercounted():
assert message_tokens(user(chinese)) == 54
image = UserMessage((TextBlock(text="see"), ImageBlock("image/png", "media-token")))
assert message_tokens(image) == 1 + 1_600
- call = ToolCallBlock("id", "read", {"path": "中"}, signature="sig")
- reply = AssistantMessage((ThinkingBlock("ab", signature="cdef"), call), ORIGIN, "tool_use")
- replayed = len("ab") + len("cdef") + len("read") + len('{"path":"中"}'.encode()) + len("sig")
+ call = ToolCallBlock("id", "read", {"path": "中"})
+ reply = AssistantMessage((ThinkingBlock("ab"), call), ORIGIN, "tool_use") # unsigned thinking replays as text
+ replayed = len("ab") + len("read") + len('{"path":"中"}'.encode())
assert message_tokens(reply) == math.ceil(replayed / 4)
+def responses_item(reasoning: int, summary: str = "") -> ThinkingBlock:
+ """An OpenAI Responses reasoning item as the adapter stores it: about 17 bytes of ciphertext per reasoning token."""
+ ciphertext = base64.b64encode(bytes(range(256)) * (reasoning // 15 + 1)).decode()[: 17 * reasoning]
+ summaries = [{"type": "summary_text", "text": summary}] if summary else []
+ item = {"type": "reasoning", "id": "rs_0", "encrypted_content": ciphertext, "summary": summaries}
+ return ThinkingBlock(summary, signature=json.dumps(item, separators=(",", ":")))
+
+
+#: Anthropic signed thinking as Claude Opus returns it with its text omitted: an empty text and a ~5 KB signature.
+ANTHROPIC_THINKING = ThinkingBlock("", signature=base64.b64encode(bytes(range(256)) * 15).decode())
+READ = ToolCallBlock("c", "read", {"path": "a"}) # "read" and '{"path":"a"}': 16 bytes, 4 tokens
+
+
+def _reply(*content, reasoning=None, output=0, usage=True) -> AssistantMessage:
+ reported = Usage(input_tokens=1, output_tokens=output, reasoning_tokens=reasoning) if usage else None
+ return AssistantMessage(tuple(content), ORIGIN, "tool_use", usage=reported)
+
+
+ "reply,tokens",
+ [
+ # OpenAI Responses: the summary text rides inside the item, and the reported reasoning covers it.
+ (_reply(responses_item(400, summary="plan"), READ, reasoning=400, output=450), 4 + 400),
+ # Two reasoning items in one response: the response's reasoning, once.
+ (_reply(responses_item(300), responses_item(100), READ, reasoning=400, output=450), 4 + 400),
+ (_reply(ANTHROPIC_THINKING, READ, reasoning=900, output=960), 4 + 900),
+ (_reply(ThinkingBlock("", signature="opaque-redacted" * 100, redacted=True), READ, reasoning=300), 4 + 300),
+ (_reply(replace(READ, signature="thought-signature" * 100), reasoning=200, output=230), 4 + 200), # Gemini
+ # A Chat marker signature: the text is the reasoning, replayed in its own field; never counted twice.
+ (_reply(ThinkingBlock("t" * 2_000, signature="reasoning_content"), READ, reasoning=480), 4 + 500),
+ # Without a reported reasoning count, the response's output, which includes it.
+ (_reply(ANTHROPIC_THINKING, READ, output=700), 4 + 700),
+ # Thinking with no payload replays as plain text.
+ (_reply(ThinkingBlock("t" * 400), READ, reasoning=900), 4 + 100),
+ ],
+)
+def test_an_opaque_reasoning_payload_counts_its_reported_reasoning_never_its_ciphertext(reply, tokens):
+ assert message_tokens(reply) == tokens
+ # The ciphertext's size never matters: ten times the payload is the same estimate.
+ bigger = tuple(
+ replace(block, signature=block.signature * 10)
+ if isinstance(block, (ThinkingBlock, ToolCallBlock)) and block.signature not in (None, "reasoning_content")
+ else block
+ for block in reply.content
+ )
+ assert message_tokens(replace(reply, content=bigger)) == tokens
+
+
+def test_without_usage_a_payload_counts_its_bytes_over_six_and_a_failed_partial_none():
+ # A replayed response that reports no usage: its payloads at UTF-8 bytes / 6, the fewest bytes per reasoning token
+ # measured, so the estimate errs high (an OpenAI Responses item of 4,000 reasoning tokens counts about 11,300).
+ item = responses_item(4_000)
+ for thinking in (item, ANTHROPIC_THINKING):
+ assert message_tokens(_reply(thinking, READ, usage=False)) == 4 + math.ceil(len(thinking.signature) / 6)
+ signed_call = replace(READ, signature="thought-signature" * 100)
+ assert message_tokens(_reply(item, signed_call, usage=False)) == 4 + math.ceil((len(item.signature) + 1_700) / 6)
+ # A failed or aborted partial is never replayed: its payloads cost nothing, whether it reports usage or not.
+ for stop in ("error", "aborted"):
+ for usage in (True, False):
+ partial = replace(_reply(item, READ, reasoning=4_000, output=4_100, usage=usage), stop_reason=stop)
+ assert message_tokens(partial) == 4
+
+
def make_request(messages=(), *, system="system", tools=(), endpoint=ENDPOINT, max_tokens=4_096) -> ModelRequest:
return ModelRequest(endpoint, system, tuple(messages), tuple(tools), max_tokens)
@@ -159,8 +225,9 @@ def _usage(total: int) -> Usage:
CAPABILITIES = ModelCapabilities(context_window=32_000, max_output_tokens=4_096)
-def _anchored_rows():
- """A read, then a response R billed 5,000 whose row records its request, R's result, and a later reply."""
+def _anchored_rows(billed: int = 5_000):
+ """A read, then a response R billed ``billed`` whose row records its request (1,106 tokens), R's result, and a
+ later reply."""
rows = Rows()
rows.input("x" * 400)
rows.tool("read", "w" * 4_000, call_id="before", path="a")
@@ -168,7 +235,7 @@ def _anchored_rows():
sent = make_request(context_view(rows.rows).messages)
anchored = rows.add(
"response",
- AssistantMessage((read,), ORIGIN, "tool_use", usage=_usage(5_000)),
+ AssistantMessage((read,), ORIGIN, "tool_use", usage=_usage(billed)),
payload={"request": request_facts(sent)},
)
result = rows.result(read, "y" * 4_000)
@@ -182,6 +249,12 @@ def _est(rows, request=None):
return budget(request, CAPABILITIES, transcript=view.messages, anchor=last_anchor(rows.rows, view)).est
+def _whole(rows, request=None):
+ """``tokens()`` of the whole request, the estimate without an anchor."""
+ request = request or make_request(context_view(rows.rows).messages)
+ return request_tokens(request.system, request.tools, request.messages)
+
+
def _edit_of(entry):
return {
"version": 1,
@@ -196,7 +269,7 @@ def test_the_anchor_holds_while_the_transcript_up_to_its_response_is_unchanged()
messages = context_view(rows.rows).messages
after = message_tokens(result.message) + message_tokens(messages[-1])
assert _est(rows) == 5_000 + after
- # Outside the transcript, a change adjusts the anchored usage by its UTF-8/4 delta.
+ # Outside the transcript, a change adjusts the anchored usage by its tokens() delta.
longer = "system " * 100
delta = request_tokens(longer, (), ()) - request_tokens("system", (), ())
assert _est(rows, make_request(messages, system=longer)) == 5_000 + after + delta
@@ -211,19 +284,72 @@ def test_the_anchor_holds_while_the_transcript_up_to_its_response_is_unchanged()
assert _est(rows) == 5_000 + message_tokens(cleared[-2]) + message_tokens(cleared[-1])
-def test_an_edit_or_checkpoint_before_the_anchor_or_another_route_invalidates_it():
- def whole(rows, request=None):
- request = request or make_request(context_view(rows.rows).messages)
- return request_tokens(request.system, request.tools, request.messages)
-
+def test_the_anchor_survives_clearing_a_result_before_it_but_never_drops_below_the_request():
+ # The provider counted far more than the bytes (5,000 for 1,106): clearing the result before R (1,000 tokens) is
+ # a negative delta of its tokens() on the anchored usage, which still says more than the bytes.
+ rows, anchored, result = _anchored_rows()
+ messages = context_view(rows.rows).messages
+ after = message_tokens(result.message) + message_tokens(messages[-1])
+ freed = 1_000 - text_tokens(CLEARED_PLACEHOLDER)
+ rows.add("context_edit", payload=_edit_of(next(row for row in rows.rows if row.kind == "tool_result")))
+ assert _est(rows) == 5_000 + after - freed > _whole(rows)
+ # It counted less (a tokenizer that packs the text tighter than 4 bytes a token): the unchanged anchor lowers the
+ # estimate below the bytes. What a clearing removes is a local estimate taken from that provider count, so once
+ # a result before R is cleared the estimate is never below the request's own tokens().
+ rows, anchored, result = _anchored_rows(billed=600)
+ assert _est(rows) == 600 + after < _whole(rows)
+ rows.add("context_edit", payload=_edit_of(next(row for row in rows.rows if row.kind == "tool_result")))
+ assert 600 + after - freed < _est(rows) == _whole(rows)
+
+
+def test_a_stored_request_size_the_transcript_cannot_explain_hides_at_most_its_excess():
+ # A row recorded under another estimate rule (here the earlier one, each reasoning item at its ciphertext's UTF-8
+ # / 4, about four times its reasoning) stores a request size larger than this rule gives what that request
+ # carried, here by about 26,000. Taken as is, the anchored usage would lose more than R and everything after it
+ # are worth; the anchor never takes away more than the transcript accounts for, so the estimate stays at usage(R)
+ # and what follows R. No rule version is recorded: growth outside the transcript hides behind that excess, at
+ # most all of it, until the next response anchors (known by design, section 2).
+ item = responses_item(8_000)
+ call = ToolCallBlock("s", "read", {"path": "a"})
+ reported = Usage(input_tokens=1_000, output_tokens=8_010, reasoning_tokens=8_000)
+ earlier_reply = AssistantMessage((item, call), ORIGIN, "tool_use", usage=reported)
+
+ def rows_storing(stored):
+ rows = Rows()
+ rows.input("x" * 400)
+ rows.add("response", earlier_reply)
+ rows.result(call, "w" * 4_000)
+ read = ToolCallBlock("r", "read", {"path": "f"})
+ current = request_facts(make_request(context_view(rows.rows).messages))["tokens"]
+ tokens = stored(current)
+ anchored = AssistantMessage((read,), ORIGIN, "tool_use", usage=_usage(12_000))
+ rows.add("response", anchored, payload={"request": {"tokens": tokens}})
+ result = rows.result(read, "y" * 4_000)
+ rows.response(value="z" * 40)
+ return rows, current, tokens, message_tokens(result.message) + 10
+
+ def grown(rows, tokens):
+ """This request with a system prompt ``tokens`` larger."""
+ return make_request(context_view(rows.rows).messages, system="system" + "s" * (4 * tokens))
+
+ # A row this rule recorded: the stored size carries the system prompt's growth.
+ rows, current, _, after = rows_storing(lambda current: current)
+ assert _est(rows) == 12_000 + after
+ assert _est(rows, grown(rows, 20_000)) == 12_000 + after + 20_000
+ ciphertext = math.ceil((len(item.signature.encode()) + len('read{"path":"a"}')) / 4)
+ rows, current, earlier, after = rows_storing(lambda current: current - (4 + 8_000) + ciphertext)
+ excess = earlier - current
+ assert excess > 12_000 + after # usage + tokens(this) - R.request.tokens - tokens(R) would be negative
+ assert _est(rows) == 12_000 + after > _whole(rows)
+ assert _est(rows, grown(rows, 20_000)) == 12_000 + after # under the excess: hidden
+ assert _est(rows, grown(rows, 40_000)) == 12_000 + after + 40_000 - excess # over it: all but the excess
+
+
+def test_a_checkpoint_or_another_route_invalidates_the_anchor():
rows, anchored, result = _anchored_rows()
other_route = ModelEndpoint("anthropic", "http://model.invalid", "other-model", "", provider="test-provider")
request = make_request(context_view(rows.rows).messages, endpoint=other_route)
- assert _est(rows, request) == whole(rows, request) # another model's tokenizer
- # A context_edit of a result before the anchored response changes what its usage measured.
- before = next(row for row in rows.rows if row.kind == "tool_result")
- rows.add("context_edit", payload=_edit_of(before))
- assert _est(rows) == whole(rows)
+ assert _est(rows, request) == _whole(rows, request) # another model's tokenizer
# A checkpoint that keeps the anchored response verbatim still replaces what came before it.
rows, anchored, result = _anchored_rows()
view = context_view(rows.rows)
@@ -234,7 +360,7 @@ def test_an_edit_or_checkpoint_before_the_anchor_or_another_route_invalidates_it
)
rows.add("compaction", payload=payload)
assert context_view(rows.rows).units[0].seq == anchored.context_seq
- assert _est(rows) == whole(rows)
+ assert _est(rows) == _whole(rows)
# A failed or aborted response, or one without usage or request facts, never anchors.
for message, facts in [
(AssistantMessage((), ORIGIN, "error", usage=_usage(9_999)), True),
@@ -248,6 +374,27 @@ def test_an_edit_or_checkpoint_before_the_anchor_or_another_route_invalidates_it
assert last_anchor(only.rows, context_view(only.rows)) is None
+ "protocol,provider,model,lifetime",
+ [
+ ("anthropic", "anthropic", "claude-opus-5-5", 300), # message breakpoints: ephemeral, no ttl
+ ("openai_responses", "openai", "gpt-6-astra", 1_800),
+ ("openai_responses", "openai", "gpt-6.1-sol", 1_800),
+ ("openai_chat", "openai", "gpt-5.6-mini", 1_800),
+ ("openai_responses", "openai", "gpt-5.5", 3_600), # before GPT-5.6: in-memory, 5 minutes to an hour
+ ("openai_responses", "openai", "gpt-4o", 3_600),
+ ("openai_responses", "openai", "o3", 3_600),
+ ("openai_responses", "openai", "my-gpt-6-astra", 3_600), # parsed whole, never searched for
+ ("openai_chat", "openrouter", "openai/gpt-6-astra", 3_600), # a relay
+ ("openai_responses", "xai", "grok/grok-4.6", 3_600),
+ ("anthropic", "moonshot", "kimi-k2", 3_600), # another vendor on the Anthropic protocol
+ ("anthropic", "test-provider", "test-model", 3_600),
+ ],
+)
+def test_a_route_cache_lives_as_long_as_its_family_documents_else_an_hour(protocol, provider, model, lifetime):
+ assert cache_ttl_s(ModelEndpoint(protocol, "http://model.invalid", model, "", provider=provider)) == lifetime
+
+
def _random_rows(seed: int) -> list[ContextEntry]:
rng = random.Random(seed)
rows = Rows()
diff --git a/tests/test_transcript_store_contract.py b/tests/test_transcript_store_contract.py
index 519695261..aa8e5daf2 100644
--- a/tests/test_transcript_store_contract.py
+++ b/tests/test_transcript_store_contract.py
@@ -351,7 +351,7 @@ async def test_a_new_agent_clears_old_results_once_the_cache_has_gone_cold(c9):
await run(agent, row=c9.stored_input(SESSION))
await run(agent, row=c9.stored_input(SESSION))
assert not [row for row in await c9.store.load(SESSION) if row.kind == "context_edit"] # warm, below 0.8 T
- idle[0] = 301 # past the cache TTL; the restarted Agent knows only the stored commit times
+ idle[0] = 3_601 # past the hour a route of unknown cache lifetime gets; the restarted Agent knows only commit times
model = Model([[Done(assistant("three"))]])
restarted = make_agent(model, store=c9.store, tools=[reader(tokens(6_000))], selection=LARGE, context=context)
await run(restarted, row=c9.stored_input(SESSION))