"""Control tools (L13): handled in the harness, acting only on the agent's
own state, conversation and records. A *waiting* tool ends the driver's run:
the item then waits on the operator."""

from typing import Any


def _tool(tool: str, description: str, /, **params: str) -> dict[str, Any]:
    return {
        "type": "function",
        "function": {
            "name": tool,
            "description": description,
            "parameters": {
                "type": "object",
                "properties": {
                    p: {"type": "string", "description": d} for p, d in params.items()
                },
                "required": list(params),
            },
        },
    }


RESTATE = _tool(
    "restate",
    "Put your understanding of the request to the operator, in their item's "
    "thread: what you take it to mean, how it fits the project, your first "
    "step, and why that way (and the main alternative you considered). Ends "
    "your turn; work starts when they agree.",
    text="Your restatement, in plain language.",
    changed="What changed from your previous restatement, and why; leave it "
    "empty for the first.",
)
ASK_HUMAN = _tool(
    "ask_human",
    "Ask the operator a question in the item's thread. Ends your turn; you "
    "continue when they answer.",
    question="The question.",
)
CLOSE_ITEM = _tool(
    "close_item",
    "The work is done: close the work item with a summary of what was done, "
    "what was verified, and what is left open.",
    summary="What was done, verified, and left open.",
)

START_MILESTONE = _tool(
    "start_milestone",
    "Start a milestone before changing code: the harness cuts its branch. "
    "Never create or switch branches yourself.",
    name="A short name for the milestone.",
)
FINISH_MILESTONE = _tool(
    "finish_milestone",
    "The milestone's work is done and its tests pass: the harness commits "
    "the work, pushes it and opens a PR, or, after review comments, pushes "
    "your fix to the PR. Ends your turn; you continue when the PR is "
    "reviewed or merged.",
    summary="What the milestone did and how it was verified, for the PR.",
    title="A short title for the PR (ignored when pushing a review fix).",
    final="yes if this milestone completes the issue, no if more milestones follow it.",
)
WAIT_FOR_REVIEW = _tool(
    "wait_for_review",
    "Nothing more to do until the operator reviews or merges the PR (you "
    "can't merge it yourself): say so and wait. You continue when there's a "
    "new comment, or when it merges or closes.",
    note="What you're waiting on, for the operator.",
)

TOOLCHAIN_STEP = _tool(
    "toolchain_step",
    "The work needs a toolchain change (a new tool, library or version): a "
    "step that installs it on the build VM and brings the project's pins, "
    "setup docs and CI configuration in step. Its edits are part of the "
    "current work. Returns its report.",
    reason="What the work needs, and why.",
)

# A conversation's tools (L1, L5): it talks, and may propose work.
REPLY = _tool(
    "reply",
    "Answer the operator in the conversation's thread. Ends your turn; you "
    "continue when they say more.",
    text="Your answer, in plain language.",
)
PROPOSE_WORK = _tool(
    "propose_work",
    "The conversation has turned into work on one of the projects: propose "
    "an issue for it. The operator agrees to it as to a restatement; then the "
    "issue is opened, and work on it starts as its own item. Ends your turn.",
    project="The project's name, from the list in your instructions.",
    title="A short title for the issue.",
    summary="What was decided, distilled: the request, what it means, and the "
    "first step. Not the conversation; it is the issue's body and the work's "
    "whole brief.",
)

PROPOSE_PROJECT = _tool(
    "propose_project",
    "The conversation has become a new project: propose it. The operator "
    "agrees to it as to a restatement; then you list what it needs set up "
    "(a repository, a build VM, the project's entry), and once it is ready "
    "and checked, the project's architecture is your first piece of work. "
    "Ends your turn.",
    name="The project's name: lowercase letters, digits and -.",
    purpose="What it is for, in a paragraph.",
    decisions="The decisions setting it up depends on: language and toolchain "
    "(which pick the build VM), services, secrets, network access beyond the "
    "default; and anything else agreed so far.",
)

WAITING = frozenset(
    {
        "restate",
        "ask_human",
        "close_item",
        "finish_milestone",
        "wait_for_review",
        "reply",
        "propose_work",
        "propose_project",
        "toolchain_ready",
    }
)


def names(tools: list[dict[str, Any]]) -> set[str]:
    return {tool["function"]["name"] for tool in tools}