Skip to content

The agent that grows with you

22.7 KB
Raw Blame
"""Resolve explicit model changes using the existing source model switch pipeline."""
import asyncio
import json
from dataclasses import asdict, replace
from typing import NamedTuple

from gateway.session_route_identity import ROUTE_BOUND_KEYS
from hermes_state_runtime import RuntimeStoreError


class _Route(NamedTuple):
    provider: str
    model: str
    base_url: str
    api_key: object  # a callable bearer (Azure Entra) stays callable


def _current_route(authority, live, old):
    """``(config, route)`` the session runs now, both from ONE read of the owning profile.

    A following session runs the profile's current route, so its frozen creation endpoint beside
    the current key would send that key to a host the profile left. Main switched from the live
    runtime's whole tuple (``tui_gateway.model_switch._current_model_runtime``). The provider is
    the configured name: a named ``providers:`` entry resolves to the bare ``custom`` class, and a
    pick on the same entry must not read as a route change. Only the session's own route counts:
    a fallback is where a turn lands, not what the user switches from. A route that cannot
    authenticate here must not block leaving it: like main's agent-less ``--provider`` path, the
    pick then switches from the configured provider alone and resolves its own target.
    """
    from gateway.session_policy import profile_read_scope
    from hermes_cli.auth import AuthError
    with profile_read_scope(old, authority):
        config = old.config(authority)
        block = config.get('model') or {}
        try:
            model, runtime = authority.runner._resolve_session_agent_runtime(
                source=live.source, session_key=live.route, fallback=False)
        except AuthError:
            return config, _Route(block.get('provider') or '', old.current_model(authority) or '',
                                  block.get('base_url') or '', '')
    return config, _Route(block.get('provider') or runtime.get('provider') or '', model or '',
                          runtime.get('base_url') or '', runtime.get('api_key') or '')


async def prepare_model(authority, live, payload, prepared):
    from gateway.session_policy import restore_policy, bind_launch_key, bound_route_holds, route_launch_key
    from gateway.session_policy_credentials import recover_config_secrets
    from hermes_cli.model_switch import apply_model_selection, switch_model
    from hermes_cli.config import get_compatible_custom_providers
    old = restore_policy(prepared['snapshot']['receipt']['policy'])
    config, current = _current_route(authority, live, old)
    reset = is_model_reset(payload)
    if reset:
        payload = await asyncio.to_thread(_reset_payload, authority, old, current)
        if 'status' in payload:
            return payload
    # A pick is an explicit user action: it resolves against the owning profile's CURRENT named
    # providers, as CLI/TUI ``/model`` do (#139740). A following session's ``config`` already is
    # the profile's current read; every other session keeps ``config`` for its own route below.
    resolution = config if old.follows_profile else await asyncio.to_thread(
        _provider_resolution_config, authority, config, old.ignore_user_config)

    def switch(**kwargs):
        result = switch_model(**kwargs)
        return result, _alias_credential(authority, result)
    result, alias_credential = await asyncio.to_thread(switch, raw_input=payload['model'],
        current_provider=current.provider, current_model=current.model, current_base_url=current.base_url,
        current_api_key=current.api_key, explicit_provider=payload.get('provider', ''),
        is_global=False, user_providers=resolution.get('providers'),
        custom_providers=get_compatible_custom_providers(resolution))
    if not result.success:
        raise RuntimeStoreError('model_resolution_failed')
    # The configured default is the user's own choice: a reset is never held behind a cost ask.
    refusal = None if reset else await _selection_guard_refusal(
        authority, live, payload, prepared['snapshot'], current, result)
    if refusal is not None:
        return refusal
    frozen = old.config()
    # The committed selection freezes the ONE picked endpoint (its key stays a private secret).
    provider_secrets, retired, moved = ({}, (), {}) if old.follows_profile else _freeze_selected_provider(
        resolution, frozen, result.target_provider)
    if old.follows_profile:
        # A following session switches FROM the profile's current route: measured from its creation
        # endpoint, a pick on the current one read as a route change and dropped its key_env pointer.
        followed = config.get('model') or {}
        # An inline key (or an alias key's pointer) authenticates the route it was picked on: once the
        # followed route moved, the same-route cleanup below would keep it for the new endpoint.
        held = bound_route_holds(frozen.get('model'), frozen, followed, config)
        # Every other route-bound key follows the profile's current route.
        kept = ('api_key', 'api', 'api_key_from') if held else ()
        route_keys = tuple(k for k in ROUTE_BOUND_KEYS if k not in kept)
        frozen['model'] = {k: v for k, v in (frozen.get('model') or {}).items() if k not in route_keys}
        # The profile's inline key and its private-secret pointer are not copied into the receipt:
        # its secrets stay at the profile's own path, never re-committed under this session.
        frozen['model'].update({k: followed[k] for k in route_keys
                                if k in followed and k not in ('api_key', 'api', 'api_key_from')})
    # The one selection shape config.yaml gets (#25106): api_mode follows the target, a context pin
    # and the endpoint-bound credential fields (inline key, key_env/api_key_env) drop on a route change.
    # Off-loop: the context-pin check can do cold-start disk I/O.
    frozen['model'] = await asyncio.to_thread(apply_model_selection, frozen.get('model'), result)
    if 'reasoning' in payload:
        # The level picked with the model lands in the same commit (as prepare_reasoning writes it).
        from gateway.session_policy import pin_reasoning_effort
        pin_reasoning_effort(frozen, payload['reasoning'], session=True)
    if old.follows_profile:
        # A committed /model holds while the profile still targets what it targets now (main's
        # composer_override_profile); a later profile edit supersedes it.
        from pathlib import Path
        from gateway.run import _load_gateway_config
        from gateway.session_policy import present_sections, profile_target
        live = await asyncio.to_thread(
            lambda: _load_gateway_config(Path(authority.db.db_path).resolve().parent / 'config.yaml'))
        frozen['model']['selection_profile'] = list(profile_target(present_sections(live)))
    # A direct alias's own credential is part of the selection (never ``result.api_key``, which the
    # switch resolved for its probe): its env pointer is committed and re-read every turn; a literal
    # key is a private config secret at the alias entry's own path (what a restarted owner re-reads)
    # and the receipt keeps only a pointer to it, which config() projects into ``model.api_key``.
    key_env, source, alias_key = alias_credential
    key_env = key_env or _selected_provider_key_env(resolution, result.target_provider)
    if key_env:
        frozen['model']['key_env'] = key_env
    if source:
        frozen['model'].update(api_key=None, api_key_from=list(source))
    elif 'api_key' not in frozen['model']:
        frozen['model'].pop('api_key_from', None)
    # Creation identity (request_json) remains immutable; runtime selection lives in the policy.
    policy = replace(old, model=result.new_model, config_json=json.dumps(frozen))
    secrets = recover_config_secrets(authority, old) if old.config_secret_ref else {}
    # The picked entry's private subtree is replaced whole: a key or header its current declaration
    # withdrew must not follow it to the new endpoint.
    # An unrelated entry the pick displaced carries its own secrets to its new index.
    secrets = {moved.get(path[:2], path[:2]) + path[2:]: value for path, value in secrets.items()}
    secrets = {path: value for path, value in secrets.items() if path[:2] not in retired}
    secrets.update(provider_secrets)
    # A cleared field's private value must not be re-hydrated into the new route by config().
    secrets = {path: value for path, value in secrets.items()
               if not (len(path) == 2 and path[0] == 'model' and path[1] not in frozen['model'])}
    if source:
        secrets.pop(('model', 'api_key'), None)
        secrets[source] = alias_key
    # Re-fingerprint frozen config references because policy identity includes model.
    # An explicit launch key belongs to the endpoint it authenticated, not to a provider name:
    # custom -> custom on another base_url must not carry it (same route identity as config keys).
    # Measured on resolved routes (a respelled provider on one endpoint is one route; a named entry
    # whose base_url moved is another): the key survives only while it still authenticates the route
    # the session runs now and the pick stays on that route.
    key = route_launch_key(authority, old, config)
    if key is None or not bound_route_holds(config.get('model'), config, frozen['model'], config):
        policy = replace(policy, credential_ref=None)
        key = None
    policy = bind_launch_key(authority, prepared['snapshot']['receipt']['session_id'], policy, key,
                             config_secrets=secrets)
    return dict(prepared, policy=asdict(policy))


def is_model_reset(payload):
    """``/model reset`` as a ``model`` mutation; with any other selection field it is refused, as on
    every surface (``parse_model_switch_args``)."""
    from hermes_cli.model_switch import (
        MODEL_SWITCH_ERR_RESET_WITH_FLAGS, MODEL_SWITCH_ERROR_TEXT, MODEL_SWITCH_RESET_TOKEN)
    if payload['model'].strip().lower() != MODEL_SWITCH_RESET_TOKEN:
        return False
    if set(payload) - {'model', 'confirm'}:
        raise RuntimeStoreError('invalid_params', field='payload',
                                detail=MODEL_SWITCH_ERROR_TEXT[MODEL_SWITCH_ERR_RESET_WITH_FLAGS])
    return True


def configured_default(authority):
    """``(model, provider)`` the owning profile's config.yaml names now (``auto`` reads as no provider)."""
    from gateway.run import _resolve_gateway_model
    from gateway.session_policy import profile_config
    profile = profile_config(authority)
    block = profile.get('model')
    if not block:
        return '', ''
    provider = str(block.get('provider') or '') if isinstance(block, dict) else ''
    return _resolve_gateway_model(profile), '' if provider.lower() == 'auto' else provider


def _reset_payload(authority, old, current):
    """``/model reset``: the pick becomes the owning profile's configured model, read fresh, so the
    session runs (and, when following, keeps following) its profile again; history is kept. Returns a
    ``noop`` report when the session already runs that model. A safe-mode session never read the
    profile, so it has no configured default to return to."""
    from agent.i18n import t
    model, provider = ('', '') if old.ignore_user_config else configured_default(authority)
    if not model:
        raise RuntimeStoreError('invalid_params', field='payload.model', detail=t('cli.model.reset_no_default'))
    if model == current.model and provider in ('', current.provider):
        return {'status': 'noop', 'model': model, 'note': t('cli.model.reset_none', model=model)}
    return {'model': model, **({'provider': provider} if provider else {})}


def _provider_resolution_config(authority, config, bypass=False):
    """*config* with the owning profile's CURRENT named providers over its frozen ones, used only to
    resolve and freeze a pick. Reads this owner's own config.yaml (never another profile's); a
    frozen entry the profile no longer declares stays resolvable. A session that bypasses the
    profile (``ignore_user_config``, implied by safe mode) resolves only its own frozen config.
    ``${VAR}`` refs expand against the profile's CURRENT ``.env``, not the daemon's start env."""
    from pathlib import Path
    from gateway.session_local import load_profile_config
    if bypass:
        return config
    current = load_profile_config(Path(authority.db.db_path).resolve().parent)
    if not isinstance(current, dict):
        return config
    resolved = dict(config)
    frozen_providers, current_providers = config.get('providers'), current.get('providers')
    if isinstance(frozen_providers, dict) or isinstance(current_providers, dict):
        current_providers = current_providers if isinstance(current_providers, dict) else {}
        slugs = {_provider_key_slug(key) for key in current_providers}
        # A respelled key is the same provider: the profile's spelling replaces the frozen one.
        resolved['providers'] = {**{key: entry for key, entry in (
            frozen_providers if isinstance(frozen_providers, dict) else {}).items()
            if _provider_key_slug(key) not in slugs}, **current_providers}
    frozen_custom, current_custom = config.get('custom_providers'), current.get('custom_providers')
    if isinstance(frozen_custom, list) or isinstance(current_custom, list):
        current_custom = list(current_custom) if isinstance(current_custom, list) else []
        names = {_custom_provider_name(entry) for entry in current_custom if isinstance(entry, dict)}
        # Current entries keep their profile positions (the path cold recovery re-reads).
        resolved['custom_providers'] = current_custom + [
            entry for entry in (frozen_custom if isinstance(frozen_custom, list) else [])
            if not isinstance(entry, dict) or _custom_provider_name(entry) not in names]
        resolved['_profile_custom_count'] = len(current_custom)
    return resolved


def _custom_provider_name(entry):
    """The runtime's canonical identity: ``My Provider`` and ``my-provider`` are one provider."""
    from hermes_cli.providers import custom_provider_slug
    return custom_provider_slug(str(entry.get('name') or ''), str(entry.get('provider_key') or ''))


def _selected_provider_key_env(config, provider):
    """Return a selected ``providers.<slug>`` credential pointer, never its secret value."""
    providers = config.get('providers')
    entry = providers.get(provider) if isinstance(providers, dict) else None
    if not isinstance(entry, dict):
        return None
    return str(entry.get('key_env') or entry.get('api_key_env') or '').strip() or None


def _freeze_selected_provider(config, frozen, provider):
    """Copy only the picked named provider's declaration into the frozen session route.

    The next turn resolves from the session's own configuration, not a later profile edit. Private
    fields move to the policy's secret store, as policy creation does; nothing else moves. Returns
    ``(secrets, retired)``: the entry's private values and every ``(section, key)`` whose previous
    private subtree they replace, plus ``moved``: ``{old (section, index): new}`` for an unrelated entry
    the pick displaced. A legacy entry from the profile is frozen at its profile index (the path cold
    recovery re-reads); an equivalent earlier spelling is blanked, never left to win.
    """
    from copy import deepcopy
    from gateway.session_policy import _extract_config_secrets
    from hermes_cli.runtime_provider_custom import named_custom_provider_config_path
    path = named_custom_provider_config_path(provider, config)
    if path is None:
        return {}, (), {}
    section, index = path
    entries = config.get(section)
    if not isinstance(entries, (dict, list)) or not isinstance(entries[index], dict):
        return {}, (), {}
    copied = deepcopy(entries[index])
    retired, moved = {(section, index)}, {}
    if section == 'providers':
        previous = frozen.get(section) if isinstance(frozen.get(section), dict) else {}
        stale = {key for key in previous if _provider_key_slug(key) == _provider_key_slug(index)}
        frozen[section] = {**{k: v for k, v in previous.items() if k not in stale}, index: copied}
        retired |= {(section, key) for key in stale}
    else:
        frozen_entries = list(frozen.get(section) or [])
        name = _custom_provider_name(copied)
        same = [i for i, entry in enumerate(frozen_entries)
                if isinstance(entry, dict) and _custom_provider_name(entry) == name]
        if index >= config.get('_profile_custom_count', len(entries)):
            index = same[0]  # a frozen-only entry stays where it is
        frozen_entries += [{}] * (index + 1 - len(frozen_entries))
        displaced = frozen_entries[index]
        if isinstance(displaced, dict) and displaced and _custom_provider_name(displaced) != name:
            moved[(section, index)] = (section, len(frozen_entries))
            frozen_entries.append(displaced)  # still resolvable by name, with its own secrets
        for i in same:
            frozen_entries[i] = {}
        frozen_entries[index] = copied
        retired |= {(section, i) for i in same} | {(section, index)}
        frozen[section] = frozen_entries
    secrets = {}
    _extract_config_secrets(frozen[section][index], secrets, (section, index))
    return secrets, retired, moved


def _provider_key_slug(key):
    """A ``providers:`` key's canonical identity: ``Review Prov`` and ``review-prov`` are one."""
    from hermes_cli.providers import custom_provider_slug
    return custom_provider_slug('', str(key))


def _alias_credential(authority, result):
    """``(key_env, source_path, literal_key)`` the direct alias a switch resolved declares for its own
    endpoint, read from THIS owner's config.yaml: the file a restarted owner re-reads, never the
    process-global alias cache another served profile may refill after the switch. A raw
    ``api_key: "${VAR}"`` is the pointer ``VAR``; ``(None, None, None)`` when it declares none."""
    from pathlib import Path
    from gateway.run import _load_gateway_config
    from hermes_cli.config import _env_ref_var_name, read_user_config_raw
    name = result.resolved_via_alias if result.success else ''
    path = Path(authority.db.db_path).resolve().parent / 'config.yaml'
    raw = read_user_config_raw(path) if name else {}
    for section in (('model_aliases',), ('model', 'aliases')):
        model = raw.get('model')  # `model: name` (a scalar) is valid config and declares no aliases
        entries = raw.get(section[0]) if len(section) == 1 else (model.get('aliases') if isinstance(model, dict) else None)
        for written, entry in (entries.items() if isinstance(entries, dict) else ()):
            if not isinstance(entry, dict) or not entry.get('model') or str(written).strip().lower() != name:
                continue
            key = str(entry.get('api_key') or '').strip()
            pointer = _env_ref_var_name(key[2:-1]) if key.startswith('${') and key.endswith('}') else None
            if pointer:
                return pointer, None, None
            if not key:
                return str(entry.get('key_env') or '').strip() or None, None, None
            value = _load_gateway_config(path)
            for part in (*section, written, 'api_key'):
                value = value.get(part) if isinstance(value, dict) else None
            if not value:
                raise RuntimeStoreError('model_resolution_failed')
            return None, (*section, written, 'api_key'), value
    return None, None, None


def _persisted_selection_context(authority, snapshot, current):
    from agent.usage_anchor import persisted_anchor_tokens
    from hermes_cli.model_selection_guards import SelectionContext
    target = snapshot.get('target') or snapshot['receipt']['session_id']
    tokens = persisted_anchor_tokens(authority.db, target, authority.db.get_messages_as_conversation(target))
    return SelectionContext(context_tokens=tokens, current_model=current.model or None) if tokens else None


async def _selection_guard_refusal(authority, live, payload, snapshot, current, result):
    """The shared selection-guard registry (cost, data-policy, large-context switch) runs before the
    commit. A flagged target is refused with ``status: confirmation_required`` and a ``confirm``
    token bound to the resolved target, the selection it replaces and the session revision; nothing
    is written. Only that exact token in ``payload['confirm']`` applies it: a stale or foreign
    token (target re-resolved elsewhere, another switch landed, a turn settled) gets a fresh
    refusal, never a silent apply."""
    import hashlib
    from hermes_cli.model_selection_guards import combined_message, selection_context_for_agent, selection_warnings
    from hermes_cli.route_identity import normalize_route_base_url
    lookup = (getattr(authority.runner, '_resident_agent_for', None)
              or getattr(authority.runner, '_cached_agent_for', None))
    agent = lookup(live.route) if live is not None and callable(lookup) else None
    context = selection_context_for_agent(agent)
    if context is None:
        # No resident agent (evicted by the previous switch, or an owner restart): the session's
        # persisted usage anchor still measures the context at stake, so the large-context guard
        # does not go quiet on exactly the switch that follows another one.
        context = await asyncio.to_thread(_persisted_selection_context, authority, snapshot, current)
    # Off-loop: pricing lookups may hit models.dev on a cache miss.
    warnings = await asyncio.to_thread(
        selection_warnings, result.new_model, provider=result.target_provider,
        base_url=result.base_url or current.base_url, api_key=result.api_key or current.api_key,
        model_info=result.model_info, selection_context=context)
    if not warnings:
        return None
    binding = {'target': [result.new_model, result.target_provider, normalize_route_base_url(result.base_url),
                          result.api_mode or ''],
               'current': [current.model, current.provider, normalize_route_base_url(current.base_url)],
               'session': [snapshot['target'], snapshot['target_revision']],
               'guards': sorted(w.kind for w in warnings)}
    token = hashlib.sha256(json.dumps(binding, sort_keys=True).encode()).hexdigest()
    if payload.get('confirm') == token:
        return None
    # A fresh dict: the prepared snapshot carries the frozen policy and never leaves the owner. No
    # ``model`` key: a client that predates the exchange must not paint the target as applied.
    return {'status': 'confirmation_required', 'confirm_required': True, 'confirm': token,
            'target_model': result.new_model, 'target_provider': result.target_provider,
            'confirm_message': combined_message(warnings),
            'warnings': [{'kind': w.kind, 'title': w.title, 'message': w.message} for w in warnings]}