@tool
class_name McpCustomToolSpec
extends RefCounted

## Descriptor for one custom tool registered by an addon. Mirrors the
## clients/_base.gd data-only descriptor pattern: fields are set by the
## caller, NO Callables (handler instance is materialized lazily by the
## dispatcher from script_path + method, so hot-reload can't SEGV a
## worker mid-call — same rationale as McpClient, issue #229).
##
## Construction: instantiate and set fields, then pass to
## McpToolRegistry.register(spec). Do NOT subclass — custom tools are
## dynamic (one addon may register several), not file-system-scanned
## like clients.

# --- identity ---
var name: String = ""                    ## tool name, e.g. "gdunit_run". Must not shadow a built-in.
var description: String = ""             ## shown to the agent by the MCP server
var params_schema: Dictionary = {}       ## JSON Schema; advertised to the agent for shaping calls. Params are forwarded UNVALIDATED — the handler must validate its own input.

# --- handler resolution (lazy materialization by dispatcher) ---
var script_path: String = ""             ## "res://addons/.../handler.gd"; load()ed on first call
var method: StringName = &""             ## method on the handler; signature: (params: Dictionary, ctx: McpCallContext) -> Dictionary

# --- source identity (https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #8) ---
var source_path: String = ""             ## "plugin.cfg" path: "res://addons/gdunit4_mcp/plugin.cfg". Same path = same addon (replace allowed); different path colliding = reject + dock warning. NOTE: self-declared — a collision/ownership policy for cooperating addons, NOT a security boundary (any in-editor code can claim any path).
var source: String = ""                  ## display: "gdunit4_mcp". If empty, registry reads [plugin] name from source_path.

# --- exposure ---
var promoted: bool = false               ## opt-in: ask the server to ALSO register this tool as a first-class MCP tool ("custom_<name>") with params_schema attached, so agents get native schemas/validation instead of the custom_manage indirection. The server caps promoted count; overflow stays reachable via custom_manage.

# --- execution contract ---
var timeout_ms: int = 4500               ## deferred timeout → DEFERRED_TIMEOUT_MS_BY_COMMAND["custom:<name>"]
var deferred: bool = false               ## true → handler may return DEFERRED_RESPONSE, push later via ctx.send_deferred(payload)
var requires_writable: bool = false      ## https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #1: readiness gate. false → reads run any time; true → blocks during play/import
var undoable: bool = false               ## https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #6: must be true to participate in undo=true batch_execute

# --- budgets (https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #5, enforced at register time) ---
const MAX_DESCRIPTION_CHARS := 600
const MAX_SCHEMA_BYTES := 8192
const MAX_TIMEOUT_MS := 120000
const MIN_TIMEOUT_MS := 500


## Returns an array of human-readable validation errors (empty = valid).
## Called by McpToolRegistry.register() and usable standalone for early
## feedback in addon _enter_tree before the registry is even live.
func validate() -> Array[String]:
	var errors: Array[String] = []
	if name.is_empty():
		errors.append("name is empty\n")
	if not name.is_valid_ascii_identifier():
		errors.append("name '%s' is not a valid identifier\n" % name)
	if description.length() > MAX_DESCRIPTION_CHARS:
		errors.append("description exceeds %d chars\n" % MAX_DESCRIPTION_CHARS)
	if JSON.stringify(params_schema).to_utf8_buffer().size() > MAX_SCHEMA_BYTES:
		errors.append("params_schema exceeds %d bytes\n" % MAX_SCHEMA_BYTES)
	if script_path.is_empty() or not ResourceLoader.exists(script_path):
		errors.append("script_path '%s' does not exist" % script_path)
	if method.is_empty():
		errors.append("method is empty")
	if timeout_ms < MIN_TIMEOUT_MS or timeout_ms > MAX_TIMEOUT_MS:
		errors.append("timeout_ms %d out of range [%d, %d]" % [timeout_ms, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS])
	if source_path.is_empty() or not source_path.ends_with("plugin.cfg") or not FileAccess.file_exists(source_path):
		errors.append("source_path '%s' must be an existing plugin.cfg path" % source_path)
	return errors