onboarding_session.py 4.3 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192
  1. """The onboarding chat's per-session pieces, shared by every runtime that hosts it (the session
  2. authority's local turns and the old sidecar): the ``onboarding`` toolset fold-in, the scripted opening
  3. and the per-turn note. Pure over the agent and the run record (``agent.onboarding_record``)."""
  4. from __future__ import annotations
  5. from typing import Any, Iterable, Iterator
  6. def builds_onboarding(agent) -> bool:
  7. return "setup_beat" in (getattr(agent, "valid_tool_names", None) or ())
  8. def keeps_toolsets(enabled) -> bool:
  9. """An explicit empty list is a zero-tool chat; None is unrestricted and still gets the fold-in."""
  10. return enabled is not None and (not enabled or "onboarding" in enabled)
  11. def with_onboarding(enabled) -> list[str]:
  12. """*enabled* plus onboarding. None (every toolset outside the session-gated ones, which onboarding
  13. is) is spelled out by name: the agent's other toolset gates read the names, as they read None."""
  14. if enabled is None:
  15. from toolsets import TOOLSET_SESSION_PLATFORMS, get_all_toolsets
  16. enabled = [name for name in get_all_toolsets() if name not in TOOLSET_SESSION_PLATFORMS]
  17. return [*enabled, "onboarding"]
  18. def onboarding_toolsets(enabled, db, session_id: str):
  19. """*enabled* plus ``onboarding`` for a chat whose run is in progress. Decided once, at agent build:
  20. the tool array is part of the cached prefix, so a finished run keeps setup_beat (as a refusal)
  21. until the session is rebuilt."""
  22. from agent.onboarding_flow import is_active
  23. from agent.onboarding_record import load
  24. if keeps_toolsets(enabled):
  25. return enabled
  26. return with_onboarding(enabled) if is_active(load(db, session_id)) else enabled
  27. def onboarding_chat_toolsets(enabled, db, session_id: str):
  28. """The session authority's per-turn fold-in: *enabled* plus ``onboarding`` for a chat that is or was
  29. an onboarding chat. Keyed on the record existing, never on the run being open, because the
  30. authority resolves toolsets every turn and the tool array is part of the cached prefix: a run that
  31. ends must not change it mid-conversation (setup_beat answers a finished run with a refusal)."""
  32. from agent.onboarding_record import load
  33. if keeps_toolsets(enabled) or db is None:
  34. return enabled
  35. tip = db.get_compression_tip(session_id) or session_id
  36. return with_onboarding(enabled) if load(db, tip) is not None else enabled
  37. def carry_onboarding_toolset(enabled, agent):
  38. """A tool refresh keeps the onboarding toolset the agent was built with."""
  39. if keeps_toolsets(enabled) or "onboarding" not in (getattr(agent, "enabled_toolsets", None) or ()):
  40. return enabled
  41. return with_onboarding(enabled)
  42. def onboarding_prelude(agent, history: Iterable[dict]) -> Iterator[tuple[str, str, dict]] | None:
  43. """The opening's scripted step, greeting and name card, while the name beat was never shown. A
  44. greeting already in the chat (a relaunch) is not said twice."""
  45. from agent.onboarding_flow import PENDING, is_active
  46. from agent.onboarding_record import load
  47. from agent.onboarding_text import greeting
  48. if not builds_onboarding(agent):
  49. return None
  50. record = load(agent._session_db, agent.session_id)
  51. if record is None or not is_active(record) or record["beats"]["name"] != PENDING:
  52. return None
  53. hello = greeting((record.get("facts") or {}).get("locale"))
  54. said = any(m.get("role") == "assistant" and m.get("content") == hello for m in history)
  55. def opening():
  56. yield ("" if said else hello), "setup_beat", {"beat": "name"}
  57. return opening()
  58. def onboarding_turn_note(agent, *, history_empty: bool, card_waiting: bool) -> str:
  59. """Before a user turn in the onboarding chat, while no card waits: which card is closed and how to
  60. bring it back."""
  61. from agent.onboarding_flow import is_active
  62. from agent.onboarding_record import load
  63. from agent.onboarding_text import turn_note
  64. if history_empty or card_waiting or not builds_onboarding(agent):
  65. return ""
  66. record = load(agent._session_db, agent.session_id)
  67. return (turn_note(record) or "") if record is not None and is_active(record) else ""
  68. def append_turn_note(agent: Any, note: str) -> None:
  69. if note:
  70. prior = getattr(agent, "_gateway_turn_context_notes", "") or ""
  71. agent._gateway_turn_context_notes = f"{prior}\n\n{note}" if prior else note