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