tool

type CallableTool interface {
	Tool

	// Call executes the tool with the given arguments.
	// Returns the result as a map and any error that occurred.
	// This is a blocking call that waits for completion.
	Call(ctx Context, args map[string]any) (map[string]any, error)

	// Schema returns the JSON schema for the tool's parameters.
	// Returns nil if the tool takes no parameters.
	Schema() map[string]any
}

type CancellableTool interface {
	Tool

	// Cancel requests graceful termination of the tool execution
	// identified by callID. Returns true if cancellation was initiated.
	// The tool should clean up resources and return promptly.
	Cancel(callID string) bool

	// SupportsCancellation returns true if this tool type supports cancellation.
	// Tools may return false if current state prevents cancellation.
	SupportsCancellation() bool
}

type Context interface {
	agent.CallbackContext

	// FunctionCallID returns the unique ID of this tool invocation.
	FunctionCallID() string

	// Actions returns the event actions to modify state or request transfers.
	Actions() *agent.EventActions

	// SearchMemory searches the agent's memory for relevant information.
	SearchMemory(ctx context.Context, query string) (*agent.MemorySearchResponse, error)

	// Task returns the parent task for cascade cancellation registration.
	// Returns nil if no task is associated with this context.
	// Uses agent.CancellableTask to avoid circular imports.
	Task() agent.CancellableTask
}

type Definition struct {
	Name        string
	Description string
	Parameters  map[string]any
}

type Predicate func(ctx agent.ReadonlyContext, tool Tool) bool

type Request struct {
	// SystemInstruction can be appended to by tools
	SystemInstruction string

	// Messages is the conversation history (read-only recommended)
	Messages any

	// Config contains LLM configuration
	Config any

	// Metadata for tool-specific data
	Metadata map[string]any
}

type RequestProcessor interface {
	// ProcessRequest modifies the LLM request before sending.
	// Called during the preprocessing phase of the reasoning loop.
	ProcessRequest(ctx Context, req *Request) error
}

type Result struct {
	// Content is the output content, typically a string or structured data.
	Content any

	// Streaming indicates this is an intermediate chunk, not the final result.
	// When true: UI should append to existing output
	// When false: This is the final result
	Streaming bool

	// Error is set if an error occurred during execution.
	// Can be set on intermediate chunks (partial failure) or final result.
	Error string

	// Metadata contains optional additional data about this result.
	Metadata map[string]any
}

type StreamingTool interface {
	Tool

	// CallStreaming executes the tool and yields incremental results.
	// Each yielded Result represents a chunk of output.
	//
	// The iterator pattern (iter.Seq2) aligns with Go 1.23+ and ADK-Go's
	// streaming patterns, providing consistent semantics across the codebase.
	//
	// Example implementation:
	//
	//	func (t *CommandTool) CallStreaming(ctx Context, args map[string]any) iter.Seq2[*Result, error] {
	//	    return func(yield func(*Result, error) bool) {
	//	        // Start command...
	//	        for line := range outputLines {
	//	            if !yield(&Result{Content: line, Streaming: true}, nil) {
	//	                return // Client disconnected
	//	            }
	//	        }
	//	        // Final result
	//	        yield(&Result{Content: finalOutput, Streaming: false}, nil)
	//	    }
	//	}
	CallStreaming(ctx Context, args map[string]any) iter.Seq2[*Result, error]

	// Schema returns the JSON schema for the tool's parameters.
	Schema() map[string]any
}

type Tool interface {
	// Name returns the unique name of the tool.
	Name() string

	// Description returns a human-readable description of what the tool does.
	// Used by LLMs to decide when to use this tool.
	Description() string

	// IsLongRunning indicates whether this tool is a long-running async operation.
	// Long-running tools return a job ID and are polled for completion.
	// NOTE: For HITL (human approval), use RequiresApproval() instead.
	IsLongRunning() bool

	// RequiresApproval indicates whether this tool needs human approval before execution.
	// When true:
	// - Tool execution is paused before running
	// - Task transitions to `input_required` state
	// - Human must approve or deny the operation
	// - Tool executes only after approval
	//
	// This is semantically different from IsLongRunning():
	// - RequiresApproval: needs human decision, executes instantly once approved
	// - IsLongRunning: async operation, no human needed, polls for completion
	RequiresApproval() bool
}

type ToolCall struct {
	ID   string
	Name string
	Args map[string]any
}

type ToolResult struct {
	ToolCallID string
	Content    string
	Error      string
	Metadata   map[string]any
}

type Toolset interface {
	// Name returns the name of this toolset.
	Name() string

	// Tools returns the available tools based on the current context.
	// This allows dynamic tool selection based on user, session, or other factors.
	Tools(ctx agent.ReadonlyContext) ([]Tool, error)
}