The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""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 {}