The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""``/review`` and messaging ``/refine`` for a session whose cached agent is gone.
The gateway drops a session's cached agent after an idle hour (``agent.agent_cache.idle_ttl_secs``),
under LRU or memory pressure, and around ``/moa``. The conversation outlives it in the session's
stored transcript, but ``/review`` read only the cached agent, so a session left alone for an hour
answered "Nothing to review yet" until the next message rebuilt one. A cold ``/review`` reviews the
stored transcript and dispatches the reviewer from a fresh agent on the route, toolsets and session
id the session's next turn would use, so its completion comes back exactly as a resident agent's.
"""
import asyncio
import concurrent.futures
import contextlib
import logging
logger = logging.getLogger(__name__)
async def cold_review_history(runner, source):
"""``(session_id, transcript)`` of the session ``source`` belongs to: a local session's current
physical transcript (``gateway/session_refine.py`` reads the same one), else the messaging entry's."""
from gateway.session_refine import _local_session
authority, live = _local_session(runner, source)
if live is not None:
from gateway.session_contract import SessionRef
from gateway.session_local_recovery import transcript_target
def load():
target = transcript_target(authority, SessionRef(authority.profile_id, source.chat_id))
return target, authority.db.get_messages_as_conversation(target, include_ancestors=True)
return await asyncio.to_thread(load)
entry = await runner.async_session_store.get_or_create_session(source)
return entry.session_id, await runner.async_session_store.load_transcript(entry.session_id)
async def stored_transcript(runner, session_key):
"""``(session_id, transcript)`` of a messaging session; the transcript is empty when the chat has no
session or no user/assistant turn. Read-only: ``/refine`` in a new chat must not create a session."""
session_id = await runner.async_session_store.peek_session_id(session_key)
history = await runner.async_session_store.load_transcript(session_id) if session_id else []
if not any(m.get("role") in {"user", "assistant"} for m in history):
return session_id, []
return session_id, list(history)
@contextlib.contextmanager
def cold_review_parent(runner, source, session_key, session_id):
"""A fresh agent on the session's next-turn route (built as ``session_execution._build_fresh_agent``
builds one, minus the turn-only prompt pieces), inside the session's policy scope. On exit only its
own LLM clients are released: ``close()`` would tear down the session's terminal and browser, and the
reviewer it dispatched is detached and builds its own clients."""
from gateway.run import _load_gateway_config, _platform_config_key
from gateway.session_api_turn import api_runtime_locked
from gateway.session_authorities import active_authority
from gateway.session_policy import policy_for_source, policy_scope, policy_turn_toolsets
from gateway.session_worker_construct import session_prefill, session_routing
from run_agent import AIAgent
policy = policy_for_source(runner, source)
authority = active_authority(runner) if policy else None
user_config = policy.config(authority, secrets=False) if policy else _load_gateway_config()
platform_key = policy.platform if policy else _platform_config_key(source.platform)
enabled, disabled = runner._resolve_turn_toolsets(user_config, source, platform_key)
if policy:
enabled = policy_turn_toolsets(authority, policy, user_config, source.chat_id)
# Each input below is the one the turn runner reads for this session (``run_turn_runner``).
pr = session_routing(authority, policy) if policy else runner._provider_routing
prefill = session_prefill(authority, policy, source.chat_id) if policy else runner._prefill_messages
tier = (policy.current_service_tier(runner, session_key) if policy else
runner._resolve_session_service_tier(source=source, session_key=session_key))
with policy_scope(policy, authority=authority):
model, runtime = runner._resolve_session_agent_runtime(
source=source, session_key=session_key, user_config=user_config)
route = runner._resolve_turn_agent_config("", model, runtime, tier=tier) # /fast request options
agent = AIAgent(
model=route["model"], **route["runtime"], quiet_mode=True, verbose_logging=False,
enabled_toolsets=enabled, disabled_toolsets=disabled,
# Launch-preloaded skills (``hermes -s``): the reviewer is told to load them too.
ephemeral_system_prompt=(policy.skills_prompt if policy else None) or None,
prefill_messages=prefill or None,
reasoning_config=runner._resolve_session_reasoning_config(source=source, session_key=session_key,
model=model),
service_tier=tier, request_overrides=route.get("request_overrides"),
providers_allowed=pr.get("only"), providers_ignored=pr.get("ignore"), providers_order=pr.get("order"),
provider_sort=pr.get("sort"), provider_require_parameters=pr.get("require_parameters", False),
provider_data_collection=pr.get("data_collection"),
session_id=session_id, platform=platform_key, gateway_session_key=session_key,
session_db=getattr(runner._session_db, "_db", runner._session_db),
# The session's backup providers, as its next turn would carry them: the reviewer inherits the chain.
fallback_model=None if api_runtime_locked() else runner._refresh_fallback_model(),
# The reviewer reads the transcript excerpt; this agent never runs a turn of its own.
skip_memory=True)
agent._end_session_on_close = False
try:
yield agent
finally:
with contextlib.suppress(Exception):
agent.release_clients()
def start_cold_refine(runner, source, session_key, session_id, history, focus):
"""``/refine`` for a messaging session whose cached agent is gone: the resident path's own
``_spawn_background_review`` call, made from the cold parent. A resident agent sends its review
summary into the chat through its last turn's callback (``run_turn_runner._make_bg_review_callbacks``);
this one sends it to the same chat and thread directly. Returns a future that resolves once the review
is spawned (or raises its start error); the parent's clients are released when the review's request ends,
on the thread that built it."""
from agent.async_utils import safe_schedule_threadsafe
from agent.memory_provider import spawn_context_thread
from gateway.run import _interim_metadata, _non_conversational_metadata
loop = asyncio.get_running_loop()
adapter = runner._delivery_adapter_for(source)
metadata = _interim_metadata(_non_conversational_metadata(
runner._thread_metadata_for_source(source), platform=source.platform))
started = concurrent.futures.Future()
def deliver(message):
if adapter is not None:
safe_schedule_threadsafe(adapter.send(source.chat_id, str(message), metadata=metadata), loop,
logger=logger, log_message="cold /refine summary delivery scheduling failed",
log_level=logging.WARNING)
def body():
try:
with cold_review_parent(runner, source, session_key, session_id) as parent:
parent.background_review_callback = deliver
parent._spawn_background_review(
messages_snapshot=history, review_memory=True,
review_skills="skill_manage" in getattr(parent, "valid_tool_names", set()), focus=focus or None,
explicit=True)
started.set_result(None)
run = getattr(parent, "_background_review_run", None)
if run is not None:
run.request_done.wait()
except Exception as exc: # health: allow BLE001 -- the start error becomes the /refine reply (start_failed)
if started.done():
logger.warning("cold /refine failed after it started", exc_info=True)
else:
started.set_exception(exc)
spawn_context_thread(body, name="cold-refine").start()
return asyncio.wrap_future(started)