| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321 |
- """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)
|