surface_switch.py 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  1. """Surface switch without a prompt rebuild (#104414).
  2. A surface switch (desktop <-> TUI, a session resumed under a different host) changes only which
  3. interface renders the reply, but the surface guidance and the ``Platform:`` trailer are embedded
  4. in the persisted system prompt. Rebuilding for it diverged the prompt within its first blocks,
  5. so the ENTIRE request behind it re-prefilled — a 220K-token session came back at a 1% cache hit.
  6. The stored bytes are therefore kept and the CURRENT surface's guidance is delivered on the
  7. per-turn user-message channel instead: that lands after the cached prefix and is stamped into
  8. the byte-stable ``api_content`` sidecar so later turns replay it unchanged. The prompt itself
  9. converges at the next rebuild boundary (compaction).
  10. """
  11. from __future__ import annotations
  12. import logging
  13. from typing import Any, List
  14. from agent.message_content import flatten_message_text
  15. from agent.prompt_builder import RUNTIME_ENVIRONMENT_END, RUNTIME_ENVIRONMENT_HEADING
  16. logger = logging.getLogger("run_agent")
  17. _SURFACE_SWITCH_NOTE_PREFIX = "[System: This conversation is now being answered on a different interface: "
  18. # Closes the surface name in the note; platform names are free-form for plugin platforms, so the
  19. # terminator (not ".") delimits the parse.
  20. _SURFACE_NAME_END = " — any earlier interface guidance"
  21. # Only the newest note matters, and the note is re-stamped on the switch turn, so a bounded tail
  22. # scan is enough; without a bound every turn of a never-switched session walks the whole transcript.
  23. _NOTE_SCAN_TAIL = 200
  24. def split_runtime_boundary(prompt: str) -> tuple:
  25. """``(identity, runtime_marker, runtime)`` of a persisted prompt. Legacy prose may quote
  26. the runtime heading, but only the new renderer ENDS in the boundary; when the marker is
  27. empty the whole prompt is identity."""
  28. identity, runtime_marker, runtime = prompt.rpartition(f"\n\n{RUNTIME_ENVIRONMENT_HEADING}\n\n")
  29. return (identity, runtime_marker, runtime) if prompt.endswith(RUNTIME_ENVIRONMENT_END) else (prompt, "", "")
  30. def runtime_host_value(prompt: str, label: str) -> str:
  31. """``Label: value`` from the host lines of a persisted prompt (``Current working directory``);
  32. new prompts delimit runtime hints, legacy prompts put them before context. "" when absent."""
  33. _identity, runtime_marker, runtime = split_runtime_boundary(prompt)
  34. prefix = f"{label}:"
  35. host_lines = (runtime.split("\n\n", 1)[0] if runtime_marker else prompt).splitlines()
  36. for idx, line in enumerate(host_lines):
  37. if line.startswith("User home directory:"):
  38. for candidate in host_lines[idx + 1: idx + 4]:
  39. if candidate.startswith(prefix):
  40. return candidate[len(prefix):].strip()
  41. return ""
  42. def identity_line_value(prompt: str, label: str) -> str:
  43. """``Label: value`` from the trailer paragraph that ends the identity portion (the final
  44. runtime block is embedder prose, never identity). Memory, context files and plugin prose
  45. come earlier and may hold ``Label:`` lines of their own; they are never read as identity,
  46. even when the trailer omits the label because its value is empty."""
  47. prefix = f"{label}:"
  48. trailer = split_runtime_boundary(prompt)[0].rsplit("\n\n", 1)[-1]
  49. matches = [line[len(prefix):].strip() for line in trailer.splitlines() if line.startswith(prefix)]
  50. return matches[-1] if matches else ""
  51. def _last_announced_surface(conversation_history: Any) -> str:
  52. """The surface named by the NEWEST switch note in the transcript ("" when none).
  53. Once a switch has been announced, that note — not the stored prompt's ``Platform:`` trailer —
  54. is the last thing the model was told it runs on. Reading it back is also what keeps a fresh
  55. AIAgent per turn (the gateway shape) from stacking one copy of the note per turn."""
  56. for msg in reversed((conversation_history or [])[-_NOTE_SCAN_TAIL:]):
  57. # The note only ever lands on a user row: in its api_content sidecar, or as a text part
  58. # when the content is a multimodal list (which cannot take the string sidecar).
  59. if not isinstance(msg, dict) or msg.get("role") != "user":
  60. continue
  61. sidecar = msg.get("api_content")
  62. text = (sidecar if isinstance(sidecar, str) else "") + "\n" + flatten_message_text(msg.get("content"))
  63. if _SURFACE_SWITCH_NOTE_PREFIX in text:
  64. tail = text.rsplit(_SURFACE_SWITCH_NOTE_PREFIX, 1)[1]
  65. return tail.split(_SURFACE_NAME_END, 1)[0].strip()
  66. return ""
  67. def note_inert_pinned_tools(agent: Any, built_for_this_surface: list[str]) -> None:
  68. """Name, at the end of the staged note, the pinned tools THIS surface did not build.
  69. The freeze keeps a previous surface's tools on the wire deliberately — removing them is the one
  70. thing that would still re-prefill the request behind the preserved prompt — so the model has
  71. to be TOLD they are inert here, or it plans around a ``focus_pane`` a terminal turn can only
  72. answer with ``tool_error("desktop only")``."""
  73. from tools.mcp_tool_agent import agent_tool_names
  74. surface_names = set(built_for_this_surface)
  75. inert = [name for name in agent_tool_names(agent) if name not in surface_names]
  76. note = getattr(agent, "_surface_switch_note", "") or ""
  77. if not inert or not note:
  78. return
  79. agent._surface_switch_note = note + (
  80. "\n[System: These tools stay listed for this conversation (dropping them would discard "
  81. "the cached request prefix) but were not loaded for this interface — expect a call to "
  82. f"one of them to fail: {', '.join(inert)}.]"
  83. )
  84. def stage_surface_switch_note(agent: Any, prompt: str, conversation_history: Any) -> bool:
  85. """Stage a one-shot correction when the request would otherwise misdescribe the surface.
  86. Compares the runtime surface against what the model was last told — the newest switch note
  87. if one exists, else ``prompt``'s own ``Platform:`` trailer. Consulting the note matters in
  88. both directions: switching BACK to the prompt's surface (desktop -> tui -> desktop) leaves the
  89. trailer agreeing with the runtime while a stale note still says otherwise, and a rebuild for
  90. an unrelated reason (a model switch) refreshes the prompt but not that note. The full surface
  91. guidance is attached only when the prompt itself is out of date; otherwise the note just
  92. retires the stale one. Returns whether it staged.
  93. MoA and codex_app_server turns never stamp the ``api_content`` sidecar, so the note could not
  94. be read back and would be re-sent every turn; those modes keep the stored prompt and skip the
  95. note entirely."""
  96. if getattr(agent, "provider", None) == "moa" or getattr(agent, "api_mode", None) == "codex_app_server":
  97. return False
  98. current = str(getattr(agent, "platform", "") or "").strip()
  99. if not current:
  100. return False
  101. described = identity_line_value(prompt, "Platform")
  102. told = _last_announced_surface(conversation_history) or described
  103. if not told or told == current:
  104. return False
  105. from agent.system_prompt import platform_hint
  106. hint = platform_hint(agent) if described != current else ""
  107. where = "the guidance below" if hint else "the interface section in the system prompt above"
  108. note = (
  109. f"{_SURFACE_SWITCH_NOTE_PREFIX}{current}{_SURFACE_NAME_END} in this conversation is "
  110. f"superseded — follow {where} for formatting, file delivery and any interface-specific "
  111. "capability.]"
  112. )
  113. agent._surface_switch_note = f"{note}\n{hint}" if hint else note
  114. logger.info(
  115. "Session %s switched surface %s -> %s; keeping the stored system prompt and delivering "
  116. "the new surface guidance as a turn note (prefix cache preserved).",
  117. agent.session_id, told, current,
  118. )
  119. return True