skills_index_delta.py 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138
  1. """Skills that change mid-conversation reach the model without a prompt rebuild.
  2. The ``<available_skills>`` index lives in the system prompt, and a conversation keeps those bytes
  3. for its whole life so the provider prefix cache stays warm (#104414). A skill installed, created or
  4. removed after the prompt was built (hub install, ``skill_manage``, the curator, a plugin going
  5. live, a change made by another process) therefore never reached the index the model routes on
  6. until compaction rebuilt the prompt. Every turn compares the index the prompt carries with the
  7. index the session would build now and delivers the difference on the per-turn user-message note
  8. channel, behind the cached prefix (ported from cloudflare/cloudflare-os#267).
  9. Each note states the FULL difference against the prompt, so the prompt plus the newest note is the
  10. complete record of what the model was told. A fresh agent (the gateway builds one per turn) reads that record back
  11. from the transcript once; a long-lived agent (CLI, TUI, Desktop) keeps it on itself. A note is sent
  12. only when the difference changes.
  13. """
  14. from __future__ import annotations
  15. import logging
  16. import re
  17. from typing import Any
  18. from agent.message_content import flatten_message_text
  19. logger = logging.getLogger("run_agent")
  20. _NOTE_PREFIX = "[System: The skills available in this conversation changed after its system prompt was built."
  21. _ADDED_HEAD = "Now available (load with skill_view(name) when relevant, like the skills listed in the system prompt):"
  22. _REMOVED_HEAD = "No longer available:"
  23. _ACCURATE_AGAIN = " The skills listed in the system prompt are accurate again; earlier skill-change notes are superseded."
  24. _ROW = " - "
  25. _BLOCK_RE = re.compile(r"<available_skills>\n?(.*?)</available_skills>", re.DOTALL)
  26. _NAMES_ONLY_RE = re.compile(r"\[names only\]:\s*(.+)$")
  27. _Delta = tuple[frozenset, frozenset]
  28. def _row_name(line: str) -> str:
  29. """Skill name of an index row (`` - name: description`` / `` - name``). Split on ``": "``:
  30. plugin skills are qualified (``plugin:skill``), so a bare ``":"`` is part of the name."""
  31. return line.strip()[2:].split(": ", 1)[0].strip()
  32. def index_entries(prompt: Any) -> dict[str, str]:
  33. """``{name: index row}`` for every skill in ``prompt``'s ``<available_skills>`` block; names-only
  34. category rows (focus mode) map to ``""``. ``{}`` without a block."""
  35. match = _BLOCK_RE.search(prompt) if isinstance(prompt, str) else None
  36. entries: dict[str, str] = {}
  37. for line in match.group(1).splitlines() if match else ():
  38. if line.strip().startswith("- ") and (name := _row_name(line)):
  39. entries.setdefault(name, line.rstrip())
  40. elif names_only := _NAMES_ONLY_RE.search(line):
  41. for name in filter(None, (n.strip() for n in names_only.group(1).split(","))):
  42. entries.setdefault(name, "")
  43. return entries
  44. def _render(added: dict[str, str], removed: set[str]) -> str:
  45. if not added and not removed:
  46. return f"{_NOTE_PREFIX}{_ACCURATE_AGAIN}]"
  47. parts = [_NOTE_PREFIX]
  48. if added:
  49. # Rows re-indented to _ROW: a one-skill category's row sits at category depth in the index,
  50. # and _parse reads names back only from _ROW lines.
  51. parts += [_ADDED_HEAD, *(_ROW + (added[name].lstrip() or f"- {name}")[2:] for name in sorted(added))]
  52. if removed:
  53. parts.append(f"{_REMOVED_HEAD} {', '.join(sorted(removed))}")
  54. return "\n".join(parts) + "]"
  55. def _parse(note: str) -> _Delta:
  56. """Inverse of :func:`_render` for the text that follows ``_NOTE_PREFIX``."""
  57. lines = note.split("\n")
  58. added: set[str] = set()
  59. if _ADDED_HEAD in lines[1:2]:
  60. for line in lines[2:]:
  61. if not line.startswith(_ROW):
  62. break
  63. added.add(_row_name(line.removesuffix("]")))
  64. removed: set[str] = set()
  65. for line in lines[1:]:
  66. if line.startswith(_REMOVED_HEAD):
  67. tail = line[len(_REMOVED_HEAD):].removesuffix("]")
  68. removed = {n.strip() for n in tail.split(",") if n.strip()}
  69. break
  70. return frozenset(added), frozenset(removed)
  71. def _announced(conversation_history: Any) -> _Delta:
  72. """The difference named by the newest skills note anywhere in the transcript: a note far back
  73. still describes the current state when nothing changed since it was sent."""
  74. for msg in reversed(conversation_history or []):
  75. if not isinstance(msg, dict) or msg.get("role") != "user":
  76. continue
  77. sidecar = msg.get("api_content")
  78. text = (sidecar if isinstance(sidecar, str) else "") + "\n" + flatten_message_text(msg.get("content"))
  79. if _NOTE_PREFIX in text:
  80. return _parse(text.rsplit(_NOTE_PREFIX, 1)[1])
  81. return frozenset(), frozenset()
  82. def stage_skills_index_note(agent: Any, prompt: Any, conversation_history: Any) -> bool:
  83. """Stage a one-shot note when the skills this session can load differ from ``prompt``'s index
  84. by something the model has not been told yet. Returns whether it staged.
  85. A prompt without an index is never compared: it has no baseline (skills tools off, a seeded or
  86. embedder-supplied prompt), and announcing the whole catalog there would only add noise. MoA and
  87. codex_app_server turns never stamp the ``api_content`` sidecar, so the note could not be read
  88. back from the transcript; those modes skip it, like the surface-switch note."""
  89. if getattr(agent, "provider", None) == "moa" or getattr(agent, "api_mode", None) == "codex_app_server":
  90. return False
  91. stored = index_entries(prompt)
  92. if not stored:
  93. return False
  94. try:
  95. from agent.system_prompt import _skills_prompt
  96. current = index_entries(_skills_prompt(agent))
  97. except Exception:
  98. logger.debug("skills index delta: current index unavailable", exc_info=True)
  99. return False
  100. told = getattr(agent, "_skills_index_told", None)
  101. key = hash(prompt)
  102. told_added, told_removed = told[1] if isinstance(told, tuple) and told[0] == key else _announced(conversation_history)
  103. # What the model believes it can load: the prompt's index as amended by the newest note. A rebuilt
  104. # prompt (compaction) that now lists what an earlier note announced needs no further note.
  105. if (set(stored) | told_added) - told_removed == set(current):
  106. agent._skills_index_told = (key, (told_added, told_removed))
  107. return False
  108. added = {name: row for name, row in current.items() if name not in stored}
  109. removed = set(stored) - set(current)
  110. agent._skills_index_told = (key, (frozenset(added), frozenset(removed)))
  111. agent._skills_index_note = _render(added, removed)
  112. logger.info(
  113. "Session %s: skills changed (+%d/-%d) since the system prompt was built; delivering the "
  114. "change as a turn note (prefix cache preserved).",
  115. getattr(agent, "session_id", None), len(added), len(removed),
  116. )
  117. return True