"""UI-only task progress tool.

The tool gives the model a structured way to publish a short user-visible plan.
Its result is intentionally tiny; the full plan stays in the assistant tool_call
arguments for Web rendering and is compacted out of older LLM context.
"""
from __future__ import annotations

import json
from typing import Any

from .base import Tool


class TaskProgressTool(Tool):
    name = "task_progress"
    description = (
        "Publish or update a concise user-visible progress checklist for the current task. "
        "Use only for meaningful multi-step work: set the plan once, update a step when it "
        "starts or completes, and clear it only when it is no longer relevant. This is a UI "
        "progress signal, not a work product."
    )
    parameters = {
        "type": "object",
        "additionalProperties": False,
        "properties": {
            "action": {
                "type": "string",
                "enum": ["set_plan", "update_step", "clear"],
                "description": "set_plan replaces the checklist; update_step changes one step; clear removes it.",
            },
            "steps": {
                "type": "array",
                "description": "Required for set_plan. Keep to 3-7 user-meaningful steps.",
                "items": {
                    "type": "object",
                    "additionalProperties": False,
                    "properties": {
                        "id": {"type": "string", "description": "Stable short id, e.g. s1."},
                        "title": {"type": "string", "description": "Short user-visible step title."},
                        "status": {
                            "type": "string",
                            "enum": ["pending", "in_progress", "completed"],
                        },
                    },
                    "required": ["id", "title", "status"],
                },
            },
            "step": {
                "type": "object",
                "description": "Required for update_step.",
                "additionalProperties": False,
                "properties": {
                    "id": {"type": "string"},
                    "title": {"type": "string"},
                    "status": {
                        "type": "string",
                        "enum": ["pending", "in_progress", "completed"],
                    },
                },
                "required": ["id", "status"],
            },
        },
        "required": ["action"],
    }

    def execute(self, **kwargs: Any) -> str:
        action = str(kwargs.get("action") or "")
        out: dict[str, Any] = {"ok": True, "action": action}
        if action == "set_plan":
            steps = kwargs.get("steps")
            out["step_count"] = len(steps) if isinstance(steps, list) else 0
        elif action == "update_step":
            step = kwargs.get("step")
            if isinstance(step, dict) and step.get("id"):
                out["step_id"] = str(step["id"])
        return json.dumps(out, ensure_ascii=False, separators=(",", ":"))