// Package tools implements the tool server (sandboxed execution, tool registry,
// skill management) and supporting types.
package toolsrv

import (
	"context"
	"encoding/json"
)

// ToolInfo describes a tool provided by a server.
type ToolInfo struct {
	Server      string
	Name        string
	Description string
	InputSchema json.RawMessage
	// Prompt is the usage documentation for this tool, extracted from
	// the script's ollie:prompt block. Included in the system prompt.
	Prompt string
	// Tier is the retention tier: "hot", "warm", or "cold". Parsed from
	// the script's ollie:tier annotation. Empty defaults to "hot".
	Tier string
	// ReadOnly is true when the tool carries an "ollie:parallel read" annotation.
	ReadOnly bool
}

// Runner is the minimal interface satisfied by any tool server (local or remote).
// Consumers that need polymorphism over Server and RemoteServer use this.
type Runner interface {
	ListTools() ([]ToolInfo, error)
	CallTool(ctx context.Context, tool string, args json.RawMessage) (json.RawMessage, error)
}

// ParallelClassifier is implemented by tool servers that can report whether a
// named tool is safe to run concurrently with other read-class tools.
// Returns false for unknown tools (conservative default).
type ParallelClassifier interface {
	IsParallelRead(name string) bool
}

// TierClassifier is implemented by tool servers that can report the retention
// tier of a tool's results: "hot" (verbatim), "warm" (summarized on compaction),
// or "cold" (immediately summarized). Returns "hot" for unknown tools.
type TierClassifier interface {
	ResultTier(name string) string
	// ResultTierArgs classifies the tier using both the outer tool name and its
	// arguments.
	ResultTierArgs(name string, args json.RawMessage) string
}

// Handler is the signature for built-in tool handlers.
type Handler func(ctx context.Context, srv *Server, args json.RawMessage) (string, error)