// Package tool defines the Tool interface and the tool management system.
//
// Tools are the atomic capabilities that can be invoked by agents or LLMs.
// Each tool has a name, description, a parameter schema (for LLM function calling),
// and an Execute method that performs the actual work.
//
// Built-in tools include file operations (read, write, list, search) and
// command execution through the sandbox. Custom tools can be registered
// via the Manager.
package tool

import (
	"context"
	"encoding/json"
)

// ParameterSchema describes a single parameter accepted by a tool.
type ParameterSchema struct {
	Type        string              `json:"type"`
	Description string              `json:"description"`
	Required    bool                `json:"required"`
	Default     interface{}         `json:"default,omitempty"`
	Properties  map[string]ParameterSchema `json:"properties,omitempty"`
	Items       *ParameterSchema    `json:"items,omitempty"`
	Enum        []string            `json:"enum,omitempty"`
}

// Result holds the output of a tool execution.
type Result struct {
	Success  bool                   `json:"success"`
	Data     interface{}            `json:"data,omitempty"`
	Error    string                 `json:"error,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

// Tool defines the interface that all tools must implement.
//
// Tools are registered with a Manager and can be discovered and invoked
// by name. The Execute method receives a context for cancellation and
// a map of string-keyed arguments.
type Tool interface {
	// Name returns the unique identifier for this tool.
	Name() string

	// Description returns a human-readable description of what this tool does.
	Description() string

	// Parameters returns the schema describing accepted arguments.
	// Used for LLM function calling and validation.
	Parameters() map[string]ParameterSchema

	// Execute performs the tool's function with the given arguments.
	// The context controls cancellation and timeouts.
	Execute(ctx context.Context, args map[string]interface{}) (*Result, error)
}

// SuccessResult creates a successful tool result with the given data.
func SuccessResult(data interface{}) *Result {
	return &Result{
		Success: true,
		Data:    data,
	}
}

// ErrorResult creates a failed tool result with the given error message.
func ErrorResult(err string) *Result {
	return &Result{
		Success: false,
		Error:   err,
	}
}

// MustMarshalArgs converts a map of arguments to JSON bytes, panicking on error.
// Useful for logging and debugging.
func MustMarshalArgs(args map[string]interface{}) []byte {
	b, err := json.Marshal(args)
	if err != nil {
		panic("tool: failed to marshal args: " + err.Error())
	}
	return b
}