| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263 |
- """Scripted prelude: tool calls a prompt built-in plays before the turn's first model call.
- A prelude is a generator owned by the caller that starts the turn (the desktop onboarding opening is the
- intended one). Each step it yields ``(content, tool_name, args)``: the assistant text and the one
- tool call that row carries. The loop runs it through the unchanged ``run_tool_round`` (row persisted
- before the tool runs, interim text and tool events emitted, tool hooks fired) and sends the tool's
- result string back into the generator, so a later step can use an earlier answer.
- It runs before any provider call, so the rows sit between this turn's user message and the first
- model call: nothing cached is mutated, the system prompt is untouched, no user row is added, and
- roles alternate ``user -> assistant(tool_calls) -> tool -> ... -> assistant(model)``. No API call is
- counted and no ``pre/post_api_request`` hook fires for a step.
- """
- from __future__ import annotations
- import json
- from typing import Any, Generator, Optional, Tuple
- from agent.message_sanitization import deterministic_call_id
- from agent.transports.types import NormalizedResponse, build_tool_call
- from agent.turn_tool_round import run_tool_round
- Prelude = Generator[tuple[str, str, dict], Optional[str], None]
- def prelude_call_id(session_id: str, name: str, args: dict, index: int) -> str:
- """Seeded by the session, the call and its place in history: no two chats share an id (a rerun plays
- the same card at the same place), and it stays byte-stable on replay."""
- return deterministic_call_id(name, f"{session_id}:{json.dumps(args, sort_keys=True)}", index)
- def run_scripted_prelude(agent: Any, s: Any, prelude: Prelude) -> Any:
- """Play ``prelude`` into the loop state ``s``; returns the last tool round's verdict, or None when
- no step ran. The caller ends the turn on ``return`` and skips the model on ``break``."""
- from agent.conversation_loop import _run_phase
- verdict, result = None, None
- while not agent._interrupt_requested:
- try:
- content, name, args = prelude.send(result)
- except StopIteration:
- break
- s.finish_reason = "tool_calls"
- s.assistant_message = NormalizedResponse(
- content=content, finish_reason="tool_calls",
- tool_calls=[build_tool_call(prelude_call_id(agent.session_id, name, args, len(s.messages)), name, args)])
- verdict = _run_phase(run_tool_round, agent, s)
- if verdict.action != "continue":
- break
- tail = s.messages[-1] if s.messages else {}
- result = tail.get("content") if tail.get("role") == "tool" else None
- prelude.close()
- return verdict
- def play_prelude(agent: Any, s: Any, prelude: Optional[Prelude]) -> tuple[str, Any]:
- """``("return", result)`` ends the turn now, ``("break", None)`` skips the model call, ``("run", None)`` runs
- the loop as usual (also when there is no prelude)."""
- verdict = run_scripted_prelude(agent, s, prelude) if prelude is not None else None
- if verdict is not None and verdict.action in ("return", "break"):
- return verdict.action, verdict.result
- return "run", None
|