script

type Config struct {
	// StepLimit is the maximum number of Starlark execution steps per script.
	// Prevents infinite loops and runaway computation.
	// Zero uses DefaultStepLimit (100,000).
	StepLimit uint64

	// ParallelMax is the maximum number of concurrent goroutines that
	// parallel() can spawn. Zero means unlimited.
	ParallelMax int
}

type Executor interface {
	// Execute runs a Starlark script with optional named data arguments
	// injected as top-level variables. Tools are already bound from
	// construction and available as callable functions within the script.
	Execute(ctx context.Context, script string, data map[string]interface{}) (*mcp.CallToolResult, error)

	// ToolDescription returns the dynamic description for the
	// execute_tool_script virtual tool definition, listing all available
	// tools and their calling conventions.
	ToolDescription() string
}

type Tool struct {
	// Name is the MCP tool name (e.g., "github-fetch-prs").
	Name string

	// Description is the human-readable tool description.
	Description string

	// Call invokes the tool with the given arguments and returns the MCP result.
	// Arguments are always a string-keyed map. When scripts use positional
	// arguments, they are converted to "arg0", "arg1", etc.
	//
	// The caller is responsible for enforcing per-call timeouts (e.g., by
	// wrapping ctx with context.WithTimeout in the closure). The engine
	// passes the context through but does not apply additional deadlines.
	Call func(ctx context.Context, arguments map[string]interface{}) (*mcp.CallToolResult, error)
}