Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Framework-independent recall, immutable replay, compaction and capture orchestration."""
import asyncio
import logging
import time
import uuid
from dataclasses import dataclass, field, replace
import orjson
from .blocks import RECALL_PROVENANCE_NOTE, block, gateway_note, history_hint, token_estimate
from .capture import CapturePipeline, lineage
from .capture_store import Document
from .client import VikingError
from .compaction import (
BACKOFF_SECONDS,
active_cut,
apply_cut,
cut_hint,
cut_point,
estimate,
opening_block,
replacement_text,
summary_instruction,
window_size,
)
from .models import Policy
from .notices import recall_notice
from .profile import build_profile
from .protocols import (
classify,
clean_text,
client_openviking_tools,
is_user,
plugin_present,
prefix_chain,
replays_reasoning,
session_id,
strip_thinking,
text_content,
unwrap_client,
)
from .records import RecordKind as K
from .state_store import get_state
from .storage import KernelStore, digest
from .tool_catalog import reply_block_reason, select_tools, tool_block_reason
from .tool_protocols import hidden_chain, replay_hidden, reply_chain, tool_protocol
from .tool_protocols.common import PREFIX, SummaryError
from .vendors import parameter_fingerprint
from .windows import remind, status_line
logger = logging.getLogger(__name__)
# State keys for unsigned thinking the gateway relayed, by digest of its text.
THINKING = "thinking:"
@dataclass
class Prepared:
body: dict
original: dict
protocol: str
scope: str
session: str
chain: list[str]
messages: list[dict]
kind: str
anchor: int
root: dict
records: dict
disabled: bool = False
metrics: dict = field(default_factory=dict)
body_chain: list[str] = field(default_factory=list)
capture_chain: list[str] = field(default_factory=list)
strip_replayed_thinking: bool = False
anonymous: bool = False
capture: Document = field(default_factory=Document)
observation: Document = field(default_factory=Document)
capture_target: str = ""
tools_active: bool = False
# Definitions and hidden history replay, but the tool loop refuses every gateway call.
tools_closed: bool = False
hidden_history_unavailable: bool = False
upstream: dict = field(default_factory=dict)
# The estimated current context and the window it is measured against.
context_tokens: int = 0
context_window: int = 0
# Sessions and thinking digests this request read; it keeps them from expiring.
ancestors: list[str] = field(default_factory=list)
thinking: list[str] = field(default_factory=list)
# Anchors of replies whose thinking the client resent as text.
thinking_as_text: set[str] = field(default_factory=set)
# The reply's anchor; ``relayed`` records it once it succeeds.
relayed: bool = False
reply_anchor: str = ""
# What the reply starts with for the user: the recall notice of this turn's injection.
reply_lead: str = ""
class MemoryKernel:
def __init__(self, store: KernelStore, viking):
self.store, self.viking = store, viking
@staticmethod
def degraded_body(body, protocol):
adapter = tool_protocol(protocol)
if adapter.signed_thinking:
return {**body, adapter.field: strip_thinking(body.get(adapter.field, []))}
return body
async def enhance(self, body, protocol, *args):
try:
prepared = await self.prepare(body, protocol, *args)
return prepared.body, prepared, prepared.metrics
except Exception:
logger.exception("OpenViking Gateway preparation failed")
return self.degraded_body(body, protocol), None, {"degradation": "memory_store_failure"}
async def sent_history(self, scope, messages, protocol):
"""The history as the gateway relayed it: thinking a client resent as text is dropped.
Some providers return thinking without a signature, and clients such as pi
resend it as a text block. Anchors drop thinking, so that text would keep
every reply from matching its anchors in the next request.
"""
adapter = tool_protocol(protocol)
texts = {
id(b): THINKING + digest(b["text"])
for m in messages
for b in adapter.thinking_as_text(m)
}
known = await self.store.state.read(scope, list(set(texts.values()))) if texts else {}
if not known:
return messages, []
dropped = {block for block, key in texts.items() if key in known}
return [
{**m, "content": [b for b in m["content"] if id(b) not in dropped]}
if adapter.thinking_as_text(m)
else m
for m in messages
], sorted(known)
async def identity(self, scope, messages, protocol, headers):
"""Resolve the session and the sessions whose replies the history contains.
Replies are matched in the chain flavour ``completed`` records them in. A
request without a session header continues the session that produced the
latest reply it contains, or starts a new one when two sessions produced it.
"""
sid = session_id(headers)
adapter = tool_protocol(protocol)
def chains():
chain = prefix_chain(messages)
if not adapter.canonicalizes_history:
return chain, chain
return chain, hidden_chain(messages, protocol)
# Small prompts need no executor; large payloads must not block the loop.
if len(messages) > 32 or any(len(m.get("content") or "") > 8192 for m in messages):
chain, body_chain = await asyncio.to_thread(chains)
else:
chain, body_chain = chains()
endpoints = [
a for a, m in zip(body_chain, messages, strict=True) if a and adapter.is_reply(m)
]
owners = await self.store.replay.replies(scope, endpoints) if endpoints else {}
anonymous = sid is None
if anonymous:
latest = next((owners[a] for a in reversed(endpoints) if a in owners), set())
sid = next(iter(latest)) if len(latest) == 1 else "anonymous-" + uuid.uuid4().hex
# A reply two sessions produced, such as a greeting, proves no inheritance.
ancestors = sorted({next(iter(o)) for o in owners.values() if len(o) == 1} - {sid})
return sid, anonymous, chain, body_chain, ancestors
async def prepare(
self,
body,
protocol,
headers,
credential,
upstream,
policy,
counting=False,
upstreams=(),
summarize=None,
):
"""Build the upstream body; ``summarize(prepared, body)`` sends a summary request."""
adapter = tool_protocol(protocol)
sent = adapter.messages(body)
if not isinstance(sent, list) or not all(isinstance(m, dict) for m in sent):
raise ValueError("invalid message list")
# The lead is the gateway's, not the model's: the client resends it, but nothing
# matches, captures or forwards it, as replies were recorded without it.
sent = adapter.strip_lead(sent)
scope = digest(credential["account"] + "\0" + credential["user_id"] + "\0" + protocol)
# Anchors, capture and recall read the history as the gateway relayed it;
# the upstream still gets exactly what the client sent.
messages, thinking = await self.sent_history(scope, sent, protocol)
sid, anonymous, chain, body_chain, ancestors = await self.identity(
scope, messages, protocol, headers
)
as_text = (
{a for a, m, s in zip(body_chain, messages, sent, strict=True) if m != s}
if thinking
else set()
)
records, observations, capture = await self.store.load(
scope, sid, list(dict.fromkeys(["", *chain, *body_chain])), ancestors
)
plugin = plugin_present(body, headers)
root = await self.session_root(records, scope, sid, body, upstream, policy, credential)
upstream = next((u for u in upstreams if u["id"] == root["upstream_id"]), upstream)
policy = Policy.model_validate(root["policy"])
kind, anchor = classify(body, headers, messages)
if body.get("tools"):
if (K.CLIENT_TOOLS, "") not in records:
await self.store.replay.put(scope, sid, K.CLIENT_TOOLS, "", {})
elif (
kind == "user"
and (K.CLIENT_TOOLS, "") in records
and not any(adapter.is_reply(m) for m in messages)
):
# Clients such as Claude Code send side requests, like summarizing a fetched
# page, under the conversation's session header: a fresh exchange without
# tools. A turn of the conversation itself resends its replies.
kind = "auxiliary"
disabled = (K.DISABLED, "") in records
if plugin and not disabled:
await self.store.replay.put(scope, sid, K.DISABLED, "", {"reason": "plugin_present"})
disabled = True
# A token count gets gateway tools exactly when the request it measures would.
owner = not disabled and kind in {"user", "continuation"}
root = await self.session_tools(
records,
scope,
sid,
root,
body,
protocol,
upstream,
credential,
owner,
body_chain,
counting,
)
kind = "count" if counting else kind
result = {**body, adapter.field: [dict(m) for m in sent]}
prepared = Prepared(
result,
body,
protocol,
scope,
sid,
chain,
messages,
kind,
anchor,
root,
records,
disabled=disabled,
anonymous=anonymous,
body_chain=body_chain,
capture_chain=body_chain,
capture=capture,
observation=observations.get(sid, Document()),
capture_target=capture.value.get("ov_session", ""),
upstream=upstream,
ancestors=ancestors,
thinking=thinking,
thinking_as_text=as_text,
metrics={
"kind": kind,
"replay_hits": 0,
"recall_count": 0,
"recall_ms": 0,
"session": sid,
"protocol": protocol,
"credential_id": credential["id"],
},
)
CapturePipeline.metrics(prepared, policy)
# Replay first: it decides whether replies keep their reasoning, which tools depend on.
self.replay(prepared)
self.configure_tools(prepared, policy, owner)
if not disabled and policy.capture and kind == "user" and anchor >= 0:
await CapturePipeline(self.store.capture).confirm(prepared, credential, policy)
if kind in {"user", "continuation"}:
prepared.context_window = window_size(prepared, policy)
prepared.context_tokens = await self.measure(prepared)
prepared.metrics.update(
context_tokens=prepared.context_tokens, context_window=prepared.context_window
)
if (
summarize
and policy.compaction
and not disabled
and prepared.context_tokens >= policy.compaction_threshold * prepared.context_window
):
await self.compact(prepared, credential, policy, summarize)
# Recall and window signals come after any new cut, so they describe the
# context the model actually gets.
if not disabled:
if kind == "user" and anchor >= 0 and (K.INJECTION, chain[anchor]) not in records:
await self.recall(prepared, credential, policy)
await remind(self.store, prepared, policy)
if (
not disabled
and kind == "user"
and anchor >= 0
and policy.show_recall
and not reply_block_reason(body)
):
# A retry of the turn shows the same notice: it is part of the immutable decision.
decision = prepared.records.get((K.INJECTION, chain[anchor]), {})
prepared.reply_lead = decision.get("notice", "")
self.assemble(prepared)
if isinstance(body.get("input"), str) and result.get("input") == sent:
result["input"] = body["input"]
return prepared
async def session_root(self, records, scope, sid, body, upstream, policy, credential):
root = records.get((K.ROOT, ""))
if root is None:
root = await self.store.replay.put(
scope,
sid,
K.ROOT,
"",
{
"upstream_id": upstream["id"],
"policy": policy,
"credential_id": credential["id"],
"vendor": {
"prompt_cache_key": body.get("prompt_cache_key")
or "ovgw-" + digest(scope + sid)[:40],
"parameters": parameter_fingerprint(body),
},
},
)
return root
async def session_tools(
self,
records,
scope,
sid,
root,
body,
protocol,
upstream,
credential,
owner,
body_chain,
counting=False,
):
"""The root with the session's gateway tools and why there are none."""
policy = root["policy"]
# A branch where the model called a gateway tool keeps the tools, so its
# history still replays.
used = any((K.HIDDEN, anchor) in records for anchor in body_chain)
# Sessions created before tools had their own record keep them in the root.
decision = records.get((K.TOOLS, "")) or (root if "tools" in root else None)
if decision is None:
# Helper requests, such as a title with structured output, often come first;
# the first request that could use tools decides for the session. So does
# one resending tool rounds, as a sub-agent in a session of its own does.
if not (owner or used) or not policy.get("gateway_tools"):
return {**root, "tools": [], "tool_skip_reason": ""}
if tool_block_reason(body, protocol, upstream):
return {**root, "tools": [], "tool_skip_reason": ""}
# A failed load leaves the session without tools.
tools, reason = [], ""
try:
tools = select_tools(await self.viking.tools(credential["openviking_key"]), policy)
except VikingError:
reason = "tools_unavailable"
decision = await self.store.replay.put(
scope, sid, K.TOOLS, "", {"tools": tools, "tool_skip_reason": reason}
)
tools, reason = decision["tools"], decision.get("tool_skip_reason", "")
closed = records.get((K.TOOLS_CLOSED, ""))
# Client OpenViking tools may appear late, as when MCP servers connect after the
# first turn. Until the model has called a gateway tool, they turn gateway tools
# off for good; the client changed its tool list then, so caches miss anyway.
# A token count may cover only part of the client's tools, so it never decides.
if tools and closed is None and owner and not counting and not used:
names = [t["function"]["name"].removeprefix(PREFIX) for t in tools]
if client_openviking_tools(body, names):
closed = await self.store.replay.put(
scope, sid, K.TOOLS_CLOSED, "", {"reason": "tool_name_collision"}
)
if closed is not None and not used:
tools, reason = [], closed["reason"]
return {**root, "tools": tools, "tool_skip_reason": reason}
@staticmethod
def configure_tools(request, policy, owner):
tools = request.root["tools"]
request.metrics["tools_tokens"] = 0
adapter = tool_protocol(request.protocol)
if tools:
# Assemble restores no reasoning here, and thinking resent as text stays text.
restores = not (
request.disabled or request.strip_replayed_thinking or request.thinking_as_text
)
reason = tool_block_reason(
request.original, request.protocol, request.upstream, restores
)
# Upstreams reject duplicate tool names, so an exact clash always skips.
names = {t["function"]["name"] for t in tools}
collision = any(
isinstance(t, dict)
and isinstance(t.get("function", t), dict)
and t.get("function", t).get("name") in names
for t in request.original.get("tools") or []
)
hidden = any((K.HIDDEN, anchor) in request.records for anchor in request.body_chain)
if reason or collision:
request.metrics["tool_skip_reason"] = reason or "tool_name_collision"
request.hidden_history_unavailable = hidden
elif owner or hidden:
# Only the conversation's own turns get gateway tools. Others that resend
# history using them still replay it byte for byte, for provider caches and
# thinking signatures, but the tool loop refuses their calls.
adapter.add_tools(request.body, tools)
request.tools_active, request.tools_closed = True, not owner
request.metrics["tools_tokens"] = token_estimate(
orjson.dumps(adapter.wire_tools(tools)).decode()
)
elif policy.gateway_tools and owner:
request.metrics["tool_skip_reason"] = (
tool_block_reason(request.original, request.protocol, request.upstream)
or request.root["tool_skip_reason"]
or "tools_not_selected_at_session_start"
)
@staticmethod
def replay(request):
adapter = tool_protocol(request.protocol)
messages = request.body[adapter.field]
missing = False
sent = set(request.observation.value.get("sent", []))
# A cut removes the messages up to it, together with any lost injection.
cut = active_cut(request)
for index, anchor in enumerate(request.chain):
decision = request.records.get((K.INJECTION, anchor))
if decision is not None:
if decision["text"]:
adapter.append_context(messages[index], decision["text"])
request.metrics["replay_hits"] += 1
elif anchor in sent and index > cut:
missing = True
reason = ""
if request.upstream["id"] != request.root["upstream_id"]:
reason = "upstream_changed"
elif missing and adapter.signed_thinking:
reason = "missing_injection_record"
if reason:
request.body[adapter.field] = strip_thinking(messages)
request.strip_replayed_thinking = True
request.metrics["degradation"] = reason
if request.disabled:
request.metrics["degradation"] = "plugin_present"
async def recall(self, request, credential, policy):
started = time.monotonic()
existing = [
(index, request.records[K.INJECTION, anchor])
for index, anchor in enumerate(request.chain)
if (K.INJECTION, anchor) in request.records
]
# The budget is per context window: a cut frees the recall it replaced.
cut = active_cut(request)
current = [value for index, value in existing if index > cut]
used = sum(v.get("tokens", 0) for v in current)
# ponytail: exclude_uris matches a whole subtree since #5627, so echoing a
# served directory would hide every file written under it later. A URI
# without a dot in its last segment is treated as a directory and echoed
# as its own level files, which excludes the node but not its children;
# an extensionless file may be served again and a dotted directory still
# hides its subtree. Upgrade path: a server-reported is_directory flag.
exclude = list(
dict.fromkeys(
x
for v in current
for u in v.get("uris", [])
for x in (
[u]
if "." in u.rsplit("/", 1)[-1]
else [f"{u}/.abstract.md", f"{u}/.overview.md"]
)
)
)
budget = min(policy.max_tokens, policy.session_max_tokens - used)
query = clean_text(unwrap_client(text_content(request.messages[request.anchor])))[
: policy.query_max_chars
]
decision = {"text": "", "uris": [], "tokens": 0, "reason": "disabled"}
reserved = False
if policy.recall and budget >= 64 and len(query) >= 3:
# The window starts at the cut, or at the history's first user message.
if cut >= 0:
window = request.capture_chain[cut]
else:
window = next(
a
for m, a in zip(request.messages, request.capture_chain, strict=True)
if is_user(m)
)
budget = await self.reserve_recall(request, policy, used, window)
reserved = budget > 0
tools = request.root["tools"]
lead = f"Relevant memory from OpenViking. {RECALL_PROVENANCE_NOTE}"
if any(tool["function"]["name"] == "openviking_read" for tool in tools):
lead += " Use the openviking_read tool to expand URIs."
overhead = token_estimate(block("gateway-recall", lead + "\n"))
# The search entries a recall returned, for the notice.
entries = []
async def retrieve():
if not reserved:
return decision
if budget - overhead < 64:
return {**decision, "reason": "budget"}
try:
response = await self.viking.recall(
credential["openviking_key"], query, policy, exclude, budget - overhead
)
rendered = response.get("rendered") or ""
text = lead + "\n" + rendered if rendered else ""
if text:
entries.extend(e for e in response.get("entries", []) if isinstance(e, dict))
return {
"text": text,
"uris": [
entry["uri"] for entry in response.get("entries", []) if entry.get("uri")
]
if text
else [],
"tokens": token_estimate(block("gateway-recall", text)),
"reason": "recalled" if text else "empty",
}
except (VikingError, asyncio.TimeoutError) as error:
return {**decision, "reason": getattr(error, "reason", "recall_timeout")}
async def opening():
if existing:
return "", []
profile = await build_profile(self.viking, credential["openviking_key"], policy, tools)
request.metrics["profile_reason"] = profile["reason"]
# After client-side compaction, the capture document still names the earlier sessions.
hint = history_hint(
credential["user_id"], lineage(request.capture.value), tools, policy.capture
)
text = block(
"gateway-session-start",
"\n\n".join(
part for part in (gateway_note(policy, tools), hint, profile["text"]) if part
),
)
return text, [*profile["parts"], *(["history"] if hint else [])]
decision, (start, parts) = await asyncio.gather(retrieve(), opening())
status, reminder = status_line(request, policy)
recalled = block("gateway-recall", "\n\n".join(p for p in (decision["text"], status) if p))
# The opening block is immutable with recall but has its own budget, and
# the window status line costs nothing.
decision["text"] = "\n\n".join(part for part in (start, recalled) if part)
if reminder:
decision["reminder"] = reminder
if policy.show_recall:
# Replay reads only text, so the notice never changes what the model gets.
decision["notice"] = recall_notice(parts, decision["reason"], entries)
anchor = request.chain[request.anchor]
decision = await self.store.replay.put(
request.scope, request.session, K.INJECTION, anchor, decision
)
if reserved:
await self.settle_recall(request, anchor, decision["tokens"])
request.records[K.INJECTION, anchor] = decision
if decision["text"]:
adapter = tool_protocol(request.protocol)
adapter.append_context(request.body[adapter.field][request.anchor], decision["text"])
request.metrics.update(
recall_count=len(decision["uris"]),
recall_ms=round((time.monotonic() - started) * 1000, 2),
recall_reason=decision["reason"],
)
async def reserve_recall(self, request, policy, used, window):
"""Reserve a bounded allowance before recall; only this document uses CAS.
A crash can leave a conservative reservation, never overspend the cap.
Competing requests for the same anchor share its reservation and the
immutable decision; settling it twice cannot refund twice. A ledger for
another context window starts over from the records in this one.
"""
anchor, old = request.chain[request.anchor], request.observation
while True:
ledger = old.value.get("recall", {})
if ledger.get("window") != window:
ledger = {"window": window, "spent": used, "pending": {}}
if anchor in ledger["pending"]:
request.observation = old
return ledger["pending"][anchor]
budget = min(policy.max_tokens, policy.session_max_tokens - ledger["spent"])
if budget < 64:
return 0
value = {
**old.value,
"recall": {
"window": window,
"spent": ledger["spent"] + budget,
"pending": {**ledger["pending"], anchor: budget},
},
}
if await self.store.state.swap(request.scope, request.session, old, value):
request.observation = Document(value, old.version + 1)
return budget
old = await get_state(self.store.state, request.scope, request.session)
async def settle_recall(self, request, anchor, tokens):
old = request.observation
while anchor in old.value.get("recall", {}).get("pending", {}):
ledger = old.value["recall"]
pending = dict(ledger["pending"])
reserved = pending.pop(anchor)
value = {
**old.value,
"recall": {
**ledger,
"spent": ledger["spent"] - reserved + tokens,
"pending": pending,
},
}
if await self.store.state.swap(request.scope, request.session, old, value):
request.observation = Document(value, old.version + 1)
return
old = await get_state(self.store.state, request.scope, request.session)
async def relayed(self, request, response):
"""Record what the client's next request is matched by, before the client can send it."""
if request.relayed:
return
output = response.output
for text in tool_protocol(request.protocol).unsigned_thinking(output):
await self.store.state.swap(request.scope, THINKING + digest(text), Document(), {})
if output and request.kind in {"user", "continuation"}:
chain = reply_chain(request, output)
request.reply_anchor = chain[-1]
if response.finished and not request.disabled and replays_reasoning(request.upstream):
await self.record_reasoning(request, output, chain)
if response.finished and request.reply_anchor:
# A reply that hands the turn to client tools is resent with their results.
await self.store.replay.put(
request.scope, request.session, K.REPLY, request.reply_anchor, {}
)
request.relayed = True
async def record_reasoning(self, request, output, chain):
"""Keep the reply's reasoning under the anchors the client resends it by."""
adapter = tool_protocol(request.protocol)
visible, reasoning = adapter.split_reasoning(output)
if not reasoning:
return
if visible is not output:
chain = reply_chain(request, visible)
# Without its reasoning items the reply ends at another anchor; forks find it there.
if chain[-1]:
await self.store.replay.put(request.scope, request.session, K.REPLY, chain[-1], {})
tail = chain[len(request.messages) :]
for index, value in reasoning.items():
if tail[index]:
await self.store.replay.put(
request.scope, request.session, K.REASONING, tail[index], value
)
async def completed(self, request, credential, response):
await self.relayed(request, response)
endpoint = request.reply_anchor
chain = set(request.chain)
sent = [
a
for (k, a), v in request.records.items()
if k == K.INJECTION and v.get("text") and a in chain
]
# The next request measures its context from this usage while the reply stays in it.
# Without counts from the upstream, it estimates the whole request instead.
usage = {
**(response.context_usage or response.usage or {}),
"anchor": endpoint,
"time": time.time(),
}
def observe(value):
if (
usage.get("input_tokens")
and endpoint
and usage["time"] >= value.get("usage", {}).get("time", 0)
):
value["usage"] = usage
if sent:
value["sent"] = list(dict.fromkeys([*value.get("sent", []), *sent]))
if request.kind == "user" and usage["time"] >= value.get("user_at", 0):
value["user_at"] = usage["time"]
return value
await self.update_observation(request, observe)
if request.ancestors or request.thinking:
await self.store.keep(request.scope, request.ancestors, request.thinking)
if (
request.disabled
or request.kind not in {"user", "continuation"}
or not response.complete
or not response.message
or request.anchor < 0
):
return
policy = Policy.model_validate(request.root["policy"])
if policy.capture:
await CapturePipeline(self.store.capture).stage(request, response, policy)
@staticmethod
def assemble(request):
"""Apply the latest cut, restore dropped reasoning, then expand or drop hidden history."""
apply_cut(request)
adapter = tool_protocol(request.protocol)
if (
not request.disabled
and not request.strip_replayed_thinking
and not (request.hidden_history_unavailable and adapter.omits_reasoning)
and replays_reasoning(request.upstream)
):
MemoryKernel.restore_reasoning(request)
messages = request.body[adapter.field]
if request.tools_active:
messages = replay_hidden(
messages, request.body_chain, request.records, request.protocol
)
if request.strip_replayed_thinking:
messages = strip_thinking(messages)
elif request.hidden_history_unavailable:
cleaned = adapter.omit_hidden_history(messages)
if cleaned != messages:
messages = cleaned
request.metrics.setdefault("degradation", "hidden_tool_history_unavailable")
request.body[adapter.field] = messages
@staticmethod
def restore_reasoning(request):
"""Give each reply back the reasoning the client dropped, the same bytes every turn.
Inserted items get no anchor, so the body chain stays aligned with the body.
Spans a hidden transcript replaces are left alone: the transcript has the
reasoning, and its visible count is the span as the client sent it.
"""
adapter = tool_protocol(request.protocol)
covered = set()
if request.tools_active:
for index, anchor in enumerate(request.body_chain):
record = request.records.get((K.HIDDEN, anchor)) if anchor else None
if record and 0 < record["visible_count"] <= index + 1:
covered.update(range(index + 1 - record["visible_count"], index + 1))
messages, chain, restored = [], [], 0
for index, (message, anchor) in enumerate(
zip(request.body[adapter.field], request.body_chain, strict=True)
):
value = request.records.get((K.REASONING, anchor)) if anchor else None
items = [message]
if value and anchor not in request.thinking_as_text and index not in covered:
items = adapter.restore_reasoning(messages, message, value)
restored += items != [message]
messages.extend(items)
chain.extend(["" for _ in items[1:]] + [anchor])
request.body[adapter.field], request.body_chain = messages, chain
if restored:
request.metrics["reasoning_restored"] = restored
@classmethod
def assembled(cls, request):
"""The body the upstream would get now, without changing the request."""
candidate = replace(request, body=dict(request.body), metrics={})
cls.assemble(candidate)
return candidate.body
async def measure(self, request):
"""Estimate the context: the last reply's usage plus what the client added after it.
Usage counts only when its reply is still in this history after the latest
cut, so usage from subagents, other branches or before a cut is ignored.
Otherwise the estimate covers the whole body the upstream would get.
"""
usage = request.observation.value.get("usage", {})
anchor, chain = usage.get("anchor"), request.capture_chain
index = chain.index(anchor) if anchor and anchor in chain else -1
if index > active_cut(request):
tokens = usage.get("input_tokens", 0) + usage.get("output_tokens", 0)
return tokens + await asyncio.to_thread(estimate, request.messages[index + 1 :])
return await asyncio.to_thread(estimate, self.assembled(request))
async def compact(self, request, credential, policy, summarize):
"""Replace the history before a new cut with a model-written summary.
The summary covers only what the cut replaces, so every branch continuing these
replies can reuse the record. Failures forward the full history and back off.
"""
failed_at = request.observation.value.get("compaction", {}).get("failed_at", 0)
cut = cut_point(request)
if cut <= active_cut(request) or time.time() - failed_at < BACKOFF_SECONDS:
return
adapter = tool_protocol(request.protocol)
body, kept = self.assembled(request), request.body[adapter.field][cut + 1 :]
messages = body[adapter.field]
span = messages[: len(messages) - len(kept)]
# A continuation is cut in the middle of the turn, before the model answered.
in_progress = request.kind == "continuation"
started = time.monotonic()
try:
# Messages after the cut are new client input that hidden history never expands.
if messages[len(span) :] != kept:
raise SummaryError("cut_not_found")
instruction = summary_instruction(policy.summary_max_tokens, in_progress)
limit = policy.summary_max_tokens
try:
response = await summarize(
request, adapter.summary_request(body, span, instruction, limit)
)
except SummaryError as error:
# Models with a small output limit reject the headroom; ask for the bare cap.
if error.reason != "summary_http_400":
raise
response = await summarize(
request, adapter.summary_request(body, span, instruction, limit, headroom=0)
)
summary = adapter.summary_text(response).strip()
if not summary:
raise SummaryError("summary_empty")
except SummaryError as error:
await self.compaction_failed(request, error.reason)
return
except Exception:
logger.exception("OpenViking Gateway summary failed")
await self.compaction_failed(request, "summary_failed")
return
anchor = request.capture_chain[cut]
if policy.capture and in_progress:
# First, so the hint names the session that receives the part being cut.
await CapturePipeline(self.store.capture).confirm_cut(request, anchor)
hint = cut_hint(request, credential["user_id"], policy)
opening = opening_block(request.records, request.chain)
text = replacement_text(summary, hint, opening, in_progress)
# A concurrent request may have written this cut first; its text wins.
record = await self.store.replay.put(
request.scope,
request.session,
K.REPLACEMENT,
anchor,
{"source": "compaction", "text": text, "tokens": token_estimate(text)},
)
request.records[K.REPLACEMENT, anchor] = record
request.metrics.update(
compaction_tokens=record["tokens"],
compaction_ms=round((time.monotonic() - started) * 1000, 2),
)
# Later readers see the compacted context; the metric keeps the estimate that triggered it.
request.context_tokens = await self.measure(request)
if request.context_tokens >= policy.compaction_threshold * request.context_window:
# What a cut cannot remove fills the window, so summarizing again soon cannot help.
await self.compaction_failed(request, "still_over_threshold")
async def compaction_failed(self, request, reason):
request.metrics["compaction_failed"] = reason
failure = {"failed_at": time.time(), "reason": reason}
await self.update_observation(request, lambda value: {**value, "compaction": failure})
async def update_observation(self, request, change):
"""Apply ``change`` to the session's observation document, retrying on conflicts."""
old = request.observation
while True:
value = change(dict(old.value))
if value == old.value:
return
if await self.store.state.swap(request.scope, request.session, old, value):
request.observation = Document(value, old.version + 1)
return
old = await get_state(self.store.state, request.scope, request.session)