hermes-agent/hermes_cli/gateway_mutations.py

"""Prepared native controls retain their identity across ambiguous RPC replies."""
import json
import uuid
from hermes_cli.gateway_client import COMPRESS_RPC_TIMEOUT, GatewayClientError


class PreparedMutations:
    def __init__(self):
        self.pending = {}

    async def apply(self, client, session_id, operation, payload, *, confirm=None):
        """The owner's answer for this prepared mutation (retained across ambiguous replies).

        A guarded model target answers ``status: confirmation_required`` and writes nothing.
        ``confirm`` (``async (refusal) -> bool``) is the surface's prompt: yes re-sends the same
        retained mutation once with ``payload.confirm`` = the owner's token (under the original
        key, so an ambiguous reply to the confirmed send retries that exact request); no answers
        ``status: cancelled``. Without a prompt (non-interactive) the refusal is an error, and a
        confirmed send refused again (another switch or a turn landed first) is never re-asked.

        ``payload`` may be a function of the snapshot the CAS tuple is read from (a rewind names
        its target row from that same transcript); returning None means "nothing to do" and is
        answered ``status: nothing``. A derived payload is keyed by operation alone, so a lost-reply
        retry re-presents the original target instead of re-deriving one from an already-rewound
        transcript. Metadata edits (``rename``) carry no generation fence, as on Ink/Desktop."""
        key = _key(session_id, operation, payload)
        self.retire(session_id, keep=key)
        if key not in self.pending:
            snapshot = await client.rpc('session.resume', session_id=session_id)
            body = payload(snapshot) if callable(payload) else json.loads(key[2])
            if body is None:
                return {'status': 'nothing', 'session_id': session_id, 'operation': operation}
            fence = {} if operation in _METADATA else {'expected_generation': snapshot['execution_generation']}
            self.pending[key] = {'params': dict(session_id=session_id, operation=operation, payload=body,
                request_id=uuid.uuid4().hex, expected_revision=snapshot['revision'], **fence)}
        entry = self.pending[key]
        while 'result' not in entry:
            try:
                # A compression answers after its summary + commit; the default budget would report
                # a timeout while the owner (which shields the mutation) still commits it.
                budget = {'_timeout': COMPRESS_RPC_TIMEOUT} if operation == 'compress' else {}
                entry['result'] = await client.rpc('session.mutate', **budget, **entry['params'])
            except GatewayClientError as exc:
                # A disconnect is not a definitive authority refusal. Preserve
                # the tuple; never refresh its preconditions behind the user.
                if str(exc) in {'invalid_params', 'revision_conflict', 'stale_generation',
                                'session_busy', 'unknown_execution', 'permission_denied',
                                'model_resolution_failed', 'nothing_to_compress',
                                'unsupported_compress_options'}:
                    self.pending.pop(key)
                raise
            refusal = entry['result']
            if refusal.get('status') != 'confirmation_required':
                break
            # The owner wrote nothing (no receipt): the same tuple may be re-sent with the token.
            del entry['result']
            if confirm is None or 'confirm' in entry['params']['payload']:
                self.pending.pop(key)
                raise GatewayClientError(model_refusal_text(refusal, confirmed=confirm is not None))
            try:
                accepted = await confirm(refusal)
            except BaseException:
                self.pending.pop(key)
                raise
            if not accepted:
                self.pending.pop(key)
                return {'status': 'cancelled', 'session_id': session_id, 'operation': operation}
            entry['params'] = {**entry['params'], 'request_id': uuid.uuid4().hex,
                               'payload': {**entry['params']['payload'], 'confirm': refusal['confirm']}}
        return entry['result']

    def acknowledge(self, session_id, operation, payload):
        self.pending.pop(_key(session_id, operation, payload), None)

    def retire(self, session_id, *, keep=None):
        """Only a session's very next control may be the retry of an ambiguous one: any other verb
        on the session (a different control, a prompt) retires its retained identities, so a later
        deliberate repeat is new work instead of replaying a stale receipt."""
        for key in [key for key in self.pending if key[0] == session_id and key != keep]:
            del self.pending[key]


_METADATA = frozenset({'rename'})


def _key(session_id, operation, payload):
    return (session_id, operation, None if callable(payload) else json.dumps(payload, sort_keys=True))


def model_refusal_text(refusal, *, confirmed=False):
    """Why a guarded model target was not applied (the owner's guard text first)."""
    reason = ('the session changed before the confirmation landed; run /model again.' if confirmed else
              'this target needs a confirmation; run /model in an interactive session to confirm it.')
    return f"{refusal['confirm_message']}\n\nModel not switched: {reason}"


def confirmation_title(refusal):
    """The one prompt title for the owner's guard warnings (as ``combined_selection_warning``)."""
    warnings = refusal.get('warnings') or []
    return warnings[0]['title'] if len(warnings) == 1 else 'Model Selection Warning'


def confirm_choice(raw, choices):
    """``once`` / ``cancel`` (or None) for a typed answer: the choice's number or the classic
    CLI's confirm aliases (y/yes/once, n/no/cancel)."""
    from hermes_cli.cli_modal_mixin import _CONFIRM_ALIASES
    answer = (raw or '').strip().lower()
    if answer.isdigit() and 0 < int(answer) <= len(choices):
        return choices[int(answer) - 1][0]
    allowed = {choice[0] for choice in choices}
    normalized = _CONFIRM_ALIASES.get(answer, answer)
    return normalized if normalized in allowed else None


def compress_payload(arg):
    """Structured ``session.mutate(compress)`` payload from the raw ``/compress`` arguments.

    The shared parser is the one every native surface uses, so ``--preview`` stays a read-only
    flag and ``here [N]`` a boundary instead of becoming a focus topic; ``--aggressive`` has no
    canonical implementation and is refused before anything reaches the authority.
    """
    from agent.conversation_compression_manual import AGGRESSIVE_UNSUPPORTED, parse_compress_args
    request = parse_compress_args(arg)
    if request.aggressive:
        raise GatewayClientError(AGGRESSIVE_UNSUPPORTED)
    payload = {}
    if request.focus_topic:
        payload['focus'] = request.focus_topic
    if request.preview:
        payload['preview'] = True
    if request.partial:
        payload.update(partial=True, keep_last=request.keep_last)
    return payload


def slash_mutation(command, arg):
    name = command.lstrip('/')
    if name == 'model':
        from hermes_cli.model_switch import parse_model_flags_detailed
        parsed = parse_model_flags_detailed(arg)
        if parsed.is_global or parsed.is_once or parsed.force_refresh or not parsed.model_input:
            raise GatewayClientError('unsupported_model_options')
        return name, {'model': parsed.model_input, **(
            {'provider': parsed.explicit_provider} if parsed.explicit_provider else {})}
    if name == 'compress':
        return name, compress_payload(arg)
    if name != 'branch':
        raise GatewayClientError('unsupported_command')
    return name, {'title': arg} if arg else {}