using System.Text.Json;

namespace ClawdDotNet.Core.Tools;

public interface IAgentTool
{
    string Name { get; }
    string Description { get; }
    JsonElement InputSchema { get; }

    /// <summary>
    /// Ob dieses Werkzeug gefahrlos gleichzeitig mit anderen laufen darf.
    ///
    /// Die Vorgabe ist <c>false</c> — nicht aus Vorsicht um ihrer selbst willen,
    /// sondern weil die falsche Antwort hier nicht auffällt: Zwei schreibende
    /// Aufrufe, die sich um dieselbe Datei oder denselben Datensatz streiten,
    /// scheitern nicht zuverlässig, sondern gelegentlich. Ein Werkzeug gibt sich
    /// deshalb ausdrücklich frei, und nur dann, wenn es nichts verändert.
    ///
    /// „Nichts verändert" heißt: kein Schreiben in Dateien, Datenbank oder Fremdsystem
    /// und keine Abhängigkeit davon, was ein anderer Aufruf desselben Zuges tut.
    /// Ein reiner Abruf erfüllt das, eine Ablage nicht.
    /// </summary>
    bool IsParallelSafe => false;

    /// <summary>
    /// Ob ein zweiter, gleicher Aufruf schadlos bleibt (#554).
    ///
    /// <para>Gebraucht wird das nach einem harten Absturz: Im Protokoll steht, dass ein
    /// Aufruf begann, nicht ob er wirkte. Bei einem wiederholbaren Werkzeug muss man das
    /// auch nicht wissen — man ruft es einfach noch einmal. Bei allen anderen bleibt nur,
    /// den Fall vorzulegen statt zu raten.</para>
    ///
    /// <para>Nicht zu verwechseln mit <see cref="IsParallelSafe"/>. Das heißt „stört
    /// keinen gleichzeitigen Aufruf", dies hier heißt „richtet zweimal keinen Schaden an".
    /// Ein Werkzeug kann das eine sein und das andere nicht: Eine Datei zu überschreiben
    /// ist wiederholbar — zweimal derselbe Inhalt ergibt denselben Zustand —, verträgt
    /// aber keinen zweiten Schreiber zur selben Zeit.</para>
    ///
    /// <para>Vorgabe <c>false</c>, aus demselben Grund wie oben: Wer sich irrt, versendet
    /// die Mail zweimal.</para>
    /// </summary>
    bool IsRepeatable => false;

    /// <summary>
    /// Prueft vor Staging und Ausfuehrung, ob das Werkzeug diesen Aufruf ueberhaupt zulassen
    /// wuerde (#579). Liefert den Ablehnungsgrund oder <c>null</c>.
    ///
    /// <para>Ohne diese Pruefung legte das Staging Aufrufe zur Freigabe vor, die das
    /// Werkzeug selbst verbietet - der Mensch gab frei, und erst dann scheiterte der
    /// Aufruf. Das gewoehnt an harmlose Freigaben und laesst eine Prompt-Injection die
    /// Freigabeliste mit alarmierenden, aber unmoeglichen Vorschlaegen fuellen.</para>
    ///
    /// <para>Nur pruefen, nichts veraendern, nichts abrufen. Kann die Pruefung die
    /// Argumente nicht lesen, <c>null</c> liefern - die Ausfuehrung meldet den Fehler dann
    /// selbst.</para>
    /// </summary>
    string? Preflight(JsonElement input, AgentToolContext context) => null;

    Task<ToolResult> ExecuteAsync(
        JsonElement input,
        AgentToolContext context,
        CancellationToken ct);
}