The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""First-run onboarding on the session authority: ``onboarding.start`` and ``onboarding.skip``.
The onboarding chat is an ordinary local Desktop session the authority owns from its first row: the
start creates it here, writes the run record (``agent.onboarding_record``) before any agent is built,
attaches the asking connection and admits the hidden opening turn through the same durable FIFO as a
typed message. The record is what makes it an onboarding chat for every later turn: the ``onboarding``
toolset fold-in (``run_turn``), the scripted greeting and name card and the per-turn note
(``run_turn_runner``), all from ``agent.onboarding_session``. ``onboarding.state`` and
``onboarding.set_run`` read and write only config and stay on the sidecar handler.
"""
from __future__ import annotations
import asyncio
import logging
import threading
import uuid
from functools import partial
from gateway.session_contract import SessionRef
from hermes_state_runtime import RuntimeStoreError
logger = logging.getLogger(__name__)
ONBOARDING_PROFILE = 'default'
class OnboardingRefusal(RuntimeStoreError):
"""A refusal on the sidecar handler's wire: its JSON-RPC code and human message."""
def __init__(self, code, message):
super().__init__('onboarding_refused', detail=message)
self.wire_code, self.wire_message = code, message
class _NoModelForTheRun(Exception):
"""The claim was blocked and nothing else can carry the run's first chat."""
def handlers(connection):
return {'onboarding.start': partial(start, connection), 'onboarding.skip': partial(skip, connection)}
def _onboarding_connection(connection):
return connection._sibling_for(ONBOARDING_PROFILE) or connection
async def start(connection, ref, params):
from tui_gateway.contracts.profiles_vault_complete_foreign_subagents import OnboardingStartParams
from pydantic import ValidationError
try:
request = OnboardingStartParams.model_validate(params)
except ValidationError as exc:
raise RuntimeStoreError('invalid_params', detail=str(exc)) from exc
target = _onboarding_connection(connection)
if target is not connection:
# Dispatch entered the asking profile's scope; the claim, the facts and the chat's policy are default's.
from gateway.session_authorities import owner_scope
with owner_scope(target.authority):
return await start(target, ref, params)
if 'session:create' not in connection.actor.capabilities:
raise RuntimeStoreError('permission_denied')
authority = connection.authority
lock = getattr(authority, '_onboarding_start_lock', None)
if lock is None:
lock = authority._onboarding_start_lock = asyncio.Lock()
# Held through the opening's admission: two windows pressing start at once get one chat and one opening.
async with lock:
plan = await asyncio.to_thread(_choose_run, authority, request)
stored = plan['stored'] or await _create_chat(connection)
from gateway.session_mutations import retire_live_sessions
from gateway.session_runtime_workers import tracked_write
discards = _discards(authority)
if request.fresh_launch:
discards.ids.update(sid for sid in plan['replaced']
if (live := authority.sessions.get(sid)) is None or not live.subscribers)
def retire(deleted):
retire_live_sessions(authority, deleted)
return deleted
try:
deleted = await tracked_write(authority, partial(_settle_runs, authority, request, plan, stored, discards),
retire)
finally:
discards.ids.difference_update(plan['replaced'])
if plan['claimed'] is not None:
from hermes_cli import free_tier_bootstrap
await asyncio.to_thread(free_tier_bootstrap.refresh_record)
_withdraw_setup_cards(authority, [sid for sid in plan['replaced'] if sid not in deleted])
chat = SessionRef(authority.profile_id, stored)
await connection.resume(chat, {})
opening = plan['opening'] if plan['stored'] else await asyncio.to_thread(_opening_for, authority, stored)
if opening is not None:
run_id = await asyncio.to_thread(_run_id, authority, stored)
await connection.submit(chat, {'session_id': stored, 'text': opening, 'display_kind': 'hidden',
'submission_id': f'onboarding-opening:{run_id or stored}'})
return {'session_id': stored, 'stored_session_id': stored, 'resumed': plan['stored'] is not None,
'run_id': await asyncio.to_thread(_run_id, authority, stored)}
def _choose_run(authority, request):
"""A refused claim (5079) or a blocked one with nothing else to run on (5080) leaves no chat, so
the install stays due."""
from agent.onboarding_facts import read_facts
from agent.onboarding_flow import Facts
from agent.onboarding_record import load, open_session_ids
from agent.onboarding_text import opening_prompt
from hermes_cli.auth_constants import AuthError
db = authority.db
open_ids = open_session_ids(db)
stored = None if request.rerun or request.fresh_launch else next(iter(open_ids), None)
plan = {'stored': stored, 'open_ids': open_ids, 'claimed': None, 'facts': None, 'opening': None,
'replaced': [sid for sid in open_ids if sid != stored]}
if stored is not None:
facts = Facts.from_stored(load(db, stored)['facts'])
if not (db.get_session(stored) or {}).get('message_count'):
plan['opening'] = opening_prompt(facts)
plan['facts'] = facts
return plan
plan['facts'] = read_facts(facts_source=request.facts_source.value, locale=request.locale)
if not request.rerun:
try:
plan['claimed'] = _claim_before_run(assume_fresh=request.assume_fresh)
except AuthError as exc:
logger.info('onboarding.start: welcome trial not claimed: %s', exc)
raise OnboardingRefusal(5079, str(exc)) from exc
except _NoModelForTheRun as exc:
logger.info('onboarding.start: no chat opened: %s', exc)
raise OnboardingRefusal(5080, str(exc)) from exc
return plan
def _claim_before_run(*, assume_fresh):
"""``onboarding.run: true`` on disk before the welcome-trial claim, so a crash after the claim still
opens onboarding next launch."""
from hermes_cli import anon_auth
from hermes_cli.onboarding_run import set_run
from hermes_cli.welcome_trial import claim_desktop_free_tier, provider_configured
if not anon_auth.on_local_desktop_backend():
# A CLI or TUI holds a native ticket too: its start schedules nothing. A rerun (Settings, any
# Desktop) never claims and never reaches here.
raise _NoModelForTheRun('First-run onboarding starts only in the Desktop app on this machine.')
set_run(True)
claimed = claim_desktop_free_tier(assume_fresh=assume_fresh)
if claimed is None and not (anon_auth.free_inference_active() or provider_configured()):
raise _NoModelForTheRun('The welcome trial is not available here, and no provider is set up.')
return claimed
async def _create_chat(connection):
from gateway.session_local import stage_local_session
from gateway.session_local_recovery import restore_local_session
from gateway.session_runtime_workers import tracked_write
from hermes_state_local import commit_local_session
authority = connection.authority
staged = stage_local_session(authority, connection.actor, {'source': 'gui', 'request_id': uuid.uuid4().hex},
client_local=connection.native_owner,
desktop_local=getattr(connection.transport, 'desktop_local', False))
if not (staged['policy'] or {}).get('model'):
raise OnboardingRefusal(5080, 'No model is set up to run onboarding on.')
await tracked_write(authority, partial(commit_local_session, authority.db, epoch=authority.epoch, receipt=staged))
return restore_local_session(authority, staged['session_id']).session_id
class _Discards:
"""The chats a fresh launch's start deletes because no window watched them when it looked. A window
that resumes one before its delete takes it back (``keep_from_discard``); the lock makes the take-back
and the delete one or the other, never a viewer on a deleted chat."""
def __init__(self):
self.lock = threading.Lock()
self.ids = set()
def _discards(authority):
discards = getattr(authority, '_onboarding_discards', None)
if discards is None:
discards = authority._onboarding_discards = _Discards()
return discards
async def keep_from_discard(authority, session_id):
"""``attach``, after its last other await: a chat a fresh launch was about to delete is kept. The
take-back itself never yields, so the viewer joins in the same loop step and a later start sees it
watched; a start claims only on the loop. A delete in flight holds the lock across its write, so
that wait runs off the loop and the take-back is retried after it."""
discards = getattr(authority, '_onboarding_discards', None)
while discards is not None and session_id in discards.ids:
if discards.lock.acquire(blocking=False):
discards.ids.discard(session_id)
discards.lock.release()
return
def delete_finished():
with discards.lock:
pass
await asyncio.to_thread(delete_finished)
def _settle_runs(authority, request, plan, stored, discards):
"""The new chat's record and title, and the end of every other open run; returns the chats it
deleted. One open run at a time: the kept run is open before the others end, so the install flag
never closes in between."""
from agent.onboarding_flow import End
from agent.onboarding_record import advance, start
from agent.onboarding_text import CHAT_TITLE
db = authority.db
if plan['stored'] is None:
# The record exists before any agent is built, so the first turn already folds the toolset in.
start(db, stored, plan['facts'])
deleted = []
if request.fresh_launch:
deleted = _discard_unfinished_runs(db, plan['replaced'], discards)
for old in plan['replaced']:
if old not in deleted:
advance(db, old, End('replaced'))
if plan['stored'] is None:
# After the discard, so a run started over keeps the title its deleted chat had.
db.set_session_title(stored, db.get_next_title_in_lineage(CHAT_TITLE))
return deleted
def _discard_unfinished_runs(db, stored_ids, discards):
"""A new launch's start: the runs the app was closed on never count as done. A chat no window
watches (still in *discards*) is deleted the way ``session.delete`` deletes it, which ends its run
(``deleted``) and tells every window; the caller retires the deleted ids from the authority. A chat a
window reopened, or one a turn still writes (the delete refuses it), is kept, and its run ends as
``replaced`` so it is never resumed."""
from pathlib import Path
from agent.onboarding_record import delete_chat
sessions_dir = Path(db.db_path).parent / 'sessions'
deleted = []
for old in stored_ids:
with discards.lock:
if old not in discards.ids:
continue
try:
if delete_chat(db, old, lambda old=old: db.delete_session(
old, sessions_dir=sessions_dir, exclude_active_write_guards=True)):
deleted.append(old)
except Exception:
logger.exception('onboarding.start could not delete unfinished chat %s', old)
return deleted
def ending_run_on_delete(db, session_id, commit):
"""*commit* (the canonical delete's receipt transaction) wrapped so deleting the chat that holds
the live run ends that run (``deleted``) and tells every window, as the sidecar's
``session.delete`` did. Returns the receipt."""
from agent.onboarding_record import delete_chat
receipt = []
def delete():
receipt.append(commit())
return session_id in receipt[0]['deleted_ids']
delete_chat(db, session_id, delete)
return receipt[0]
def _withdraw_setup_cards(authority, stored_ids):
"""Close the card still waiting in a chat whose run just ended; its answer would be refused."""
from gateway.session_server_requests import withdraw
for sid in stored_ids:
live = authority.sessions.get(sid)
if live is not None:
withdraw(live.event_stream, sid, 'setup_beat')
def _opening_for(authority, stored):
from agent.onboarding_flow import Facts
from agent.onboarding_record import load
from agent.onboarding_text import opening_prompt
if (authority.db.get_session(stored) or {}).get('message_count'):
return None
return opening_prompt(Facts.from_stored(load(authority.db, stored)['facts']))
def _run_id(authority, stored):
from agent.onboarding_record import load
return (load(authority.db, stored) or {}).get('run_id') or ''
async def skip(connection, ref, params):
"""Skip setup: end the chat's run and close the card that waits. The card's asker reads the
skipped record when it wakes (``setup_beat``)."""
from agent.onboarding_flow import End
from agent.onboarding_record import advance, load
from gateway.session_runtime_workers import tracked_write
from gateway.session_server_requests import withdraw
from pydantic import ValidationError
from tui_gateway.contracts.profiles_vault_complete_foreign_subagents import OnboardingSkipParams
try:
request = OnboardingSkipParams.model_validate(params)
except ValidationError as exc:
raise RuntimeStoreError('invalid_params', detail=str(exc)) from exc
if not request.session_id:
raise RuntimeStoreError('invalid_params')
authority = connection.authority
authority.authorize(connection.actor, ref, 'session:control')
db = authority.db
if load(db, db.get_compression_tip(ref.session_id) or ref.session_id) is None:
return {'skipped': False}
step = await tracked_write(authority, partial(advance, db, ref.session_id, End('skipped')))
live = authority.sessions.get(ref.session_id)
if live is not None:
withdraw(live.event_stream, ref.session_id, 'setup_beat')
return {'skipped': bool(step.result.get('skipped_all'))}
def arm_onboarding_turn(agent, owner, history):
"""The onboarding chat's per-turn inputs on an authority-owned local turn: the turn note (which
card is closed and how to bring it back) appended to the API-only notes, and the scripted opening
returned for ``run_conversation(prelude=...)``. Nothing for a chat without ``setup_beat``."""
from agent.onboarding_session import append_turn_note, builds_onboarding, onboarding_prelude, onboarding_turn_note
if owner is None or not builds_onboarding(agent):
return None
from gateway.session_server_requests import waiting
authority, session_id, _generation = owner
live = authority.sessions.get(session_id)
card_waiting = live is not None and waiting(live.event_stream, session_id, 'setup_beat')
append_turn_note(agent, onboarding_turn_note(agent, history_empty=not history, card_waiting=card_waiting))
return onboarding_prelude(agent, history)