"""
Checklist tool for tracking agent creation workflow.

This tool helps the agent track progress when building reusable agents:
- write_agent_creation_checklist: Creates and updates a checklist for agent creation steps
"""

from langchain_core.tools import tool as langchain_tool

from universal_mcp.agents.codeact0.state import Todo


@langchain_tool
async def write_agent_creation_checklist(checklist: list[Todo]) -> str:
    """Create or update a checklist to plan and track the prototyping steps for a reusable agent.

    ### TRIGGER CONDITIONS & USAGE
    - Use this tool ONLY when the user explicitly asks to "create a workflow", "create a reusable agent", or "build an automation".
    - Do NOT use this for one-off tasks, direct answers, or simple script executions.
    - Use this tool to manage complex objectives, ensuring you track each necessary item and give the user visibility into your progress.

    ### PURPOSE & INPUT
    - The input is a **checklist** of atomic actions required for the workflow, not the execution of the full workflow.
    - The aim is to verify logic on a *single sample* before compiling the final agent. Do not list every iteration (e.g., "Process item 1", "Process item 2"); instead, list the logical block being tested.

    ### OPERATING RULES
    1. **Pre-tested Steps**: If any steps have already been tested, mark them as 'completed' immediately when creating the checklist.
    2. **Sample-First Override**: If the user asks to process multiple items, your checklist items MUST be to "Process ONE single sample". You are forbidden from processing the full batch unless explicitly requested.
    3. **Real-Time Updates**: Mark the first task `in_progress` immediately. Update to `completed` as soon as the logic is verified.
    4. **End with Planning**: For reusable agents, the final step must always be calling `plan_agent`.

    ### Example Flow
    - "Test data fetching from API" (in_progress)
    - "Verify data extraction on one sample" (pending)
    - "Prototype report generation format" (pending)
    - "Call plan_agent to save the agent" (pending)

    Args:
        checklist: A list of checklist items, each with 'content' (str) and 'status' ('pending', 'in_progress', 'completed').
    """
    total = len(checklist)
    completed_count = sum(1 for t in checklist if t.get("status") == "completed")

    in_progress_content = None
    for t in checklist:
        if t.get("status") == "in_progress":
            in_progress_content = t.get("content", "")
            break
    if in_progress_content is None:
        for t in checklist:
            if t.get("status") == "pending":
                in_progress_content = t.get("content", "")
                break

    # Build human-readable status string: "x/y completed, <full_text> in progress"
    status_str = f"{completed_count}/{total} completed"
    if in_progress_content:
        status_str += f", {in_progress_content} in progress"

    # If everything is done, guide the agent on next steps
    if total > 0 and completed_count == total:
        status_str += ". All completed"

    return status_str
